[Flang] Update build documentation

[PeteSteinfeld]

Summary

Changes to build instructions based on the latest requirements with
compiler-rt.

[Leporacanthicus]

Mostly being pedantic/nitpicking.

It looks like it's quite complicated, I'd prefer "as simple as possible" cmake commands.

flang/README.md

64–69

Stylistic nit-pick: Perhaps make this an impersonal ("don't use I")?

86–90

Nitpick: If you have done rm -rf on a directory, there's no point in using mkdir -p. [And technically, if you just created the directory, it shouldn't have a build or install directory in it, should it?]

Mostly confusing as there are places below that doesn't use -p

94

This seems unnecessary - assuming your system has a competent C and C++ compiler, cmake ought to pick it up by default.

96–102

Are all of these things required? It looks complicated to me - the command I use isn't trivial, but it's simpler than this [it also limits number of parallel links and a few things, to avoid running low on memory].

129–130

The text above says that clang must be used for compiler-rt?

136

Is compiler-rt incompatible with C++17? Keeping settings as similar as possible is helpful...

168

Should that be standalone?

[tschuett]

I would love to see a more precise target in the future.

> ninja install-flang

Another nice target would be:

> ninja install-flang-headers

[PeteSteinfeld]

Responding to Mats's comments.

[PeteSteinfeld]

@Leporacanthicus , thank you so much for your excellent feedback. Sorry for the delay in responding.

flang/README.md

64–69

Thanks. I'll change it.

86–90

Thanks. I'll change it.

94

It looks like you're correct. I'll get rid of them.

96–102

Yes, I've been able to simplify it. One thing that's not strictly necessary (but handy for debugging) is the -DCMAKE_EXPORT_COMPILE_COMMANDS=ON.

129–130

Good catch. I'll fix this.

136

Good question. I don't know the answer. But I do know that the commands in this document work. I'm not sure how to thoroughly test the results of changing the standard level, so I'm reluctant to change it.

168

In this case, the instructions say to cd to the subdirectory of standalone which is called llvm-project/flang. This directory was created by the git clone command.

[PeteSteinfeld]

@Leporacanthicus, do you require any further changes? If not, can you please approve?

[Leporacanthicus]

LGTM

flang/README.md

 
 If you are interested in writing new documentation, follow
 [LLVM's Markdown style guide](https://github.com/llvm/llvm-project/blob/main/llvm/docs/MarkdownQuickstartTemplate.md).
 
 ## Building flang
 There are two ways to build flang. The first method is to build it at the same
 time that you build all of the projects on which it depends. This is called
 building in tree. The second method is to first do an in tree build to create
-all of the projects on which flang depends, and then only build the flang code
-itself. This is called building standalone. Building standalone has the
-advantage of being smaller and faster. Once you create the base build and base
-install areas, you can create multiple standalone builds using them.
+all of the projects on which flang depends.  Then, after creating this base
+build, only build the flang code itself. This is called building standalone.
+Building standalone has the advantage of being smaller and faster. Once you
+create the base build and base install areas, you can create multiple
+standalone builds using them.
 
 Note that instructions for building LLVM can be found at
 https://llvm.org/docs/GettingStarted.html.
 
+All of the examples below use GCC as the C/C++ compilers and ninja as the build
+tool.
+
 ### Building flang in tree
 Building flang in tree means building flang along with all of the projects on
-which it depends.  These projects include mlir, clang, flang, and compiler-rt.
-Note that compiler-rt is only needed to access libraries that support 16 bit
-floating point numbers.  It's not needed to run the automated tests.
+which it depends.  These projects include mlir, clang, flang, openmp, and
+compiler-rt.  Note that compiler-rt is only needed to access libraries that
+support 16 bit floating point numbers.  It's not needed to run the automated
+tests.  You can use several different C++ compilers for most of the build,
+includig GNU and clang.  But building compiler-rt requres using the clang
+compiler built in the initial part of the build.
+
+Here's a directory structure that works.  Create a root directory for the
+cloned and built files.  Under that root directory, clone the source code
+into a directory called llvm-project.  The build will also
+create subdirectories under the root directory called build (holds most of
+the built files), install (holds the installed files, and compiler-rt (holds
+the result of building compiler-rt).
 
 Here's a complete set of commands to clone all of the necessary source and do
 the build.
 
-First clone the source:
+First, create the root directory and `cd` into it.
+```bash
+mkdir root
+cd root
+
+Now clone the source:
 ```bash
-git clone https://github.com/llvm/llvm-project.git my-project
+git clone https://github.com/llvm/llvm-project.git
 ```
 Once the clone is complete, execute the following commands:
 ```bash
-cd my-project
-
 rm -rf build
-mkdir -p build
+mkdir build
+rm -rf install
+mkdir install
+ROOTDIR=`pwd`
+INSTALLDIR=$ROOTDIR/install
 
 cd build
 
 cmake \
   -G Ninja \
-  ../llvm \
   -DCMAKE_BUILD_TYPE=Release \
-  -DFLANG_ENABLE_WERROR=On \
+  -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
+  -DCMAKE_CXX_STANDARD=17 \
+  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
+  -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
+  -DFLANG_ENABLE_WERROR=ON \
   -DLLVM_ENABLE_ASSERTIONS=ON \
   -DLLVM_TARGETS_TO_BUILD=host \
-  -DCMAKE_INSTALL_PREFIX=$INSTALLDIR
   -DLLVM_LIT_ARGS=-v \
-  -DLLVM_ENABLE_PROJECTS="clang;mlir;flang" \
-  -DLLVM_ENABLE_RUNTIMES="compiler-rt"
+  -DLLVM_ENABLE_PROJECTS="clang;mlir;flang;openmp" \
+  -DLLVM_ENABLE_RUNTIMES="compiler-rt" \
+  ../llvm-project/llvm
 
 ninja
 ```
 
 To run the flang tests on this build, execute the command in the "build"
 directory:
 ```bash
 ninja check-flang
 ```
 
+To create the installed files:
+```bash
+ninja install
+
+echo "latest" > $INSTALLDIR/bin/versionrc
+```
+
+To build compiler-rt:
+```bash
+cd $ROOTDIR
+rm -rf compiler-rt
+mkdir compiler-rt
+cd compiler-rt
+CC=$INSTALLDIR/bin/clang \
+CXX=$INSTALLDIR/bin/clang++ \
+cmake \
+  -G Ninja \
+  ../llvm-project/compiler-rt \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_INSTALL_PREFIX=$INSTALLDIR \
+  -DCMAKE_CXX_STANDARD=11 \
+  -DCMAKE_C_CFLAGS=-mlong-double-128 \
+  -DCMAKE_CXX_CFLAGS=-mlong-double-128 \
+  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
+  -DCOMPILER_RT_BUILD_ORC=OFF \
+  -DCOMPILER_RT_BUILD_XRAY=OFF \
+  -DCOMPILER_RT_BUILD_MEMPROF=OFF \
+  -DCOMPILER_RT_BUILD_LIBFUZZER=OFF \
+  -DCOMPILER_RT_BUILD_SANITIZERS=OFF \
+  -DLLVM_CONFIG_PATH=$INSTALLDIR/bin/llvm-config
+
+ninja
+ninja install
+```
+
 Note that these instructions specify flang as one of the projects to build in
 the in tree build.  This is not strictly necessary for subsequent standalone
 builds, but doing so lets you run the flang tests to verify that the source
 code is in good shape.
 ### Building flang standalone
 To do the standalone build, start by building flang in tree as described above.
 This build is base build for subsequent standalone builds.  Start each
 standalone build the same way by cloning the source for llvm-project:
 ```bash
-git clone https://github.com/llvm/llvm-project.git standalone
+mkdir standalone
+cd standalone
+git clone https://github.com/llvm/llvm-project.git
 ```
 Once the clone is complete, execute the following commands:
 ```bash
-cd standalone
-base=<directory that contains the in tree build>
-
-cd flang
+cd llvm-project/flang
 rm -rf build
 mkdir build
 cd build
 
 cmake \
   -G Ninja \
   -DCMAKE_BUILD_TYPE=Release \
-  -DFLANG_ENABLE_WERROR=On \
+  -DCMAKE_CXX_STANDARD=17 \
+  -DCMAKE_CXX_LINK_FLAGS="-Wl,-rpath,$LD_LIBRARY_PATH" \
+  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
+  -DFLANG_ENABLE_WERROR=ON \
   -DLLVM_TARGETS_TO_BUILD=host \
-  -DLLVM_ENABLE_ASSERTIONS=On \
-  -DLLVM_BUILD_MAIN_SRC_DIR=$base/build/lib/cmake/llvm \
+  -DLLVM_ENABLE_ASSERTIONS=ON \
+  -DLLVM_BUILD_MAIN_SRC_DIR=$ROOTDIR/build/lib/cmake/llvm \
+  -DLLVM_EXTERNAL_LIT=$ROOTDIR/build/bin/llvm-lit \
   -DLLVM_LIT_ARGS=-v \
-  -DLLVM_DIR=$base/build/lib/cmake/llvm \
-  -DCLANG_DIR=$base/build/lib/cmake/clang \
-  -DMLIR_DIR=$base/build/lib/cmake/mlir \
+  -DLLVM_DIR=$ROOTDIR/build/lib/cmake/llvm \
+  -DCLANG_DIR=$ROOTDIR/build/lib/cmake/clang \
+  -DMLIR_DIR=$ROOTDIR/build/lib/cmake/mlir \
   ..
 
 ninja
 ```
 
 To run the flang tests on this build, execute the command in the "flang/build"
 directory:
 ```bash

  --param flang_site_config=<path-to-flang-build>/test-lit/lit.site.cfg.py \
  --param flang_config=<path-to-flang-build>/test-lit/lit.cfg.py \
   <path-to-fortran-test>
 
 ```
 
 Unit tests:
 
-If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`ON` by default), it is possible to generate unittests.
+If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to generate unittests.
 Note: Unit-tests will be skipped for LLVM install for an standalone build as it does not include googletest related headers and libraries.
 
 There are various ways to run unit-tests.
 
 ```
 
 1. ninja check-flang-unit
 2. ninja check-all or ninja check-flang
 3. <path-to-llvm-lit>/llvm-lit \
         test/Unit
 4. Invoking tests from <standalone flang build>/unittests/<respective unit test folder>
 
 ```
 
 
 ## For in tree builds
-If flang was built with `-DFLANG_INCLUDE_TESTS=On` (`On` by default), it is possible to
+If flang was built with `-DFLANG_INCLUDE_TESTS=ON` (`ON` by default), it is possible to
 generate unittests.
 
 To run all of the flang unit tests use the `check-flang-unit` target:
 ```bash
 ninja check-flang-unit
 ```
 To run all of the flang regression tests use the `check-flang` target:
 ```bash
 ninja check-flang
 ```
 
 # How to Generate Documentation
 
 ## Generate FIR Documentation
-If flang was built with `-DLINK_WITH_FIR=On` (`On` by default), it is possible to
+If flang was built with `-DLINK_WITH_FIR=ON` (`ON` by default), it is possible to
 generate FIR language documentation by running `ninja flang-doc`. This will
 create `docs/Dialect/FIRLangRef.md` in flang build directory.
 
 ## Generate Doxygen-based Documentation
 To generate doxygen-style documentation from source code
 - Pass `-DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON` to the cmake command.
 
 ```bash