[flang-commits] [flang] 5f8810d - [flang][docs] Initial documentation for the Fortran LLVM Test Suite.

[via flang-commits]

Author: naromero77
Date: 2021-05-26T15:59:55-05:00
New Revision: 5f8810d7b463e085ab24d5443cde7143cae08ddc

URL: https://github.com/llvm/llvm-project/commit/5f8810d7b463e085ab24d5443cde7143cae08ddc
DIFF: https://github.com/llvm/llvm-project/commit/5f8810d7b463e085ab24d5443cde7143cae08ddc.diff

LOG: [flang][docs] Initial documentation for the Fortran LLVM Test Suite.

Describes how to run the Fortran LLVM Test Suite, specifically the external SPEC CPU 2017 Fortran tests.

Reviewed By: rovka

Differential Revision: https://reviews.llvm.org/D102877

Added: 
    flang/docs/FortranLLVMTestSuite.md

Modified: 
    flang/docs/index.md
    llvm/docs/TestSuiteGuide.md

Removed: 
    


################################################################################
diff  --git a/flang/docs/FortranLLVMTestSuite.md b/flang/docs/FortranLLVMTestSuite.md
new file mode 100644
index 0000000000000..ee7ce42928103
--- /dev/null
+++ b/flang/docs/FortranLLVMTestSuite.md
@@ -0,0 +1,60 @@
+# Fortran Tests in the LLVM Test Suite
+
+```eval_rst
+.. contents::
+   :local:
+```
+
+The [LLVM Test Suite](https://github.com/llvm/llvm-test-suite) is a
+separate git repo from the main LLVM project. We recommend that
+first-time users read through [LLVM Test Suite
+Guide](https://llvm.org/docs/TestSuiteGuide.html) which describes the
+organizational structure of the test suite and how to run it.
+
+Although the Flang driver is unable to generate code at this time, we
+are neverthelesss incrementally adding Fortran tests into the LLVM
+Test Suite. We are currently testing against GFortran while we make
+progress towards completing the new Flang driver with full
+code-generation capabilities.
+
+## Running the LLVM test-suite with Fortran
+
+Fortran support can be enabled by setting the following CMake variables:
+```
+% cmake -DCMAKE_Fortran_COMPILER=<path to Fortran compiler> \
+        -DTEST_SUITE_FORTRAN:STRING=ON \
+        -C../test-suite/cmake/caches/O3.cmake \
+        ../test-suite
+```
+
+At the moment, there is only a "hello world" Fortran test. A current
+shortcoming in the design of the test suite is that building the C/C++
+tests is conflated with building and running the Fortran tests,
+i.e. it is not possible to only build and run the Fortran tests with
+the exception of the [External
+tests](https://llvm.org/docs/TestSuiteGuide.html#external-suites).
+
+
+## Running the SPEC CPU 2017
+
+We recently added CMake hooks into the LLVM Test Suite to support
+Fortran tests from [SPEC CPU 2017](https://www.spec.org/cpu2017/). We
+strongly encourage the use of the CMake Ninja (1.10 or later) generator
+due to better support for Fortran module dependency detection. Some of
+the SPEC CPU 2017 Fortran tests, those that are derived from climate
+codes, require support for little-endian/big-endian byte swapping
+capabilities which we automatically detect at CMake configuration
+time.  Note that a copy of SPEC CPU 2017 must be purchased by your
+home institution and is not provided by LLVM.
+
+
+Here is an example of how to build SPEC CPU 2017 with GCC
+
+```
+cmake -G "Ninja" -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ \
+    -DCMAKE_Fortran_COMPILER=gfortran \
+    -DTEST_SUITE_COLLECT_CODE_SIZE:STRING=OFF \
+    -DTEST_SUITE_SUBDIRS:STRING="External/SPEC" \
+    -DTEST_SUITE_FORTRAN:STRING=ON \
+    -DTEST_SUITE_SPEC2017_ROOT=<path to SPEC directory>  ..
+```

diff  --git a/flang/docs/index.md b/flang/docs/index.md
index dc56c387afdc4..d1ea4dc2af953 100644
--- a/flang/docs/index.md
+++ b/flang/docs/index.md
@@ -53,6 +53,7 @@ Flang is LLVM's Fortran frontend
    ArrayComposition
    BijectiveInternalNameUniquing
    DoConcurrent
+   FortranLLVMTestSuite
 ```
 
 # Indices and tables

diff  --git a/llvm/docs/TestSuiteGuide.md b/llvm/docs/TestSuiteGuide.md
index 5fc8774771954..699f9adc39d77 100644
--- a/llvm/docs/TestSuiteGuide.md
+++ b/llvm/docs/TestSuiteGuide.md
@@ -158,6 +158,11 @@ benchmarks. CMake can print a list of them:
   automatically use `path/to/clang++` as the C++ compiler.  See
   [https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html)
 
+- `CMAKE_Fortran_COMPILER`
+
+  Select the Fortran compiler executable to be used. Not set by default and not
+  required unless running the Fortran Test Suite.
+
 - `CMAKE_BUILD_TYPE`
 
   Select a build type like `OPTIMIZE` or `DEBUG` selecting a set of predefined
@@ -165,6 +170,11 @@ benchmarks. CMake can print a list of them:
   option and may be changed by modifying `CMAKE_C_FLAGS_OPTIMIZE` etc.  See
   [https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html)
 
+- `TEST_SUITE_FORTRAN`
+
+  Activate that Fortran tests. This is a work in progress. More information can be
+  found in the [Flang documentation](https://flang.llvm.org/docs/html/FortranLLVMTestSuite.html)
+
 - `TEST_SUITE_RUN_UNDER`
 
   Prefix test invocations with the given tool. This is typically used to run