Repository files navigation

• Goals and Motivation
• Scope
• Getting started
  • Get the code
  • Requirements
  • Supported compilers
  • Build with CMake
  • Build with fortran-lang/fpm
• Using stdlib in your project
• Documentation
• Contributing
• Links

The Fortran Standard, as published by the ISO (https://wg5-fortran.org/), doesnot have a Standard Library. The goal of this project is to provide a communitydriven and agreed uponde facto "standard" library for Fortran, called aFortran Standard Library (stdlib). We have a rigorous process howstdlib isdeveloped as documented in ourWorkflow.stdlib is both aspecification and a reference implementation. We are cooperating with theFortran Standards Committee (e.g., the effortstarted at the J3committee repository) and the plan is to continue working with the Committee inthe future (such as in the step 5. in theWorkflow document), sothat if the Committee wants to standardize some feature already available instdlib, it wouldbase it onstdlib's implementation.

The goal of the Fortran Standard Library is to achieve the following general scope:

• Utilities (containers, strings, files, OS/environment integration, unittesting & assertions, logging, ...)
• Algorithms (searching and sorting, merging, ...)
• Mathematics (linear algebra, sparse matrices, special functions, fast Fouriertransform, random numbers, statistics, ordinary differential equations,numerical integration, optimization, ...)

git clone https://github.com/fortran-lang/stdlibcd stdlib

To 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)
• thefypp 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 installerpip:

pip install --user fypp cmake ninja

Alternatively, you can install the build tools from the conda-forge channel with the conda package manager:

conda config --add channels conda-forgeconda create -n stdlib-tools fypp cmake ninjaconda activate stdlib-tools

You can install conda using theminiforge installer.Also, you can install a Fortran compiler from conda-forge by installing thefortran-compiler package, which installs GFortran.

The following combinations are tested on the default branch of stdlib:

The following combinations are known to work, but they are not tested in the CI:

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.

Please share your experience with successful and failing builds for compiler/platform/architecture combinations not covered above.

Configure the build with

cmake -B build

You can pass additional options to CMake to customize the build.Important options are

• -G Ninja to use the Ninja backend instead of the default Make backend. Other build backends are available with a similar syntax.
• -DCMAKE_INSTALL_PREFIX is used to provide the install location for the library. If not provided the defaults will depend on your operating system,see here.
• -DCMAKE_MAXIMUM_RANK the 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_LIBS set toon in case you want link your application dynamically against the standard library (default:off).
• -DBUILD_TESTING set tooff in case you want to disable the stdlib tests (default:on).
• -DCMAKE_VERBOSE_MAKEFILE is by default set toOff, but if set toOn will show commands used to compile the code.
• -DCMAKE_BUILD_TYPE is by default set toRelWithDebInfo, which uses compiler flags suitable for code development (but with only-O2 optimization). Beware the compiler flags set this way will override any compiler flags specified viaFFLAGS. To prevent this, use-DCMAKE_BUILD_TYPE=NoConfig in conjunction withFFLAGS.
• -DFIND_BLAS set tooff in case you want to disable finding the external BLAS/LAPACK dependency (default:on).

For example, to configure a build using the Ninja backend while specifying compiler optimization viaFFLAGS, generating procedures up to rank 7, installing to your home directory, using theNoConfig compiler flags, and printing the compiler commands, use

export FFLAGS="-O3"cmake -B build -G Ninja -DCMAKE_MAXIMUM_RANK:String=7 -DCMAKE_INSTALL_PREFIX=$HOME/.local -DCMAKE_VERBOSE_MAKEFILE=On -DCMAKE_BUILD_TYPE=NoConfig

To build the standard library run

cmake --build build

To test your build, run the test suite and all example programs after the build has finished with

cmake --build build --targettest

To test only the test suite, run

ctest --test-dir build/test

Please report failing tests on ourissue tracker including details of the compiler used, the operating system and platform architecture.

To install the project to the declared prefix run

cmake --install build

Now you have a working version of stdlib you can use for your project.

If at some point you wish to recompilestdlib with different options, you mightwant to delete thebuild folder. This will ensure that cached variables fromearlier builds do not affect the new build.

Fortran Package Manager (fpm) is a package manager and build system for Fortran.
You can buildstdlib using providedfpm.toml:

Option 1: From root folder

Asfpm does not currently supportfypp natively,stdlib now proposes a python script to preprocess and build it.This script enables modification of the differentfypp macros available instdlib. The preprocessed files will be dumped at<current_folder>/temp/*.f90 or*.F90.

Make sure to install the dependencies from therequirement.txt

pip install --upgrade -r config/requirements.txt

To build, you can use the following command line:

python config/fypp_deployment.pyfpm build --profile release

or the short-cut

python config/fypp_deployment.py --build

To modify themaxrank macro for instance:

python config/fypp_deployment.py --maxrank 7 --build

To see all the options:

python config/fypp_deployment.py --help

Note: If you use a compiler different than GNU compilers, the script will try to catch it from the environment variablesFPM_FC,FPM_CC,FPM_CXX.

Option 2: From thestdlib-fpm branch which has already been preprocessed with default macros:

git checkout stdlib-fpmfpm build --profile release

Either option you chose for building thestdlib, you can install it with:

fpm install --profile release

The command above will install the following files:

• libstdlib.a into~/.local/lib/ (Unix) orC:\Users\<username>\AppData\Roaming\local\lib\ (Windows)
• all the.[s]mod files produced by the compiler into~/.local/include/ (Unix) orC:\Users\<username>\AppData\Roaming\local\include\ (Windows)

You can change the installation path by setting the prefix option tofpm:

fpm install --profile release --prefix /my/custom/installation/path/

You can use thestdlib by adding the-lstdlib flag to your compiler.If your prefix is a non standard path, add also:

• -L/my/custom/installation/path/lib
• -I/my/custom/installation/path/include

You can run the examples withfpm as:

fpm run --example prog

withprog being the name of the example program (e.g.,example_sort).

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_stdlibREQUIRED)...target_link_libraries(${PROJECT_NAME}PRIVATEfortran_stdlib::fortran_stdlib)

To make the installed stdlib project discoverable add the stdlib directory to theCMAKE_PREFIX_PATH.The usual install location of the package files is$PREFIX/lib/cmake/fortran_stdlib.

To usestdlib within yourfpm project, add the following lines to yourfpm.toml file:

[dependencies]stdlib = {git="https://github.com/fortran-lang/stdlib",branch="stdlib-fpm" }

Warning

Fpm 0.9.0 and later implements stdlib as ametapackage.To include the standard library metapackage, change the dependency to:stdlib = "*".

see also

After the library has been built, it can be included in a regular Makefile.The recommended way to do this is using thepkg-config tool, for which an example is shown below.

# Necessary if the installation directory is not in PKG_CONFIG_PATHinstall_dir := path/to/install_direxportPKG_CONFIG_PATH :=$(install_dir)/lib/pkgconfig:$(PKG_CONFIG_PATH)STDLIB_CFLAGS :=`pkg-config --cflags fortran_stdlib`STDLIB_LIBS :=`pkg-config --libs fortran_stdlib`# Example definition of Fortran compiler and flagsFC := gfortranFFLAGS := -O2 -Wall -g# Definition of targets etc....# Example rule to compile object files from .f90 files%.o:%.f90    $(FC) -c -o $@ $< $(FFLAGS) $(STDLIB_CFLAGS)# Example rule to link an executable from object files%:%.o    $(FC) -o $@ $^ $(FFLAGS) $(STDLIB_LIBS)

The same can also be achieved without pkg-config.If the library has been installed in a directory inside the compiler's search path,only a flag-lfortran_stdlib is required.If the installation directory is not in the compiler's search path, one can add for example

install_dir := path/to/install_dirlibdir :=$(install_dir)/libmoduledir :=$(install_dir)/include/fortran_stdlib/<compiler name and version>

The linker should then look for libraries inlibdir (using e.g.-L$(libdir)) and the compiler should look for module files inmoduledir (using e.g.-I$(moduledir)).Alternatively, the library can also be included from a build directory without installation with

build_dir := path/to/build_dirlibdir :=$(build_dir)/srcmoduledir :=$(build_dir)/src/mod_files

Documentation is a work in progress (see issue#4) but already available atstdlib.fortran-lang.org.This includes API documentation automatically generated from static analysis and markup comments in the source filesusing theFORD 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 thewiki.

stdlib ships full versions of BLAS and LAPACK, for allreal andcomplex kinds, through generalized interface modulesstdlib_linalg_blas andstdlib_linalg_lapack.The 32- and 64-bit implementations may be replaced by external optimized libraries if available, which may allow for faster code.When linking against external BLAS/LAPACK libraries, the user should define macrosSTDLIB_EXTERNAL_BLAS andSTDLIB_EXTERNAL_LAPACK,to ensure that the external library version is used instead of the internal implementation.

• In case of a CMake build, the necessary configuration can be added by ensuring both macros are defined:

  add_compile_definitions(STDLIB_EXTERNAL_BLAS STDLIB_EXTERNAL_LAPACK)

• In case of anfpm build, the stdlib dependency should be set as follows:

  [dependencies]stdlib = {git="https://github.com/fortran-lang/stdlib",branch="stdlib-fpm",preprocess.cpp.macros=["STDLIB_EXTERNAL_BLAS","STDLIB_EXTERNAL_LAPACK"] }

Support for 64-bit integer size interfaces of all BLAS and LAPACK procedures may also be enabledby setting the CMake flag-DWITH_ILP64=True. The 64-bit integer version is always built in addition tothe 32-bit integer version, that is always available. Additional macrosSTDLIB_EXTERNAL_BLAS_I64 andSTDLIB_EXTERNAL_LAPACK_I64
may be defined to link against an external 64-bit integer library, such as Intel MKL.

• In case of anfpm build, 64-bit integer linear algebra support is given via branchstdlib-fpm-ilp64:

  [dependencies]stdlib = {git="https://github.com/fortran-lang/stdlib",branch="stdlib-fpm-ilp64",preprocess.cpp.macros=["STDLIB_EXTERNAL_BLAS_I64","STDLIB_EXTERNAL_LAPACK"] }

• Guidelines
• Issues
• Workflow
• Style guide
• Code of conduct
• License

• Proposals for the Fortran Standard Committee
• US Fortran Standards Committee
• International Fortran Standard Committee