Summarize build toolchain workflow and implied rules (#360)

Co-authored-by: Jeremie Vandenplas <jeremie.vandenplas@gmail.com>

Author: awvwgk

WORKFLOW.md

@@ -59,3 +59,74 @@ PR and proposal was approved by "vast majority".
 
 You are welcome to propose changes to this workflow by opening an
 [issue](https://github.com/fortran-lang/stdlib/issues).
+
+
+## Build system
+
+This project supports two build systems right now, CMake and make.
+Eventually, stdlib will be using the Fortran package manager
+([fpm](https://github.com/fortran-lang/fpm)) as build system as well.
+The effort of supporting fpm is tracked in issue
+[#279](https://github.com/fortran-lang/stdlib/issues/279).
+
+
+### CMake build files
+
+The build files for CMake allow both in-tree, *i.e.* build artifacts share
+the same tree as the source files, and out-of-tree builds, *i.e.* build artifacts
+exist in a separate directory tree.
+Both build types are explicitly supported and tested, the latter strategy
+is recommended for local development.
+
+Sources for the main library target are added in ``src/CMakeLists.txt``
+relative to the library target, *i.e.* no absolute paths are required.
+
+To add tests, the macro ``ADDTEST`` should be used instead of the CMake function
+``add_test``, the macro hides creation of the executable target, linking against the 
+main library target and registering the test.
+The tests themselves are defined as standalone executables in the subdirectories
+in ``src/tests``, a new subdirectory with tests has to be registred in
+``src/tests/CMakeLists.txt``.
+
+The source tree should be considered read-only. References to ``PROJECT_SOURCE_DIR``
+and ``CMAKE_CURRENT_SOURCE_DIR`` should only be used for accessing source files,
+never to write build outputs, use ``PROJECT_BINARY_DIR`` and ``CMAKE_CURRENT_BINARY_DIR``
+to write build artifacts instead.
+To fully support in-tree builds, build artifacts must never have the same name as
+source files to avoid accidentally overwriting them, *e.g.* when preprocessing or
+configuring a file.
+
+The ``CMAKE_INSTALL_PREFIX`` should only be written to on install, never in the build
+process. To install generated files, create a build output in the build tree and
+install it with the ``install`` function.
+This project follows the GNU install conventions, this means that the variables
+``CMAKE_INSTALL_BINDIR``, ``CMAKE_INSTALL_LIBDIR``, and ``CMAKE_INSTALL_INCLUDEDIR``
+must be used instead of ``bin``, ``lib``, and ``include``, respectively.
+Library targets should be exported on install to allow correct inclusion of the
+project in other CMake projects.
+Prefer dashes as in ``project-config`` or ``project-targets`` over camel-case as in
+``projectConfig`` or ``projectTarget`` for file names as the former allows easier
+construction from the ``PROJECT_NAME`` variable by concatenation.
+
+The project is usable as CMake subproject. Explicit references to
+``CMAKE_SOURCE_DIR`` and ``CMAKE_BINARY_DIR`` must be avoided to not
+break subproject builds.
+An example project is available [here](https://github.com/fortran-lang/stdlib-cmake-example)
+to test the CMake subproject integration.
+
+
+### Make build files
+
+The build files for ``make`` are using the name ``Makefile.manual`` to
+not conflict with the in-tree build of CMake.
+This project uses recursive make to transverse the subdirectory structure
+from the top-level makefile, called ``Makefile.manual``, and the build
+happens in-tree, *i.e.* build artifacts are present along with the source code.
+
+New source files are added in ``src/Makefile.manual`` and include manual
+dependency definitions through the object files to allow parallel
+compilation.
+Tests are generated by the make include file ``src/tests/Makefile.manual.test.mk``
+and defined in the subdirectories of the ``src/tests`` as entries in ``PROGS_SRC``.
+New subdirectories have to be explicitly added to ``src/tests/Makefile.manual``
+or are ignored.