diff --git a/WORKFLOW.md b/WORKFLOW.md index e6b32cbb5..c6d72b3b5 100644 --- a/WORKFLOW.md +++ b/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.