fpx.f

A Fortran preprocessor in Fortran for modern Fortran.
Explore the project »

Introduction

About the Project

Fortran, the venerable language of scientific computing, has powered simulations of galaxies, weather systems, and quantum phenomena for over seven decades. Its enduring strength lies in its clarity, performance, and mathematical soul, qualities that resonate deeply with its community of developers. Yet, nestled within this ecosystem is a contentious tool: the preprocessor. From its ad hoc beginnings in the 1970s to its modern incarnations in tools like cpp, fpp, and fypp, preprocessing has been both a lifeline and a lightning rod for Fortran developers.

It enables portability across diverse platforms, conditional compilation for debugging, and code generation for complex libraries. These capabilities are critical to Fortran’s role in high-performance computing. But it also sparks fierce debate, with many Fortraners decrying its tendency to obscure code, disrupt the language’s elegant simplicity, and introduce bugs.

This project aims at providing a simple, embeddable, open-source preprocessor written in modern Fortran. fpx is mostly compliant to a C preprocessor, fine-tuned for the specificity of the Fortran language. fpx is an embeddable preprocessor. It can be used as a command-line tool or directly embedded into any solution with the module fpx_parser.

fpx supports:

conditional compilation with #if, #ifdef, #ifndef, #elif, #elifdef, #elifndef, #else,#endif
simple macros and function like macros with #define, #undef, defined and !defined
simple arithmetic and bitwise operations with +, -, *, **, /, >, <, >=, =<, ||, &&, |, ^, &, !, ?: and ~.
include files with #include
diagnostic messages with #warning and #error
variadic macros with __VA_ARGS__, and __VA_OPT__,
build-in macros as __LINE__, __FILE__, __FILENAME__, __TIME__, __DATE__, __TIMESTAMP__
stringification # and concatenation ##
and more...

Getting Started

Requirements

To build that library you need

a Fortran 2008 compliant compiler, or better, a Fortran 2018 compliant compiler (Intel Fortran and gfortran compilers are known to work well for fpx.f).

The following compilers are tested on the default branch of fpx.f:

Name	Version	Platform	Architecture
GCC Fortran (MinGW)	14	Windows 10	x86_64
Intel oneAPI classic	2021.5	Windows 10	x86_64

a preprocessor. fpx.f uses some preprocessor macros. It is known to work both with intel fpp and cpp. The goal is for fpx to preproces itself at some point. In particular, the console line application uses the header file 'app.inc' from the 'fortiche' repo.

Unit test rely on the the header file assertion.inc. Since the whole framework fits in a single file, it has been added directly to the repo.

Linting, indentation, and styling is done with fprettify with the following settings

fprettify './src/' -r --case 1 1 1 1 -i 4 --strict-indent --enable-replacements --strip-comments --c-relations

Installation

Get the code

git clone https://github.com/davidpfister/fpx.f

cd fpx.f

Build with fpm

The repo can be build using fpm

fpm build

For convenience, the repo also contains a response file that can be invoked as follows:

fpm @build

(For the Windows users, that command does not work in Powershell since '@' is a reserved symbol. One should use the '–' as follows: fpm --% @build. This is linked to the following issue)

Building with ifort requires to specify the compiler name (gfortran by default)

fpm @build --compiler ifort

Alternatively, the compiler can be set using fpm environment variables.

set FPM_FC=ifort

Besides the build command, several commands are also available:

@pretiffy
system fprettify .\src\ -r --case 1 1 1 1 -i 4 --strict-indent --enable-replacements --strip-comments --c-relations
 
@clean
option clean --all
 
@rebuild
system rmdir /s /q build
option build
 
@build
option build
 
@test
options test --flag 'D_QUIET'
 
@doc
option clean --all
system cd ./.dox & doxygen ./Doxyfile.in & cd ..

The settings to the cpp preprocessor are specified in the file.

[preprocess]
cpp.suffixes = ["F90", "f90"]
cpp.macros = ["_FPM"]

The _FPM macro is used to differentiate the build when compiling with fpm or Visual Studio. This is mostly present to adapt the hard coded paths that differs in both cases.

Build with Visual Studio 2019

The project was originally developed on Windows with Visual Studio 2019. The repo contains the solution file (Fpx.f.sln) to get you started with Visual Studio 2019.

Usage

Command line

The preprocessor fpx can be used from the command-line using your favorite shell. The following options are available:

Option	Definition
-D<macro>	Define a <macro> with no value.
-D<macro>=<val>	Define a <macro> with <val> as its value.
-U<macro>	Undefine <macro>'
-I<dir>	Add <dir> to the end of the global include paths.
-h, -?	Display this help.
-o	Output file path with name and extension.
-v	Display the version of the program.

Using the file preprocessor could not be easier. The function simply takes as arguments the input and output file paths.

Embedded

program test
    use fpx_parser
    
    call preprocess('tests/input.in', 'tests/output.out')
end program

For more examples, please refer to the Documentation

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. So, thank you for considering contributing to fpx.f. Please review and follow these guidelines to make the contribution process simple and effective for all involved. In return, the developers will help address your problem, evaluate changes, and guide you through your pull requests.

By contributing to fpx.f, you certify that you own or are allowed to share the content of your contribution under the same license.

License

Distributed under the MIT License.

Table of Contents