Addition of tables listing all preprocessing macros and flags

Author: jvdp1

README.md

@@ -252,6 +252,42 @@ 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* (compiler flag `-cpp`/`-fpp`) for conditional compilation
+
+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>`), via `fpm.toml` `preprocess.fypp.macros=["MAXRANK=<n>"]`, or via `python config/fypp_deployment.py --maxrank <n>`. |
+| `VERSION90` |  Enables a more Fortran-90-friendly preprocessing mode (affects defaults such as the maximum rank generated). Can be passed directly 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: `-DWITH_QP=ON/OFF`; fypp deployment script: `--with_qp`. |
+| `WITH_XDP` |  Enables extended double precision code generation (`real(xdp)`, `complex(xdp)`). CMake: `-DWITH_XDP=ON/OFF`; fypp deployment script: `--with_xdp`. |
+| `WITH_ILP64` |  Enables generation of 64-bit integer (ILP64) linear-algebra interfaces (built in addition to the default 32-bit interface). CMake: `-DWITH_ILP64=ON/OFF`; fypp deployment script: `--with_ilp64`. |
+| `PROJECT_VERSION_MAJOR` |  Part of the version string passed into fypp templates. Set automatically by CMake/from `VERSION`, but can be overridden by passing `-DPROJECT_VERSION_MAJOR=<n>` (used by `config/fypp_deployment.py`). |
+| `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_NO_BITSET` |  Disables compilation of the bitsets component. CMake: `-DSTDLIB_NO_BITSET=ON`; or define for the compiler preprocessor (e.g., `-DSTDLIB_NO_BITSET`). This makes `STDLIB_BITSET` evaluate to 0 via `include/macros.inc`. |
+| `STDLIB_BITSET` |  Internal numeric macro (0/1) derived from `STDLIB_NO_BITSET` in `include/macros.inc`. Used in code as `#if STDLIB_BITSET == 1`. Prefer setting `STDLIB_NO_BITSET` rather than defining `STDLIB_BITSET` directly. |
+| `STDLIB_NO_STATS` |  Disables compilation of the statistics component. CMake: `-DSTDLIB_NO_STATS=ON`; or define for the compiler preprocessor (e.g., `-DSTDLIB_NO_STATS`). This makes `STDLIB_STATS` evaluate to 0 via `include/macros.inc`. |
+| `STDLIB_STATS` |  Internal numeric macro (0/1) derived from `STDLIB_NO_STATS` in `include/macros.inc`. Used in code as `#if STDLIB_STATS == 1`. Prefer setting `STDLIB_NO_STATS` rather than defining `STDLIB_STATS` directly. |
+| `STDLIB_EXTERNAL_BLAS` |  Use an external BLAS (32-bit integer interface). Usually set 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` |  Use an external LAPACK (32-bit integer interface). Usually paired with `STDLIB_EXTERNAL_BLAS`. |
+| `STDLIB_EXTERNAL_BLAS_I64` |  Use an external BLAS with ILP64 (64-bit integer) interfaces. Usually paired with `STDLIB_EXTERNAL_LAPACK_I64`. |
+| `STDLIB_EXTERNAL_LAPACK_I64` |  Use an external LAPACK with ILP64 (64-bit integer) interfaces. |
+
+
 ## Using stdlib in your project
 
 ### Using stdlib with CMake