.. _ch02-fortran-makefiles:

=============================================================
Makefiles
=============================================================


Makefile Rules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A makefile takes a set of *rules* in the following format::

  target ... : prerequisites ...
   (tab space) recipe
   (tab space) ...

* A *target* usually refers to a file name that is generated by
  executing your program. This is your outcome from running your code.

* A *prerequisite* is a file that is required as input in order to
  generate the target, which often depends on several files.

* A *recipe* is an action that takes place when ``make`` carries out.
  One very important thing is to put a tab space in front of each recipe.

   

Makeifle examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The directory ``$lecture_note/chapters/chapt02/codes/multifile`` contains a Fortran code
`fullcode.f90` that consists of a main program and two subroutines:

.. literalinclude:: ./codes/multifile/fullcode.f90
   :language: fortran
   :linenos:

To illustrate the construction of a Makefile, we first break this up into
three separate files:

.. literalinclude:: ./codes/multifile/main.f90
   :language: fortran
   :linenos:

.. literalinclude:: ./codes/multifile/sub1.f90
   :language: fortran
   :linenos:

.. literalinclude:: ./codes/multifile/sub2.f90
   :language: fortran
   :linenos:


The directory ``$lecture_note/chapters/chapt02/codes/multifile`` contains several Makefiles
that get successively more sophisticated to compile the codes in this
directory.

In the first version we write out explicitly what to do for each
file. In order to run this ``Makefile``, just type ``make`` as long as your makefile has
a default name ``Makefile`` or ``makefile``:

.. literalinclude:: ./codes/multifile/Makefile
   :language: make
   :linenos:

In the second version there is a general rule for creating `.o` files from
`.f90` files, called *inference rules* (see more `article-inference
<http://www.public.iastate.edu/~akmitra/aero361/design_web/AshWWW/makefiles.pdf>`_),
or *pattern rules* (see more
`article-pattern <https://www.gnu.org/software/make/manual/html_node/Pattern-Rules.html>`_).
There is an old style rule called *suffix rules* which we will not use in our course.
See `article-suffix
<https://www.gnu.org/software/make/manual/html_node/Suffix-Rules.html>`_
for more details. The last line (i.e., recipe) has the special macro
``$<`` which implies the filename of the prerequisite (i.e., ``*.f90``
files). There are seven frequently used core
`macro variables <https://stackoverflow.com/questions/3220277/what-do-the-makefile-symbols-and-mean>`_.
In order to run this non-default ``Makefile2``, you need
to type in ``make -f Makefile2``:

.. literalinclude:: ./codes/multifile/Makefile2
   :language: make
   :linenos:

In the third version we define a macro `OBJECTS` so we only have to write
out this list once, which minimizes the chance of introducing errors:

.. literalinclude:: ./codes/multifile/Makefile3
   :language: make
   :linenos:

In the fourth version, we add a Fortran compile flag (for level 3
optimization) and an linker flag (blank in this example):

.. literalinclude:: ./codes/multifile/Makefile4
   :language: make
   :linenos:

Next we add a ``phony`` target ``clean`` 
that removes the files created when compiling
the code in order to facilitate cleanup.  It is *phony* because it does not
create a file named ``clean``, rather ``clean`` is an *action*.
To run ``clean``, type ``make -f Makefile5 clean``:

.. literalinclude:: ./codes/multifile/Makefile5
   :language: make
   :linenos:

Finally we add a help message so that `make help` says something
useful (you need to type ``make -f Makefile6 help`` for this example):

.. literalinclude:: ./codes/multifile/Makefile6
   :language: make
   :linenos:

Fancier things are also possible, for example automatically detecting all
the `.f90` files in the directory to construct the list of `SOURCES`
and `OBJECTS`:

.. literalinclude:: ./codes/multifile/Makefile7
   :language: make
   :linenos:

Further reading
---------------

* `<http://software-carpentry.org/4_0/make/>`_

* `<http://www.gnu.org/software/make/manual/make.html>`_

* `<http://mrbook.org/tutorials/make/>`_

* `<http://en.wikipedia.org/wiki/Make_%28software%29>`_

* `remake <http://bashdb.sourceforge.net/remake/>`_, a make debugger

* `<https://stackoverflow.com/questions/5950395/makefile-to-compile-multiple-c-programs>`_, a makefile to produce multiple executables