diff --git a/README.md b/README.md index 1931149e5..94ff0d64a 100644 --- a/README.md +++ b/README.md @@ -40,54 +40,127 @@ git clone https://github.com/fortran-lang/stdlib cd stdlib ``` + ### Requirements -The preprocessor ```fypp``` (https://github.com/aradi/fypp) is needed because metaprogramming is used. -It can be installed using the command line installer ```pip```. +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) +- the [fypp](https://github.com/aradi/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``: + ```sh -pip install fypp +pip install --user fypp cmake ninja ``` +Alternatively, you can install the build tools from the conda-forge channel with the conda package manager: + +```sh +conda config --add channels conda-forge +conda create -n stdlib-tools fypp cmake ninja +conda activate stdlib-tools +``` + +You can install conda using the [miniforge installer](https://github.com/conda-forge/miniforge/releases). +Also, you can install a Fortran compiler from conda-forge by installing the ``fortran-compiler`` package, which installs GFortran. + + +### Supported Compilers + +The following combinations are tested on the default branch of stdlib: + +Name | Version | Platform | Architecture +--- | --- | --- | --- +GCC Fortran | 7, 8, 9, 10 | Ubuntu 18.04 | x86_64 +GCC Fortran | 7, 8, 9, 10 | MacOS Catalina 10.15 | x86_64 +GCC Fortran | 8 | Windows Server 2019 | 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 + +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 | 7.4 | Windows 10 | i686 | [#296](https://github.com/fortran-lang/stdlib/issues/296) +NVIDIA HPC SDK | 20.7, 20.9, 20.11 | Manjaro Linux 20 | x86_64 | [#107](https://github.com/fortran-lang/stdlib/issues/107) +NAG | 7.0 | RHEL | x86_64 | [#108](https://github.com/fortran-lang/stdlib/issues/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. + + ### Build with CMake +Configure the build with + ```sh 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. +- `-DCMAKE_MAXIMUM_RANK` the maximum array rank procedures should be generated for. + The default 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 to `on` in case you want link your application dynamically against the standard library (default: `off`). + +For example, to configure a build using the Ninja backend and generating procedures up to rank 7, which is installed to your home directory use +```sh +cmake -B build -G Ninja -DCMAKE_MAXIMUM_RANK=7 -DCMAKE_INSTALL_PREFIX=$HOME/.local +``` + +To build the standard library run + +```sh cmake --build build +``` +To test your build, run the test suite after the build has finished with + +```sh cmake --build build --target test ``` -### Build with make +Please report failing tests on our [issue tracker](https://github.com/fortran-lang/stdlib/issues/new/choose) including details on the compiler used, the operating system and platform architecture. -Alternatively, you can build using provided Makefiles: +To install the project to the declared prefix run +```sh +cmake --install build ``` -make -f Makefile.manual -``` -## Limiting the maximum rank of generated procedures +Now you have a working version of stdlib you can use for your project. + + +### Build with make -Stdlib's preprocessor (fypp) by default generates specific procedures for arrays of all ranks, up to rank 15. -This can result in long compilation times and, on some computers, exceeding available memory. -If you know that you won't need all 15 ranks, you can specify the maximum rank for which the specific procedures will be generated. -For example, with CMake: +Alternatively, you can build using provided Makefiles: ```sh -cmake -B build -DCMAKE_MAXIMUM_RANK=4 -cmake --build build -cmake --build build --target test +make -f Makefile.manual ``` -or as follows with `make`: + +You can limit the maximum rank by setting ``-DMAXRANK=`` in the ``FYPPFLAGS`` environment variable: ```sh make -f Makefile.manual FYPPFLAGS=-DMAXRANK=4 ``` -Note that currently the minimum value for maximum rank is 4. + ## Documentation -Documentation is a work in progress (see issue #4) but is currently available at https://stdlib.fortran-lang.org. +Documentation is a work in progress (see issue [#4](https://github.com/fortran-lang/stdlib/issues/4)) but already available at [stdlib.fortran-lang.org](https://stdlib.fortran-lang.org). This includes API documentation automatically generated from static analysis and markup comments in the source files using the [FORD](https://github.com/Fortran-FOSS-programmers/ford/wiki) tool, as well as a specification document or ["spec"](https://stdlib.fortran-lang.org/page/specs/index.html) for each proposed feature.