Is based on CMake and Apache Ant, where Cmake acts as a wrapper for Ant.
CMake is responsible for:
- building main dependency xcodeml-tools;
- getting info about the platform, compilers and installed software;
- processing user-specified build parameters;
- setting up out of source build;
- generating Eclipse IDE projects;
- installation;
- command-line interaction with build-system.
Ant-based solution is responsible for:
- obtaining 3rdparty java libraries;
- compiling java sources;
- generating java libraries (JARs);
- running tests from command-line.
There are 2 ways to interact with the build system:
- command-line interface (CLI);
- initially CMake is used to generate out-of-source build system based on GNU Make (on linux platforms);
- GNU Make commands can be used to run all the important functions, such as build, test and installation;
- integrated development environment (IDE)
- initially CMake is used to configure parts of the source and build system which depend on the platform and user input);
- Eclipse projects can be used for IDE-based development as well as running some of the functions, such as build and test. However, installation can only be performed with CLI.
| Important files | |
|---|---|
| File | Description |
| Collection of variables with build information | |
| Compiler-specific options | |
| Most of the setup and functionality | |
| Other CMakeLists.txt files | Mostly deal with inserting build & platform specific data into source files. |
| Options | |
|---|---|
| Name | Description |
| JAVA_HOME | Path to Java installation |
| CMAKE_INSTALL_PREFIX | Path to target install directory |
| ADD_OMNI_XCODEML_TOOLS_TO_INSTALL | Switch for bundling OMNI with CLAW |
| BUILD_OMNI_XCODEML_TOOLS | Switch to enable OMNI build |
| OMNI_HOME | Path to existing OMNI installation |
As a guideline, avoid Cmake usage, apart from where it is absolutely necessary. Use Ant instead.
Cmake generates GNU Make-based build system, which provides CLI.
| Commands | |
|---|---|
| Cmd | Description |
make |
Build CLAW (and optionally OMNI) |
make install |
Install CLAW (and optionally bundled OMNI) |
make generate-xmods |
Generate xmodules for Fortran modules that are supposed to be included with the compiler. This is a prerequisite for running claw-tests. |
make run-driver-unit-tests |
Run corresponding test project |
make run-driver-tests |
|
make run-cx2t-unit-test |
|
make run-claw-tests |
|
make run-tests |
Run all tests |
While CLI is based on CMake and GNU Make, internally most of the build system functionality is implemented with Apache Ant-based projects. There is a separate project for each distinct part of CLAW. Additionally all of these have a binding to top-level project. Additionally, the common build-specific information and parameters is concentrated in the file <build dir>/cx2t/common/claw.properties , which mostly mirrors variables from properties.cmake. Majority of the projects include this file.
| Projects | ||
|---|---|---|
| Name | Path | Description |
| cx2t | CLAW library | |
| fetch-3rdparty-dependencies | Resolves dependencies on 3rdparty libraries | |
| claw-unit-tests | CLAW unit tests | |
| clawfc | CLAW driver | |
| clawfc-tests | CLAW driver tests | |
| clawfc-unit-tests | CLAW driver unit tests | |
| claw-tests | CLAW tests | |
| solution | Top-level project | |
Eclipse Is fully supported, tested with version 4.14. Each Ant project has a corresponding Eclipse project. They can be imported into IDE from <build_dir>/ide/eclipse. Builds started from IDE will use the Ant build system projects internally. Note that, it always uses Java installation that was specified during configuration with CMake, which does not necessarily match the Java installation used by Eclipse itself. This may lead to problems during debugging, so it is recommended to ensure that the versions match. This can be set centrally in Eclipse settings for all the projects or individually in “project/properties/java compiler/Enable Project specific settings/JDK compliance/use compliance from execution environment…”.
It should be further noted that these projects are not generated by CMake, but rather are produced by configuring template files with CMake variables. As a consequence, each change in the projects structure and dependencies will require manual adjustments of the template files. These can be found in resources/eclipse.
Code should be compatible with automated formatting performed by Eclipse IDE. The rules are defined in file resources/eclipse/java-coding-style.xml, which can be imported into IDE. Note that by default Java Formatter will compress multiline comments. To avoid that, prefix them with “/*-”.
Indent with spaces. NO tabs!
All tests are written JUnit framework. Collections of tests are organized into projects
by topic, which are compiled into JARs using Ant. These can be launched either from cmdline using CMake or with Eclipse,
where it is possible to attach a debugger Additionally, all tests, with exception of claw-unit-tests, have a tests runner
which has an option of running individual testcases, by running the corresponding JAR with 2 arguments
<full name of the test class> <name of the test method>
A guide is available under documentation/developer.
In general, all bash scripts written for the CLAW Compiler projects follow these guidelines.
In addition, all scripts are tested with shellcheck and must pass the tested
without errors or warnings. So warnings might be disable where it make sense
for the correctness of the script.
Note: do not add any new Bash scripts, unless absolutely unavoidable.
- Git hooks present in the
./scripts/git_hooks/directory should be enabled in your local checkout. To enable them, you have to symlink them in the./.git/hooks/directory.
cd .git/hooks
ln -s ../../scripts/pre-commit pre-commitMake sure the file is executable.
The scripts directory contains helper scripts for the development and review process of the project.
Fortran include file
contains ascii text of any kind
Fortran source file
contains ascii text of any kind
Preprocessed Fortran source file
contains valid ascii Fortran source with no preprocessor or Fortran include statements
Fortran Program Unit Information (UnitInfo)
type (Module/Program/Function/Subroutine)
position in Preprocessed Fortran source file
names and positions of used modules
whether claw is used
Fortran File Unit Information (FileUnitInfo)
list of UnitInfo for units contained in preprocessed source file.
List of paths to include files
Path to source file
Path to preprocessed source file
UnitInfo is dependent on:
Fortran source file
Fortran include files [referenced in the source file]
Xmod file
Contains XCodeML header for one Fortran module
Xast file
Contains XCodeML AST information for one Fortran program unit
Output file
contains Fortran Program Unit sources
some, transformed by claw according to input cfg
others copied over from preprocessed source
Verify input options
some combinations are not allowed
some combinations require other options
Verify existence of input files and directories
Verify that input files don't have identical names (even with different file paths)
Process paths of input files
remove duplicates
resolve relative paths [against startup working dir]
Load all available FileUnitInfo files from input FileUnitInfo dirs [-BI]
Discard those that reference non-existing or outdated:
source file
preprocessed-source file
include files
Discard those referencing files outside include source dirs [-SI]
Discard duplicates (those that were generated for the same file)
if not [--skip-pp] given
Load preprocessed sources for files with valid FileUnitInfo
Preprocess all input files for which there is no valid FileUnitInfo [use include dirs -I]
Resolve Fortran include statements [use include dirs -I]
else
after this point, treat input files as if they are already preprocessed
Output preprocessed input files [if output dir -PO given]
if identical, do not output
Scan [=Generate FileUnitInfo] input files that don't have corresponding FileUnitInfo
Output input files FileUnitInfo [if output dir -BO given]
if [--print-claw-files] given
Print names of input files using CLAW and exit
Scan include directories for fortran files [-SI]
if not --skip-pp given
Preprocess all include files for which there is no valid FileUnitInfo
Apply ignore directive to preprocessed-sources
if output dir [-PO] given
Output newly-generated preprocessed include files
else
after this point, include files as if they are already preprocessed
For include files that don't have corresponding FileUnitInfo:
Scan preprocessed include files for FileUnitInfo
Output include files FileUnitInfo [if output dir -BO given]
Load all available xmod files [-MI]
Discard duplicates (same name)
For those that are referenced by FileUnitInfo
discard outdated
Sanity check the build (create build tree starting from units with CLAW in input files)
For all input modules and their dependencies without xmod
Generate xmods (in build tree order)
Output all xmods in the build tree [if output dir -MO given]
For all input units using CLAW [or all units if --force given]
Apply ignore directive [if --skip-pp given]
Apply verbatim directive to module source
Generate XAST
if [--force] given
For all input units NOT using CLAW, without XAST
Generate XAST
Output XAST, for all input units using CLAW [if output dir -XO given]
if [--force] given
Output XAST, for all input units not using CLAW [if output dir -XO given]
For all input units using CLAW
Translate xast using CX2T translator
Output translated XAST (TXAST), for all input units with XAST [if output dir -TXO given]
For all input units with XAST
Generate decompiled source
Undo the effects of ignore and verbatim
Output decompiled source files, for all input modules using CLAW [if output dir -TSO given]
For all input files
Generate output file, which includes (in order they are encountered in input file)
decompiled source for units which have one
preprocessed source for the rest