commit	20fd80920883834ea6f35b3b93d460f9279a2878	[log] [tgz]
author	Peter Steinfeld <psteinfeld@nvidia.com>	Tue Mar 02 07:53:10 2021 -0800
committer	Copybara-Service <copybara-worker@google.com>	Thu Mar 18 00:17:07 2021 -0700
tree	4b39c872201ae786e4a4ca27a2cbb932c66699a5
parent	4c5edef1b7b6b12b8107c3fd21e9dbfd47c8bda4 [diff]

[flang] Detect circularly defined interfaces of procedures

It's possible to define a procedure whose interface depends on a procedure
which has an interface that depends on the original procedure.  Such a circular
definition was causing the compiler to fall into an infinite loop when
resolving the name of the second procedure.  It's also possible to create
circular dependency chains of more than two procedures.

I fixed this by adding the function HasCycle() to the class DeclarationVisitor
and calling it from DeclareProcEntity() to detect procedures with such
circularly defined interfaces.  I marked the associated symbols of such
procedures by calling SetError() on them.  When processing subsequent
procedures, I called HasError() before attempting to analyze their interfaces.
Unfortunately, this did not work.

With help from Tim, we determined that the SymbolSet used to track the
erroneous symbols was instantiated using a "<" operator which was defined using
the location of the name of the procedure.  But the location of the procedure
name was being changed by a call to ReplaceName() between the times that the
calls to SetError() and HasError() were made.  This caused HasError() to
incorrectly report that a symbol was not in the set of erroneous symbols.

I fixed this by changing SymbolSet to be an unordered set that uses the
contents of the name of the symbol as the basis for its hash function.  This
works because the contents of the name of the symbol is preserved by
ReplaceName() even though its location changes.

I also fixed the error message used when reporting recursively defined
dummy procedure arguments by removing extra apostrophes and sorting the
list of symbols.

I also added tests that will crash the compiler without this change.

Note that the "<" operator is used in other contexts, for example, in the map
of characterized procedures, maps of items in equivalence sets, maps of
structure constructor values, ...  All of these situations happen after name
resolution has been completed and all calls to ReplaceName() have already
happened and thus are not subject to the problem I ran into when ReplaceName()
was called when processing procedure entities.

Note also that the implementation of the "<" operator uses the relative
location in the cooked character stream as the basis of its implementation.
This is potentially problematic when symbols from diffent compilation units
(for example symbols originating in .mod files) are put into the same map since
their names will appear in two different source streams which may not be
allocated in the same relative positions in memory.  But I was unable to create
a test that caused a problem.  Using a direct comparison of the content of the
name of the symbol in the "<" operator has problems.  Symbols in enclosing or
parallel scopes can have the same name.  Also using the location of the symbol
in the cooked character stream has the advantage that it preserves the the
order of the symbols in a structure constructor constant, which makes matching
the values with the symbols relatively easy.

This patch supersedes D97749.

Differential Revision: https://reviews.llvm.org/D97774

GitOrigin-RevId: 95540f9dbf0369b3c3ed2fa44371a99440cf79a9

5 files changed

tree: 4b39c872201ae786e4a4ca27a2cbb932c66699a5

README.md

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) with an aim to replace the previous flang project (https://github.com/flang-compiler/flang) and address its various deficiencies. F18 was subsequently accepted into the LLVM project and rechristened as Flang.

Getting Started

Read more about flang in the docs directory. Start with the compiler overview.

To better understand Fortran as a language and the specific grammar accepted by flang, read Fortran For C Programmers and flang's specifications of the Fortran grammar and the OpenMP grammar.

Treatment of language extensions is covered in this document.

To understand the compilers handling of intrinsics, see the discussion of intrinsics.

To understand how a flang program communicates with libraries at runtime, see the discussion of runtime descriptors.

If you're interested in contributing to the compiler, read the style guide and also review how flang uses modern C++ features.

If you are interested in writing new documentation, follow markdown style guide from LLVM.

Supported C++ compilers

Flang is written in C++17.

The code has been compiled and tested with GCC versions from 7.2.0 to 9.3.0.

The code has been compiled and tested with clang version 7.0, 8.0, 9.0 and 10.0 using either GNU‘s libstdc++ or LLVM’s libc++.

The code has been compiled on AArch64, x86_64 and ppc64le servers with CentOS7, Ubuntu18.04, Rhel, MacOs, Mojave, XCode and Apple Clang version 10.0.1.

The code does not compile with Windows and a compiler that does not have support for C++17.

Building Flang out of tree

These instructions are for building Flang separately from LLVM; if you are building Flang alongside LLVM then follow the standard LLVM build instructions and add flang to LLVM_ENABLE_PROJECTS instead, as detailed there.

LLVM dependency

The instructions to build LLVM can be found at 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 flang.

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 flang build, define LLVM_DIR and MLIR_DIR on the cmake command line.

LLVM=<LLVM_BUILD_DIR>/lib/cmake/llvm \
MLIR=<LLVM_BUILD_DIR>/lib/cmake/mlir \
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ...

where LLVM_BUILD_DIR is the top-level directory where LLVM was built.

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 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.

export CXX=g++-8.3

CXX=/opt/gcc-8.3/bin/g++-8.3 cmake ...

Building flang 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++.

CXX should include the full path to clang++ or clang++ should be found on your PATH.

export CXX=clang++

Installation Directory

To specify a custom install location, add -DCMAKE_INSTALL_PREFIX=<INSTALL_PREFIX> to the cmake command where <INSTALL_PREFIX> is the path where flang should be installed.

Build Types

To create a debug build, add -DCMAKE_BUILD_TYPE=Debug to the cmake command. Debug builds execute slowly.

To create a release build, add -DCMAKE_BUILD_TYPE=Release to the cmake command. Release builds execute quickly.

Build Flang out of tree

cd ~/flang/build
cmake -DLLVM_DIR=$LLVM -DMLIR_DIR=$MLIR ~/flang/src
make

Build The New Flang Driver

The new Flang driver, flang-new, is currently under active development and should be considered as an experimental feature. For this reason it is disabled by default. This will change once the new driver replaces the throwaway driver, flang.

In order to build the new driver, add -DFLANG_BUILD_NEW_DRIVER=ON to your CMake invocation line. Additionally, when building out-of-tree, use CLANG_DIR (similarly to LLVM_DIR and MLIR_DIR) to find the installed Clang components.

Note: CLANG_DIR is only required when building the new Flang driver, which currently depends on Clang.

How to Run Tests

Flang supports 2 different categories of tests

Regression tests (https://www.llvm.org/docs/TestingGuide.html#regression-tests)
Unit tests (https://www.llvm.org/docs/TestingGuide.html#unit-tests)

For out of tree builds

To run all tests:

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 flang. The parameters in charge of this are: flang_site_config and flang_config. And they can be set as shown below:

<path-to-llvm-lit>/llvm-lit \
 --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. Note: Unit-tests will be skipped for LLVM install for an out-of-tree build as it does not include googletest related headers and libraries.

There are various ways to run unit-tests.


1. make check-flang-unit
2. make check-all or make check-flang
3. <path-to-llvm-lit>/llvm-lit \
        test/Unit
4. Invoking tests from <out-of-tree 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 generate unittests.

To run all of the flang unit tests use the check-flang-unit target:

make check-flang-unit

To run all of the flang regression tests use the check-flang target:

make 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 generate FIR language documentation by running make 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.

cd ~/llvm-project/build
cmake -DLLVM_ENABLE_DOXYGEN=ON -DFLANG_INCLUDE_DOCS=ON ../llvm
make doxygen-flang

It will generate html in

    <build-dir>/tools/flang/docs/doxygen/html # for flang docs

Generate Sphinx-based Documentation

Flang documentation should preferably be written in markdown(.md) syntax (they can be in reStructuredText(.rst) format as well but markdown is recommended in first place), it is mostly meant to be processed by the Sphinx documentation generation system to create HTML pages which would be hosted on the webpage of flang and updated periodically.

If you would like to generate and view the HTML locally:

Install Sphinx, including the sphinx-markdown-tables extension.
Pass -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF to the cmake command.

cd ~/llvm-project/build
cmake -DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF ../llvm
make docs-flang-html

It will generate html in

   $BROWSER <build-dir>/tools/flang/docs/html/