Merge pull request #1083 from jvdp1/preprocess_table

Addition of tables summarizing preprocessing macros and flags

Author: jvdp1

README.md

@@ -252,6 +252,41 @@ fpm run --example prog
 with `prog` being the name of the example program (e.g., `example_sort`).
 
 
+### Preprocessing macros and flags
+
+`stdlib` uses two preprocessing steps:
+
+- *fypp* for meta-programming (templating and feature selection)
+- *C* preprocessing (activated through compiler flags like `-cpp`(GNU) or `-fpp`(Intel) or use of uppercase file suffix .F90) for conditional compilation
+
+*fypp* preprocessing macros and flags are supported through `CMake` or the `python` script `config/fypp_deployment.py`.
+*C* preprocessing macros and flags are supported through `CMake` and `fpm`.
+
+The table below lists all *fypp* preprocessing macros and flags currently used by `stdlib`:
+
+| Macro/flag Name | Comments |
+| --- | --- |
+| `MAXRANK` |  Maximum array rank generated by templates. Set via CMake `-DCMAKE_MAXIMUM_RANK=<n>` (passed to fypp as `-DMAXRANK=<n>`), or via fypp deployment script `--maxrank <n>`. |
+| `VERSION90` |  Defines the default maximum rank generated when `MAXRANK` is not defined. If defined, the maximum rank generated is 7; otherwise it is 15. Can be passed to fypp as `-DVERSION90` (CMake sets this automatically in some configurations). |
+| `WITH_CBOOL` |  Enables `c_bool` logical support if available. CMake auto-detects this and passes it to fypp; can be overridden at configure time with `-DWITH_CBOOL=ON/OFF`. |
+| `WITH_QP` |  Enables quadruple precision code generation (`real(qp)`, `complex(qp)`). CMake auto-detects this and passes it to fypp; can be overridden at configure time with `-DWITH_QP=ON/OFF`; fypp deployment script: `--with_qp`. |
+| `WITH_XDP` |  Enables extended double precision code generation (`real(xdp)`, `complex(xdp)`). CMake auto-detects this and passes it to fypp; can be overridden at configure time with `-DWITH_XDP=ON/OFF`; fypp deployment script: `--with_xdp`. |
+| `WITH_ILP64` |  Enables generation of 64-bit integer (ILP64) size interfaces for BLAS and LAPACK (in addition to the default 32-bit interface). Set via CMake `-DWITH_ILP64=True` or via  fypp deployment script `--with_ilp64`. |
+| `PROJECT_VERSION_MAJOR` |  Part of the version string passed into fypp templates. Set automatically by CMake from the file `VERSION`. Can be overridden by passing `-DPROJECT_VERSION_MAJOR=<n>`, or via fypp deployment script `--vmajor <n>`. |
+| `PROJECT_VERSION_MINOR` |  See `PROJECT_VERSION_MAJOR`. |
+| `PROJECT_VERSION_PATCH` |  See `PROJECT_VERSION_MAJOR`. |
+
+
+The table below lists all *C preprocessing* macros and flags currently used by `stdlib`:
+
+| Macro/flag Name | Comments |
+| --- | --- |
+| `STDLIB_EXTERNAL_BLAS` |  Links against an external BLAS (32-bit integer interface). Set automatically by CMake when external BLAS/LAPACK are found, or manually via `add_compile_definitions(STDLIB_EXTERNAL_BLAS)`. In fpm: `preprocess.cpp.macros=["STDLIB_EXTERNAL_BLAS"]`. |
+| `STDLIB_EXTERNAL_LAPACK` |  Links against an external LAPACK (32-bit integer interface). Usually paired with `STDLIB_EXTERNAL_BLAS`. |
+| `STDLIB_EXTERNAL_BLAS_I64` |  Links against an external BLAS with ILP64 (64-bit integer) interfaces. Usually paired with `STDLIB_EXTERNAL_LAPACK_I64`. |
+| `STDLIB_EXTERNAL_LAPACK_I64` |  Links against an external LAPACK with ILP64 (64-bit integer) interfaces. |
+
+
 ## Using stdlib in your project
 
 ### Using stdlib with CMake