Makefiles and compiling BOUT++
==============================

BOUT++ has its own makefile system. These can be used to

#. :ref:`Write an example or executable <sec-executables>`

#. :ref:`Add a feature to BOUT++ <sec-modules>`

In all makefiles, ``BOUT_TOP`` is required!

These makefiles are sufficient for most uses, but for more complicated,
an executable script ``bout-config`` can be used to get the compilation
flags (see :ref:`sec-bout-config`).

.. _sec-executables:

Executables example
-------------------

If writing an example (or physics module that executes) then the
makefile is very simple:

.. code-block:: makefile

    BOUT_TOP        = ../..

    SOURCEC         = <filename>.cxx

    include $(BOUT_TOP)/make.config

where ``BOUT_TOP`` - refers to the relative (or absolute) location of
the BOUT directory (the one that includes ``/lib`` and ``/src``) and
``SOURCEC`` is the name of your file, e.g. ``gas_compress.cxx``.

Optionally, it is possible to specify ``TARGET`` which defines what the
executable should be called (e.g. if you have multiple source files).
That’s it!

Multiple subdirectories
~~~~~~~~~~~~~~~~~~~~~~~

Large physics modules can have many files, and it can be helpful to
organise these into subdirectories. An example of how to do this is in
``examples/make_subdir``.

In the top level, list the directories

.. code-block:: makefile

    DIRS = fuu bar

In the makefile in each subdirectory, specify

.. code-block:: makefile

    TARGET = sub

then specify the path to the top-level directory

.. code-block:: makefile

    MODULE_DIR = ..

and the name of the subdirectory that the makefile is in

.. code-block:: makefile

    SUB_NAME = fuu

.. _sec-modules:

Modules example
---------------

If you are writing a new module (or concrete implementation) to go into
the BOUT++ library, then it is again pretty simple

.. code-block:: makefile

    BOUT_TOP = ../..

    SOURCEC         = communicator.cxx difops.cxx geometry.cxx grid.cxx \
                      interpolation.cxx topology.cxx
    SOURCEH         = $(SOURCEC:%.cxx=%.h)
    TARGET          = lib

    include $(BOUT_TOP)/make.config

``TARGET`` - must be ``lib`` to signify you are adding to
``libbout++.a``.

The other variables should be pretty self explanatory.

Adding a new subdirectory to ’src’
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

No worries, just make sure to edit ``src/makefile`` to add it to the
``DIRS`` variable.

.. _sec-bout-config:

bout-config script
------------------

The ``bout-config`` script is in the ``bin`` subdirectory of the BOUT++
distribution, and is generated by ``configure``. This script can be used
to get the compilers, flags and settings to compile BOUT++. To get a
list of available options:

.. code-block:: bash

    $ bout-config --help

so to get the library linking flags, for example

.. code-block:: bash

    $ bout-config --libs

This script can be used in makefiles to compile BOUT++ alongside other
libraries. The easiest way is to use ``bout-config`` to find the ``make.config``
file which contains the settings. For example the heat conduction example can
be compiled with the following ``makefile``:

.. code-block:: makefile

   SOURCEC         = conduction.cxx
   include $(shell bout-config --config-file)

This includes the ``make.config`` file installed with ``bout-config``, rather than
using the ``BOUT_TOP`` variable.

A different way to use ``bout-config`` is to get the compiler and linker flags,
and use them in your own makefile, for example:

.. code-block:: makefile

   CXX=`bout-config --cxx`
   CFLAGS=`bout-config --cflags`
   LD=`bout-config --ld`
   LDFLAGS=`bout-config --libs

   conduction: conduction.cxx
       $(CXX) $(CFLAGS) -c conduction.cxx -o conduction.o
       $(LD) -o conduction conduction.o $(LDFLAGS)

   
A more general example is in ``examples/make-script``.

