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

[naromero77]

Summary

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

[rovka]

Thanks for writing this! I left a lot of comments, but most of them are just typos / nitpicks, otherwise it looks good :)

flang/docs/FortranLLVMTestSuite.md

10

Typo: seperate -> separate

13

Nitpick: You can skip the second "describes".

15

This looks like the kind of sentence that's likely to get outdated and confuse people when flang does become capable of generating code. Do we have a better place to put this info? I don't remember if there's any "Current status" document that's constantly updated for flang.

17

Do we have or plan to have a buildbot doing this?

21

Nitpick: I think the other LLVM docs tend to use "test-suite" rather than "TestSuite" or "Test Suite", would be nice to be consistent.

32

Nitpick: I think "shortcoming" is a single word.

35

Typo: the the -> the
Also, this sentence needs a '.' at the end :)

43

Typo: strong -> strongly

46

Typo: requires -> require

[naromero77]

• Fix typos and other grammatical issues.

flang/docs/FortranLLVMTestSuite.md

15

I think that's a good point.

Yes, we mention the current status here:
https://flang.llvm.org/docs/ReleaseNotes.html#introducing-flang

However, I think it would be good to keep this sentence because it adds a bit of context. One might wonder why write a Fortran Test Suite, if there is no compiler driver able to generate code.

Just my opinion. I do need to create a mental note to update this page once Flang can generate code and this version of Flang is upstreamed.

17

A buildbot with GFortran or a buildbot with the throw away driver?

I am not sure that setting up a buildbot with GFortran would be appropriate unless there is precedent for it elsewhere in the project.

It might be worth it for the throw away driver, but I would want one of the higher ups to chime in.

flang/docs/FortranLLVMTestSuite.md

+# 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>  ..
+```

flang/docs/index.md

.. toctree::
    ParserCombinators
    RuntimeDescriptor
    RuntimeTypeInfo
    Calls
    Character
    ArrayComposition
    BijectiveInternalNameUniquing
    DoConcurrent
+   FortranLLVMTestSuite
 ```
 
 # Indices and tables
 
 ```eval_rst
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 ```

llvm/docs/TestSuiteGuide.md

 
 - `CMAKE_C_COMPILER`
 
   Select the C compiler executable to be used. Note that the C++ compiler is
   inferred automatically i.e. when specifying `path/to/clang` CMake will
   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
   compiler flags. These flags are applied regardless of the `CMAKE_C_FLAGS`
   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
   cross-compiled tests within a simulator tool.
 
 - `TEST_SUITE_BENCHMARKING_ONLY`
 
   Disable tests that are unsuitable for performance measurements. The disabled