From c90ce54ce3a2de07f0bb00389c37f6dbf81ec930 Mon Sep 17 00:00:00 2001 From: Steve Scalpone Date: Tue, 19 Mar 2019 23:47:18 -0700 Subject: [PATCH] [flang] Update README.md with a list of compilers that are known to compile f18. Explain how to configure LLVM on the cmake cmd line. Add more detail about how to compile with clang++. Original-commit: flang-compiler/f18@e7f678147bc842188d90beafc77e2c84c614239d Reviewed-on: https://github.com/flang-compiler/f18/pull/344 Tree-same-pre-rewrite: false --- flang/README.md | 148 +++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 99 insertions(+), 49 deletions(-) diff --git a/flang/README.md b/flang/README.md index 5b549de..60e894c 100644 --- a/flang/README.md +++ b/flang/README.md @@ -1,47 +1,92 @@ -# f18 +# F18 -F18 is a front-end for Fortran. -It is intended to replace the existing front-end in the Flang compiler. +F18 is a ground-up implementation of a Fortran frontend written in modern C++. +F18, when combined with LLVM, is intended to replace the Flang compiler. -Flang is a Fortran compiler targeting LLVM. Visit the Flang wiki for more information about Flang: +Flang is a Fortran compiler targeting LLVM. +Visit the [Flang wiki](https://github.com/flang-compiler/flang/wiki) +for more information about Flang. -https://github.com/flang-compiler/flang/wiki +## Getting Started -* Read more about f18 in the [documentation directory](documentation). Start with the [compiler overview](documentation/Overview.md). -* To better understand Fortran as a language and the specific grammar accepted by f18, read [Fortran For C Programmers](documentation/FortranForCProgrammers.md) and f18's specifications of the [Fortran grammar](documentation/f2018-grammar.txt) and the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt). Treatment of language extensions is covered in [this document](documentation/Extensions.md). -* To understand the compilers handling of intrinsics, see the [discussion of intrinsics](documentation/Intrinsics.md). -* To understand how an f18 program communicates with libraries at runtime, see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md). -* If you're interested in contributing to the compiler, read the [style guide](documentation/C++style.md) and also review [how f18 uses modern C++ features](documentation/C++17.md). +Read more about f18 in the [documentation directory](documentation). +Start with the [compiler overview](documentation/Overview.md). +To better understand Fortran as a language +and the specific grammar accepted by f18, +read [Fortran For C Programmers](documentation/FortranForCProgrammers.md) +and +f18's specifications of the [Fortran grammar](documentation/f2018-grammar.txt) +and +the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt). +Treatment of language extensions is covered +in [this document](documentation/Extensions.md). + +To understand the compilers handling of intrinsics, +see the [discussion of intrinsics](documentation/Intrinsics.md). + +To understand how an f18 program communicates with libraries at runtime, +see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md). + +If you're interested in contributing to the compiler, +read the [style guide](documentation/C++style.md) +and +also review [how f18 uses modern C++ features](documentation/C++17.md). ## Building F18 -### Selection of the C++ compiler +### Get the Source Code + +``` +cd where/you/want/the/source +git clone https://github.com/flang-compiler/f18.git +``` + +### Supported C++ compilers F18 is written in C++17. The code has been compiled and tested with GCC versions 7.2.0, 7.3.0, 8.1.0, and 8.2.0. -The code has been compiled and tested with clang 6.0 -using either GCC 7.3.0 or 8.1.0 headers; -however, the headers needed small patches. -To build and install f18, there are several options -for specifying the C++ compiler. -You can have the proper C++ compiler on your path, -or you can set the environment variable CXX, -or you can define the variable GCC on the cmake command line. +The code has been compiled and tested with +clang version 7.0 and 8.0 +using either GNU's libstdc++ or LLVM's libc++. + +### LLVM dependency + +F18 uses components from LLVM. + +The instructions to build LLVM can be found at +https://llvm.org/docs/GettingStarted.html. + +We highly recommend using the same compiler to compile both llvm and f18. + +The f18 CMakeList.txt file uses +the variable `LLVM_DIR` to find the installed components. + +To get the correct LLVM libraries included in your f18 build, +define LLVM_DIR on the cmake command line. +``` +LLVM=/lib/cmake/llvm cmake -DLLVM_DIR=$LLVM ... +``` +where `LLVM_INSTALLATION_DIR` is +the top-level directory +where llvm is installed. + +### Building f18 with GCC By default, cmake will search for g++ on your PATH. -The g++ version must be 7.2 or greater in order to build f18. +The g++ version must be one of the supported versions +in order to build f18. -Or, if you export CXX, +Or, cmake will use the variable CXX to find the C++ compiler. CXX should include the full path to the compiler or a name that will be found on your PATH, @@ -49,37 +94,49 @@ e.g. g++-7.2, assuming g++-7.2 is on your PATH. ``` export CXX=g++-7.2 ``` +or +``` +CXX=/opt/gcc-7.2/bin/g++-7.2 cmake ... +``` +There's a third option! +The CMakeList.txt file uses the variable GCC +as the path to the bin directory containing the C++ compiler. -Or, you can reference the GCC installation directory directly. -The CMakeList.txt file -uses the variable GCC -as the path to the bin directory -containing the C++ compiler. GCC can be defined on the cmake command line where `` is the path to a GCC installation with bin, lib, etc: ``` -cmake -DGCC= +cmake -DGCC= ... ``` -To use f18 after it is built, -the environment variables PATH and LD_LIBRARY_PATH -must be set to use GCC and its associated libraries. +### Building f18 with clang -### LLVM and Clang dependency +To build f18 with clang, +cmake needs to know how to find clang++ +and the GCC library and tools that were used to build clang++. -F18 uses components from version 6.0 of LLVM and clang -(even when f18 is not compiled with clang). +The CMakeList.txt file expects either CXX or BUILD_WITH_CLANG to be set. -The instructions to build LLVM and clang can be found at -https://clang.llvm.org/get_started.html. +CXX should include the full path to clang++ +or clang++ should be found on your PATH. +``` +export CXX=clang++ +``` +BUILD_WITH_CLANG can be defined on the cmake command line +where `` +is the path to a clang installation with bin, lib, etc: +``` +cmake -DBUILD_WITH_CLANG= +``` -The f18 CMakeList.txt file uses -the environment variable `Clang_DIR` to find the installed components. +To use f18 after it is built, +the environment variables PATH and LD_LIBRARY_PATH +must be set to use GCC and its associated libraries. -To get the correct LLVM and clang libraries included in your f18 build, -set the environment variable -`Clang_DIR` -to the `lib/cmake/clang` directory in the clang install directory. +Or GCC can be defined on the f18 cmake command line +where `` is the path to a GCC installation with bin, lib, etc: +``` +cmake -DGCC= ... +``` ### Installation Directory @@ -104,16 +161,9 @@ add to the cmake command. Release builds execute quickly. -### Get the Source Code - -``` -cd where/you/want/the/source -git clone https://github.com/flang-compiler/f18.git -``` ### Build F18 ``` cd where/you/want/to/build -export Clang_DIR= cmake where/you/put/the/source/f18 make ``` -- 2.7.4