Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adjust README for upstreaming to llvm. #909

Closed
wants to merge 6 commits into from
Closed

Adjust README for upstreaming to llvm. #909

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
64f097c
Adjust README for upstreaming to llvm.
DavidTruby Jan 7, 2020
0372b99
Changed further F18 references to Flang.
DavidTruby Jan 7, 2020
5d6d22d
Added wording explaining relationship to old flang.
DavidTruby Mar 9, 2020
1c6aec6
Clarify build instructions in README
DavidTruby Apr 6, 2020
61ebcca
Clarify out-of-tree instructions further.
DavidTruby Apr 6, 2020
fbe371d
Reworded text about the previous flang project.
DavidTruby Apr 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
147 changes: 38 additions & 109 deletions README.md
View file
Open in desktop
@@ -1,30 +1,22 @@
<!--===- README.md
# Flang

Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
See https://llvm.org/LICENSE.txt for license information.
SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

-->

# F18

F18 is a ground-up implementation of a Fortran front end 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](https://github.com/flang-compiler/flang/wiki)
for more information about Flang.
Flang is a ground-up implementation of a Fortran front end written in modern
C++. It started off as the f18 project (https://github.com/flang-compiler/f18)
at Nvidia with an aim to replace the old flang project
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say "previous flang project" :-)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to call out NVIDIA, but if you do, please also include the NNSA.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've changed it to not call out anyone in particular, let me know if the new wording is ok!

(https://github.com/flang-compiler/flang) and address its various deficiencies.
F18 was subsequently accepted as the Fortran frontend of LLVM and rechristened
DavidTruby marked this conversation as resolved.
Show resolved Hide resolved
as Flang.

## Getting Started

Read more about f18 in the [documentation directory](documentation).
Read more about flang 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,
and the specific grammar accepted by flang,
read [Fortran For C Programmers](documentation/FortranForCProgrammers.md)
and
f18's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
flang's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
and
the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt).

Expand All @@ -34,26 +26,17 @@ 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,
To understand how a flang 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

### Get the Source Code

```
cd where/you/want/the/source
git clone https://github.com/flang-compiler/f18.git
```
also review [how flang uses modern C++ features](documentation/C++17.md).

### Supported C++ compilers
## Supported C++ compilers

F18 is written in C++17.
Flang 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.
Expand All @@ -62,21 +45,22 @@ 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.
## Building Flang out of tree
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I would put a little intro here saying what these instructions are for and why you might need to follow them. Probably also recommend building in-tree as far easier.

### LLVM dependency

The instructions to build LLVM can be found at
https://llvm.org/docs/GettingStarted.html.
https://llvm.org/docs/GettingStarted.html. If you are building flang as part
of LLVM, follow those instructions and add flang to `LLVM_ENABLE_PROJECTS`.

We highly recommend using the same compiler to compile both llvm and f18.
We highly recommend using the same compiler to compile both llvm and flang.

The f18 CMakeList.txt file uses
The flang CMakeList.txt file uses
the variable `LLVM_DIR` to find the installed LLVM components
and
the variable `MLIR_DIR` to find the installed MLIR components.

To get the correct LLVM and MLIR libraries included in your f18 build,
To get the correct LLVM and MLIR libraries included in your flang build,
define LLVM_DIR and MLIR_DIR on the cmake command line.
```
LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \
Expand All @@ -86,71 +70,17 @@ cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ...
where `LLVM_BUILD_DIR` is
the top-level directory where LLVM was built.

### LLVM dependency when building f18 with Fortran IR

If you do not want to build Fortran IR, add `-DLINK_WITH_FIR=Off` to f18 cmake
command and ignore the rest of this section.

If you intend to build f18 with Fortran IR (`-DLINK_WITH_FIR` On by default),
you must:
- build LLVM with the same compiler and options as the one you are using
to build F18.
- pass `-DCMAKE_CXX_STANDARD=17 -DLLVM_ENABLE_PROJECTS="mlir"`
to LLVM cmake command.
- install LLVM somewhere with `make install` in order to get the required
AddMLIR cmake file (it is not generated in LLVM build directory).

Installing LLVM from packages is most likely not an option as it will not include
MLIR and not be built following C++17 standard.

MLIR is under active development and the most recent development version
may be incompatible. A branch named `f18` is available inside LLVM fork in
https://github.com/flang-compiler/f18-llvm-project. It contains a version of LLVM
that is known be compatible to build f18 with FIR.

The fastest way to get set up is to do:

```
cd where/you/want/to/build/llvm
git clone --depth=1 -b f18 https://github.com/flang-compiler/f18-llvm-project.git
mkdir build
mkdir install
cd build
cmake ../f18-llvm-project/llvm -DCMAKE_BUILD_TYPE=Release \
-DLLVM_ENABLE_PROJECTS=mlir -DCMAKE_CXX_STANDARD=17 \
-DLLVM_INSTALL_UTILS=On \
-DCMAKE_INSTALL_PREFIX=../install
make
make install
```

Then, `-DLLVM_DIR` would have to be set to
`<where/you/want/to/build/llvm>/install/lib/cmake/llvm`
and, `-DMLIR_DIR` would have to be set to
`<where/you/want/to/build/llvm>/install/lib/cmake/mlir`

in f18 cmake command.

To run lit tests,
`-DLLVM_EXTERNAL_LIT=<where/you/want/to/build/llvm>/build/bin/llvm-lit` must be
added to f18 cmake command. This is because `llvm-lit` is not part of
LLVM installation.

Note that when using some advanced options from f18 cmake file it may be
necessary to reproduce their effects in LLVM cmake command.

### Building f18 with GCC
### Building flang with GCC

By default,
cmake will search for g++ on your PATH.
The g++ version must be one of the supported versions
in order to build f18.
in order to build flang.

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++-8.3, assuming g++-8.3 is on your PATH.

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++-8.3, assuming g++-8.3 is on your PATH.
```
export CXX=g++-8.3
```
Expand All @@ -159,9 +89,9 @@ or
CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...
```

### Building f18 with clang
### Building flang with clang

To build f18 with clang,
To build flang with clang,
cmake needs to know how to find clang++
and the GCC library and tools that were used to build clang++.

Expand All @@ -178,7 +108,7 @@ add
`-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
to the cmake command
where `<INSTALL_PREFIX>`
is the path where f18 should be installed.
is the path where flang should be installed.

### Build Types

Expand All @@ -194,29 +124,28 @@ add
to the cmake command.
Release builds execute quickly.

### Build F18
### Build Flang
DavidTruby marked this conversation as resolved.
Show resolved Hide resolved
```
cd ~/f18/build
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/f18/src
cd ~/flang/build
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
make
```

### How to Run the Regression Tests

To run all tests:
```
cd ~/f18/build
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/f18/src
cd ~/flang/build
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
make test check-all
```

To run individual regression tests llvm-lit needs to know the lit
configuration for f18. The parameters in charge of this are:
configuration for flang. The parameters in charge of this are:
flang_site_config and flang_config. And they can be set as shown bellow:
```
<path-to-llvm-lit>/llvm-lit \
--param flang_site_config=<path-to-f18-build>/test-lit/lit.site.cfg.py \
--param flang_config=<path-to-f18-build>/test-lit/lit.cfg.py \
--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>
```

Expand Down