Write a more verbose introduction to building stdlib

README.md

@@ -40,54 +40,126 @@ 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
+--- | --- | --- | --- | ---
+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=<num>`` 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.