Skip to content

Commit

Permalink
[flang] Update README.md with a list of compilers that are known to
Browse files Browse the repository at this point in the history 
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@e7f6781
Reviewed-on: flang-compiler/f18#344
Tree-same-pre-rewrite: false
  • Loading branch information
@sscalpone
sscalpone committed Mar 20, 2019
1 parent f09d979 commit c90ce54
Showing 1 changed file with 99 additions and 49 deletions.
148 changes: 99 additions & 49 deletions flang/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,85 +1,142 @@
<!--
Copyright (c) 2018, NVIDIA CORPORATION. All rights reserved.
Copyright (c) 2018-2019, NVIDIA CORPORATION. All rights reserved.
-->

# 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=<LLVM_INSTALLATION_DIR>/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,
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 `<GCC_DIRECTORY>` is the path to a GCC installation with bin, lib, etc:
```
cmake -DGCC=<GCC_DIRECTORY>
cmake -DGCC=<GCC_DIRECTORY> ...
```

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 `<CLANG_DIRECTORY>`
is the path to a clang installation with bin, lib, etc:
```
cmake -DBUILD_WITH_CLANG=<CLANG_DIRECTORY>
```

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 `<GCC_DIRECTORY>` is the path to a GCC installation with bin, lib, etc:
```
cmake -DGCC=<GCC_DIRECTORY> ...
```

### Installation Directory

Expand All @@ -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=<CLANG_CMAKE_DIRECTORY>
cmake <your custom options> where/you/put/the/source/f18
make
```

0 comments on commit c90ce54

Please sign in to comment.