- Goals and Motivation
- Scope
- Getting started
- Using stdlib in your project
- Documentation
- Contributing
- Links
The Fortran Standard, as published by the ISO (https://wg5-fortran.org/), does
not have a Standard Library. The goal of this project is to provide a community
driven and agreed upon de facto "standard" library for Fortran, called a
Fortran Standard Library (stdlib). We have a rigorous process how stdlib is
developed as documented in our Workflow. stdlib is both a
specification and a reference implementation. We are cooperating with the
Fortran Standards Committee (e.g., the effort
started at the J3
committee repository) and the plan is to continue working with the Committee in
the future (such as in the step 5. in the Workflow document), so
that if the Committee wants to standardize some feature already available in stdlib, it would
base it on stdlib's implementation.
The goal of the Fortran Standard Library is to achieve the following general scope:
- Utilities (containers, strings, files, OS/environment integration, unit testing & assertions, logging, ...)
- Algorithms (searching and sorting, merging, ...)
- Mathematics (linear algebra, sparse matrices, special functions, fast Fourier transform, random numbers, statistics, ordinary differential equations, numerical integration, optimization, ...)
git clone https://github.com/fortran-lang/stdlib
cd stdlibTo build the Fortran standard library you need
- a Fortran 2008 compliant compiler, or better, a Fortran 2018 compliant compiler (GCC Fortran and Intel Fortran compilers are known to work for stdlib)
- CMake version 3.14 or newer (alternatively Make can be used)
- a build backend for CMake, like Make or Ninja (the latter is recommended on Windows)
- the fypp preprocessor (used as meta-programming tool)
If your system package manager does not provide the required build tools, all build dependencies can be installed with the Python command line installer pip:
pip install --user fypp cmake ninjaAlternatively, you can install the build tools from the conda-forge channel with the conda package manager:
conda config --add channels conda-forge
conda create -n stdlib-tools fypp cmake ninja
conda activate stdlib-toolsYou can install conda using the miniforge installer.
Also, you can install a Fortran compiler from conda-forge by installing the fortran-compiler package, which installs GFortran.
The following combinations are tested on the default branch of stdlib:
| Name | Version | Platform | Architecture |
|---|---|---|---|
| GCC Fortran | 9, 10, 11 | Ubuntu 20.04 | x86_64 |
| GCC Fortran | 9, 10, 11 | MacOS Catalina 10.15 | x86_64 |
| GCC Fortran (MSYS) | 10 | Windows Server 2019 | x86_64 |
| GCC Fortran (MinGW) | 10 | Windows Server 2019 | x86_64, i686 |
| Intel oneAPI classic | 2021.1 | Ubuntu 20.04 | x86_64 |
| Intel oneAPI classic | 2021.1 | MacOS Catalina 10.15 | x86_64 |
| Intel oneAPI classic | 2021.1 | Windows 10 | x86_64 |
The following combinations are known to work, but they are not tested in the CI:
| Name | Version | Platform | Architecture |
|---|---|---|---|
| GCC Fortran (MinGW) | 9.3.0, 10.2.0, 11.2.0 | Windows 10 | x86_64, i686 |
We try to test as many available compilers and platforms as possible. A list of tested compilers which are currently not working and the respective issue are listed below.
| Name | Version | Platform | Architecture | Status |
|---|---|---|---|---|
| GCC Fortran | <9 | any | any | #296, #430 |
| NVIDIA HPC SDK | 20.7, 20.9, 20.11 | Manjaro Linux 20 | x86_64 | #107 |
| NAG | 7.0 | RHEL | x86_64 | #108 |
| Intel Parallel Studio XE | 16, 17, 18 | OpenSUSE | x86_64 | failed to compile |
Please share your experience with successful and failing builds for compiler/platform/architecture combinations not covered above.
Configure the build with
cmake -B buildYou can pass additional options to CMake to customize the build. Important options are
-G Ninjato use the Ninja backend instead of the default Make backend. Other build backends are available with a similar syntax.-DCMAKE_INSTALL_PREFIXis used to provide the install location for the library. If not provided the defaults will depend on your operating system, see here.-DCMAKE_MAXIMUM_RANKthe maximum array rank procedures should be generated for. The default value is chosen as 4. The maximum is 15 for Fortran 2003 compliant compilers, otherwise 7 for compilers not supporting Fortran 2003 completely yet. The minimum required rank to compile this project is 4. Compiling with maximum rank 15 can be resource intensive and requires at least 16 GB of memory to allow parallel compilation or 4 GB memory for sequential compilation.-DBUILD_SHARED_LIBSset toonin case you want link your application dynamically against the standard library (default:off).-DBUILD_TESTINGset tooffin case you want to disable the stdlib tests (default:on).
For example, to configure a build using the Ninja backend while specifying compiler flags FFLAGS, generating procedures up to rank 7, and installing to your home directory, use
export FFLAGS="-O3"
cmake -B build -G Ninja -DCMAKE_MAXIMUM_RANK:String=7 -DCMAKE_INSTALL_PREFIX=$HOME/.localTo build the standard library run
cmake --build buildTo test your build, run the test suite after the build has finished with
cmake --build build --target testPlease report failing tests on our issue tracker including details of the compiler used, the operating system and platform architecture.
To install the project to the declared prefix run
cmake --install buildNow you have a working version of stdlib you can use for your project.
If at some point you wish to recompile stdlib with different options, you might want to delete the build folder. This will ensure that cached variables from earlier builds do not affect the new build.
To configure the build, run
cmake -B build -G "Visual Studio 15 2017" -DCMAKE_Fortran_COMPILER=ifort -DCMAKE_GENERATOR_PLATFORM=x64Visual Studio 15 2017 is just an example. -DCMAKE_GENERATOR_PLATFORM={Win32|x64} has to be specified to select the target environment properly.
Other options such as -DCMAKE_MAXIMUM_RANK and -DBUILD_SHARED_LIBS can, of course, be specified.
To build the library, run
cmake --build build --config ReleaseSpecifying the option --config {Debug|Release|MinSizeRel|RelWithDebugInfo} is recommended to select the solution configuration.
The build command has to be run at least twice because Visual Studio cannot recognize source files generated by fypp during the initial build.
The library fortran_stdlib.lib is created in build/src/<Solution Configuration>, and module files are created in build/src/mod_files/<Solution Configuration>. When you choose --config Release, <Solution Configuration> is replaced to Release.
To test the built library, run the test suite in a different way from it mentioned above:
cd build
ctest . -C ReleaseRelease is the solution configuration.
To copy the built modules and library, run
cmake --install build --config Release --prefix path/to/your_project_directoryThe modules are copied to your_project_directory\include, and the library, fortran_stdlib.lib, is copied to your_project_directory\lib.
--config {Debug|Release|MinSizeRel|RelWithDebugInfo} option is necessary to determine <Solution Configuration>.
Install directory can also be specified at configure step with the option -DCMAKE_INSTALL_PREFIX=path/to/your_project_directory. When both options (--prefix and -DCMAKE_INSTALL_PREFIX=) are omitted, the default install directory, C:\Program Files\, is used. An issue related to the permission or the directory name containing a space may occur.
When CMAKE_MAXIMUM_RANK is set to 15, it takes more than 2 hours to build with 3 parallel processes.
If the purpose of the build is to check the procedure of build and link, it is highly recommended to specify -DCMAKE_MAXIMUM_RANK=4 or -DCMAKE_MAXIMUM_RANK=7.
Build with fortran-lang/fpm
Fortran Package Manager (fpm) is a package manager and build system for Fortran.
You can build stdlib using provided fpm.toml:
git checkout stdlib-fpm
fpm build --profile releaseTo use stdlib within your fpm project, add the following lines to your fpm.toml file:
[dependencies]
stdlib = { git="https://github.com/fortran-lang/stdlib", branch="stdlib-fpm" }The stdlib project exports CMake package files and pkg-config files to make stdlib usable for other projects. The package files are located in the library directory in the installation prefix.
For CMake builds of stdlib you can find a local installation with
find_package(fortran_stdlib REQUIRED)
...
target_link_libraries(
${PROJECT_NAME}
PRIVATE
fortran_stdlib::fortran_stdlib
)To make the installed stdlib project discoverable add the stdlib directory to the CMAKE_PREFIX_PATH.
The usual install location of the package files is $PREFIX/lib/cmake/fortran_stdlib.
Documentation is a work in progress (see issue #4) but already available at stdlib.fortran-lang.org. This includes API documentation automatically generated from static analysis and markup comments in the source files using the FORD tool, as well as a specification document or "spec" for each proposed feature.
Some discussions and prototypes of proposed APIs along with a list of popular open source Fortran projects are available on the wiki.