[doc] Update documentation for the build systems feature

docs/advanced.rst

@@ -6,8 +6,8 @@ In this section, we are going to show some more elaborate use cases of ReFrame.
 Through the use of more advanced examples, we will demonstrate further customization options which modify the default options of the ReFrame pipeline.
 The corresponding scripts as well as the source code of the examples discussed here can be found in the directory ``tutorial/advanced``.
 
-Leveraging Makefiles
---------------------
+Working with Makefiles
+----------------------
 
 We have already shown how you can compile a single source file associated with your regression test.
 In this example, we show how ReFrame can leverage Makefiles to build executables.
@@ -40,29 +40,50 @@ The contents of this regression test are the following (``tutorial/advanced/adva
 
 .. literalinclude:: ../tutorial/advanced/advanced_example1.py
 
-The important bit here is the ``compile()`` method.
+The important bit here is how we set up the build system for this test:
 
 .. literalinclude:: ../tutorial/advanced/advanced_example1.py
-  :lines: 18-20
+  :lines: 14-15
   :dedent: 4
 
-As in the simple single source file examples we showed in the `tutorial <tutorial.html>`__, we use the current programming environment's flags for modifying the compilation.
-ReFrame will then compile the regression test source code as by invoking ``make`` as follows:
 
-.. code-block:: bash
+First, we set the build system to ``Make`` and then set the preprocessor flags for the compilation.
+ReFrame will invoke ``make`` as follows:
+
+.. code::
+
+  make -j CC='cc' CXX='CC' FC='ftn' NVCC='nvcc' CPPFLAGS='-DMESSAGE'
+
+The compiler variables (``CC``, ``CXX`` etc.) are set based on the corresponding values specified in the `coniguration of the current environment <configure.html#environments-configuration>`__.
+You may instruct the build system to ignore the default values from the environment by setting the following:
+
+.. code-block:: python
+
+  self.build_system.flags_from_environ = False
+
+In this case, ``make`` will be invoked as follows:
+
+.. code::
+
+  make -j CPPFLAGS='-DMESSAGE'
+
+Notice that the ``-j`` option is always generated.
+If you want to limit build concurrency, you can do it as follows:
+
+.. code-block:: python
 
-  make CC=cc CXX=CC FC=ftn CPPFLAGS=-DMESSAGE
+  self.build_system.max_concurrency = 4
 
-Notice, how ReFrame passes all the programming environment's variables to the ``make`` invocation.
-It is important to note here that, if a set of flags is set to :class:`None` (the default, if not otherwise set in the `ReFrame's configuration <configure.html#environments-configuration>`__), these are not passed to ``make``.
-You can also completely disable the propagation of any flags to ``make`` by setting :attr:`self.propagate = False <reframe.core.environments.ProgEnvironment.propagate>` in your regression test.
 
-At this point it is useful also to note that you can also use a custom Makefile, not named ``Makefile`` or after any other standard Makefile name.
-In this case, you can pass the custom Makefile name as an argument to the compile method of the base :class:`RegressionTest <reframe.core.pipeline.RegressionTest>` class as follows:
+Finally, you may also customize the name of the ``Makefile``.
+You can achieve that by setting the corresponding variable of the ``Make`` build system:
 
 .. code-block:: python
 
-  super().compile(makefile='Makefile_custom')
+  self.build_system.makefile = 'Makefile_custom'
+
+
+More details on ReFrame's build systems, you may find `here <reference.html#build-systems>`__.
 
 
 Retrieving the source code from a Git repository
@@ -97,6 +118,29 @@ ReFrame will attempt to clone this repository inside the stage directory by exec
    You will have to specify it as URL using the ``ssh://`` protocol (see `Git documentation page <https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a>`__).
 
 
+Add a configuration step before compiling the code
+==================================================
+
+It is often the case that a configuration step is needed before compiling a code with ``make``.
+Currently, ReFrame does not provide specific abstractions for "configure-make"-style build systems.
+However, you can achieve the same effect using the :attr:`prebuild_cmd <reframe.core.pipeline.RegressionTest.prebuild_cmd>` for performing the configuration step.
+The following code snippet will configure a code with ``cmake`` before invoking ``make``:
+
+.. code-block:: python
+
+  self.prebuild_cmd = ['cmake -DUSE_LIBNUMA .']
+  self.build_system = 'Make'
+  self.build_system.cppflags = ['-DHAVE_FOO']
+  self.build_system.flags_from_environ = False
+
+The generated build script then will have the following lines:
+
+.. code-block:: bash
+
+  cmake -DUSE_LIBNUMA .
+  make -j CPPFLAGS='-DHAVE_FOO'
+
+
 Implementing a Run-Only Regression Test
 ---------------------------------------
 
@@ -159,10 +203,10 @@ At runtime, ReFrame will generate the following instructions in the shell script
 
 This ensures that the environment of the test is also set correctly at runtime.
 
-Finally, as already mentioned `previously <#leveraging-makefiles>`__, since the ``Makefile`` name is not one of the standard ones, it has to be passed as an argument to the :func:`compile <reframe.core.pipeline.RegressionTest.compile>` method of the base :class:`RegressionTest <reframe.core.pipeline.RegressionTest>` class as follows:
+Finally, as already mentioned `previously <#working-with-makefiles>`__, since the name of the makefile is not one of the standard ones, it must be set explicitly in the build system:
 
 .. literalinclude:: ../tutorial/advanced/advanced_example4.py
-  :lines: 21
+  :lines: 17
   :dedent: 8
 
 Setting a Time Limit for Regression Tests

docs/reference.rst

@@ -96,3 +96,32 @@ Modules System API
 ------------------
 
 .. autoclass:: reframe.core.modules.ModulesSystem
+
+
+Build systems
+-------------
+
+.. versionadded:: 2.14
+
+ReFrame delegates the compilation of the regression test to a `build system`.
+Build systems in ReFrame are entities that are responsible for generating the necessary shell commands for compiling a code.
+Each build system defines a set of attributes that users may set in order to customize their compilation.
+An example usage is the following:
+
+.. code:: python
+
+  self.build_system = 'SingleSource'
+  self.build_system.cflags = ['-fopenmp']
+
+Users simply set the build system to use in their regression tests and then they configure it.
+If no special configuration is needed for the compilation, users may completely ignore the build systems.
+ReFrame will automatically pick one based on the regression test attributes and will try to compile the code.
+
+All build systems in ReFrame derive from the abstract base class :class:`reframe.core.buildsystems.BuildSystem`.
+This class defines a set of common attributes, such us compilers, compilation flags etc. that all subclasses inherit.
+It is up to the concrete build system implementations on how to use or not these attributes.
+
+.. automodule:: reframe.core.buildsystems
+   :members:
+   :exclude-members: BuildSystemField
+   :show-inheritance: