From ece19716d6bbfc1d8beeb86884ca3bf47111c7b8 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Thu, 7 Jan 2021 23:07:15 +0100 Subject: [PATCH 1/4] Write a more verbose introduction to building stdlib - explicitly spell out the requirements on compilers, build system and preprocessor - add a short paragraph on how to install the build dependencies using pip or conda - explain the CMake build step by step - list all important CMake configuration options in the README - add the CMake install command to the build instructions - move the paragraph about the max array rank into the build instructions --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 65 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 1931149e5..a67611dc1 100644 --- a/README.md +++ b/README.md @@ -40,54 +40,101 @@ 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, better a Fortran 2018 compliant compiler + (GCC Fortran or 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 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 from 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``. + + ### 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 setup run the projects testsuite 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. + -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: +### Build with make + +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 alrealy available at 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. From c9f31959287a4e6ea86dad2de1b92dcf46724295 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Fri, 8 Jan 2021 08:14:46 +0100 Subject: [PATCH 2/4] Apply suggested wording and spelling changes Co-authored-by: Milan Curcic --- README.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index a67611dc1..e7060294d 100644 --- a/README.md +++ b/README.md @@ -45,16 +45,16 @@ cd stdlib To build the Fortran standard library you need -- a Fortran 2008 compliant compiler, better a Fortran 2018 compliant compiler - (GCC Fortran or 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) +- 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 cmake ninja +pip install --user fypp cmake ninja ``` Alternatively, you can install the build tools from the conda-forge channel with the conda package manager: @@ -65,8 +65,8 @@ conda create -n stdlib-tools fypp cmake ninja conda activate stdlib-tools ``` -You can install conda from 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``. +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. ### Build with CMake @@ -77,10 +77,10 @@ Configure the build with cmake -B build ``` -you can pass additional options to CMake to customize the 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 +- `-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. @@ -88,7 +88,7 @@ Important options are 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 +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 @@ -100,7 +100,7 @@ To build the standard library run cmake --build build ``` -To test your build setup run the projects testsuite after the build has finished with +To test your build, run the test suite after the build has finished with ```sh cmake --build build --target test @@ -134,7 +134,7 @@ make -f Makefile.manual FYPPFLAGS=-DMAXRANK=4 ## Documentation -Documentation is a work in progress (see issue [#4](https://github.com/fortran-lang/stdlib/issues/4)) but alrealy 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. From 67cd8bfbc05092ef818a9d0a4158b51b94188a83 Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Sat, 9 Jan 2021 22:54:59 +0100 Subject: [PATCH 3/4] Add list of supported compilers/platforms/architectures - list combinations tested in the GH actions CI - list reported failing compilers --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index e7060294d..ff0c767c3 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,31 @@ You can install conda using the [miniforge installer](https://github.com/conda-f 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 +--- | --- | --- | --- | --- +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 From 25cbd1a58ecd1c1fefeb0071bb7c2d8a8fd15c8c Mon Sep 17 00:00:00 2001 From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com> Date: Mon, 11 Jan 2021 10:59:07 +0100 Subject: [PATCH 4/4] Add Windows i686 test failure with GCC 7.4 to README Co-authored-by: Jeremie Vandenplas --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ff0c767c3..94ff0d64a 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,7 @@ A list of tested compilers which are currently not working and the respective is 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