.. _chapter1:

Chapter 1
=========

First Fortran MUSICA Program
----------------------------
The MUSICA-Fortran API provides access to the MUSICA library within a fortran program.
To get started, let us create a simple program that links
to MUSICA and prints the version of MICM.

  .. literalinclude:: ../../../../fortran/test/unit/test_micm_version.F90
    :language: F90

From the ``musica_micm`` module, we only need the function ``get_micm_version``,
which returns a derived string type from the ``musica_util`` module, ``string_t``.
(The ``string_t`` type will be discussed in more detail in later chapters.)
To print the version string we just want the fortran character array,
accessed by the ``get_char_array`` function.

Now, to build this simple program,
invoke the `gfortran` compiler and link to ``libmusica-fortran``, ``libmusica``, ``yaml-cpp``,
and the standard C++ library ``libstdc++``.
The full command is

.. code-block:: bash

  gfortran -o test_micm_version test_micm_version.F90 -I<MUSICA_DIR>/include -L<MUSICA_DIR>/lib64 -lmusica-fortran -lmusica -lstdc++ -lyaml-cpp

``<MUSICA_DIR>`` is the full path of the MUSICA installation directory,
specified by the option ``CMAKE_INSTALL_PREFIX``
during installation (see :ref:`installing_musica`).
Note that the include path allows the linker to find the ``musica_micm.mod`` and ``musica_util.mod``
module definition files.

When the program is run it should display the MICM version:

.. code-block:: bash

  $ ./test_micm_version
   MICM version 3.12.0
  $

Building a MUSICA Fortran Program with CMake
--------------------------------------------

A minimal ``CMakeLists.txt`` file designed to link the ``musica_fortran`` library
to the ``demo_f.F90`` file described above is exhibited below

  .. literalinclude:: ../../../../fortran/test/tutorial/CMakeLists.txt
    :language: cmake

Common practice is to create a ``build`` subdirectory (relative to the top level ``CMakeLists.txt`` file shown above).

.. code-block:: bash

  mkdir build
  cd build

Then, ``cmake`` can then be invoked with:

.. code-block:: bash

  cmake -DMUSICA_INSTALL_DIR=<MUSICA_DIR> ..
  make

Then, the ``demo_f`` executable can be run:

.. code-block:: bash

  $ ./demo_f
    MICM version 3.12.0
  $
