flang/README.md

   1 <!--===- README.md
   2
   3    Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4    See https://llvm.org/LICENSE.txt for license information.
   5    SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6
   7 -->
   8
   9 # F18
  10
  11 F18 is a ground-up implementation of a Fortran front end written in modern C++.
  12 F18, when combined with LLVM, is intended to replace the Flang compiler.
  13
  14 Flang is a Fortran compiler targeting LLVM.
  15 Visit the [Flang wiki](https://github.com/flang-compiler/flang/wiki)
  16 for more information about Flang.
  17
  18 ## Getting Started
  19
  20 Read more about f18 in the [documentation directory](documentation).
  21 Start with the [compiler overview](documentation/Overview.md).
  22
  23 To better understand Fortran as a language
  24 and the specific grammar accepted by f18,
  25 read [Fortran For C Programmers](documentation/FortranForCProgrammers.md)
  26 and
  27 f18's specifications of the [Fortran grammar](documentation/f2018-grammar.txt)
  28 and
  29 the [OpenMP grammar](documentation/OpenMP-4.5-grammar.txt).
  30
  31 Treatment of language extensions is covered
  32 in [this document](documentation/Extensions.md).
  33
  34 To understand the compilers handling of intrinsics,
  35 see the [discussion of intrinsics](documentation/Intrinsics.md).
  36
  37 To understand how an f18 program communicates with libraries at runtime,
  38 see the discussion of [runtime descriptors](documentation/RuntimeDescriptor.md).
  39
  40 If you're interested in contributing to the compiler,
  41 read the [style guide](documentation/C++style.md)
  42 and
  43 also review [how f18 uses modern C++ features](documentation/C++17.md).
  44
  45 ## Building F18
  46
  47 ### Get the Source Code
  48
  49 ```
  50 cd where/you/want/the/source
  51 git clone https://github.com/flang-compiler/f18.git
  52 ```
  53
  54 ### Supported C++ compilers
  55
  56 F18 is written in C++17.
  57
  58 The code has been compiled and tested with
  59 GCC versions 7.2.0, 7.3.0, 8.1.0, and 8.2.0.
  60
  61 The code has been compiled and tested with
  62 clang version 7.0 and 8.0
  63 using either GNU's libstdc++ or LLVM's libc++.
  64
  65 ### LLVM dependency
  66
  67 F18 uses components from LLVM.
  68
  69 The instructions to build LLVM can be found at
  70 https://llvm.org/docs/GettingStarted.html.
  71
  72 We highly recommend using the same compiler to compile both llvm and f18.
  73
  74 The f18 CMakeList.txt file uses
  75 the variable `LLVM_DIR` to find the installed components.
  76
  77 To get the correct LLVM libraries included in your f18 build,
  78 define LLVM_DIR on the cmake command line.
  79 ```
  80 LLVM=<LLVM_INSTALLATION_DIR>/lib/cmake/llvm cmake -DLLVM_DIR=$LLVM ...
  81 ```
  82 where `LLVM_INSTALLATION_DIR` is
  83 the top-level directory
  84 where llvm is installed.
  85
  86 ### LLVM dependency for lit Regression tests
  87
  88 F18 has tests that use the lit framework, these tests rely on the
  89 presence of llvm tools as llvm-lit, FileCheck, and others.
  90 These tools are installed when LLVM build set:
  91 ```
  92 LLVM_INSTALL_UTILS=On
  93 ```
  94 to run the regression tests on f18.
  95
  96 ### Building f18 with GCC
  97
  98 By default,
  99 cmake will search for g++ on your PATH.
 100 The g++ version must be one of the supported versions
 101 in order to build f18.
 102
 103 Or,
 104 cmake will use the variable CXX to find the C++ compiler.
 105 CXX should include the full path to the compiler
 106 or a name that will be found on your PATH,
 107 e.g. g++-7.2, assuming g++-7.2 is on your PATH.
 108 ```
 109 export CXX=g++-7.2
 110 ```
 111 or
 112 ```
 113 CXX=/opt/gcc-7.2/bin/g++-7.2 cmake ...
 114 ```
 115 There's a third option!
 116 The CMakeList.txt file uses the variable GCC
 117 as the path to the bin directory containing the C++ compiler.
 118
 119 GCC can be defined on the cmake command line
 120 where `<GCC_DIRECTORY>` is the path to a GCC installation with bin, lib, etc:
 121 ```
 122 cmake -DGCC=<GCC_DIRECTORY> ...
 123 ```
 124
 125 ### Building f18 with clang
 126
 127 To build f18 with clang,
 128 cmake needs to know how to find clang++
 129 and the GCC library and tools that were used to build clang++.
 130
 131 The CMakeList.txt file expects either CXX or BUILD_WITH_CLANG to be set.
 132
 133 CXX should include the full path to clang++
 134 or clang++ should be found on your PATH.
 135 ```
 136 export CXX=clang++
 137 ```
 138 BUILD_WITH_CLANG can be defined on the cmake command line
 139 where `<CLANG_DIRECTORY>`
 140 is the path to a clang installation with bin, lib, etc:
 141 ```
 142 cmake -DBUILD_WITH_CLANG=<CLANG_DIRECTORY>
 143 ```
 144 Or GCC can be defined on the f18 cmake command line
 145 where `<GCC_DIRECTORY>` is the path to a GCC installation with bin, lib, etc:
 146 ```
 147 cmake -DGCC=<GCC_DIRECTORY> ...
 148 ```
 149 To use f18 after it is built,
 150 the environment variables PATH and LD_LIBRARY_PATH
 151 must be set to use GCC and its associated libraries.
 152
 153 ### Installation Directory
 154
 155 To specify a custom install location,
 156 add
 157 `-DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX>`
 158 to the cmake command
 159 where `<INSTALL_PREFIX>`
 160 is the path where f18 should be installed.
 161
 162 ### Build Types
 163
 164 To create a debug build,
 165 add
 166 `-DCMAKE_BUILD_TYPE=Debug`
 167 to the cmake command.
 168 Debug builds execute slowly.
 169
 170 To create a release build,
 171 add
 172 `-DCMAKE_BUILD_TYPE=Release`
 173 to the cmake command.
 174 Release builds execute quickly.
 175
 176 ### Build F18
 177 ```
 178 cd ~/f18/build
 179 cmake -DLLVM_DIR=$LLVM ~/f18/src
 180 make
 181 ```
 182
 183 ### How to Run the Regression Tests
 184
 185 To run all tests:
 186 ```
 187 cd ~/f18/build
 188 cmake -DLLVM_DIR=$LLVM ~/f18/src
 189 make check-all
 190 ```
 191
 192 To run individual regression tests llvm-lit needs to know the lit
 193 configuration for f18. The parameters in charge of this are:
 194 flang_site_config and flang_config. And they can be set as shown bellow:
 195 ```
 196 <path-to-llvm-lit>/llvm-lit \
 197  --param flang_site_config=<path-to-f18-build>/test-lit/lit.site.cfg.py \
 198  --param flang_config=<path-to-f18-build>/test-lit/lit.cfg.py \
 199   <path-to-fortran-test>
 200 ```