.. _Config Intro:


Introduction to Configuration
*****************************

Use Fab to build your Fortran and C project using a series of *build steps*
written in Python.

Here is an example of a build configuration. It uses some ready made
configurable steps provided by Fab, and it's easy to create your own custom
steps.

.. code-block::
    :linenos:

    from fab.build_config import BuildConfig
    from fab.steps.analyse import analyse
    from fab.steps.compile_fortran import compile_fortran
    from fab.steps.find_source_files import find_source_files
    from fab.steps.grab.folder import grab_folder
    from fab.steps.link import link_exe
    from fab.steps.preprocess import preprocess_fortran

    with BuildConfig(project_label='<project label>') as state:
        grab_folder(state, src='<path to source folder>')
        find_source_files(state)
        preprocess_fortran(state)
        analyse(state, find_programs=True)
        compile_fortran(state)
        link_exe(state)

.. note::

    The :func:`find_programs<fab.steps.analyse.analyse>` tells the analysis
    step to discover all Fortran "program" program units and C "main" functions.

    If you prefer to specify which programs are to be built you may specify
    them using the ``root_symbol`` argument instead. It takes a list of program
    names.

Fab is designed to minimise user input by providing sensible defaults.
Thus it knows to use the :term:`build tree` created by the preceding step as
input for the subsequent step.

Build steps can read and create named collections in the :term:`Artefact Store`.
For example, in the snippet above we don't tell the compiler which files to compile, that is generated by previous steps.

More details about steps can be found in the :ref:`guide to writing configuration<Writing Config>`.