The PyTrilinos Build System
===========================

The move by Trilinos to the CMake build system has had many advantages
for PyTrilinos.  The two primary advantages being that shared
libraries and python extension libraries can now both be built
automatically by the host build system.  Previously, shared libraries
were built by the PyTrilinos package in an ad-hoc manner, and the
python extension libraries were built using the python distutils
module, which has some reports of portability issues.  The move to
CMake has improved the reliability and robustness of the PyTrilinos
build system.

From a build-system point of view, there are two types of Trilinos
packages that are supported by PyTrilinos: those that are contained
within a single namespace, like Teuchos, Epetra and AztecOO; and those
that are contained within nested namespaces, such as NOX.  These two
types are detailed below, in addition to the ``pytrilinos`` library
and package-specific configuration options.

Single Namespace Packages
-------------------------

All supported packages must be listed in the
``LIB_OPTIONAL_DEP_PACKAGES`` variable in the
``cmake/Dependencies.cmake`` file, and they should be listed in build
order.

The PyTrilinos build system maintains two variables,
``PyTrilnos_PACKAGES`` and ``PyTrilinos_MODULES``, both set in the
top-level ``CMakeLists.txt`` file, to keep track of what to build.
(Note that these variables are referenced as
``${PACKAGE_NAME}_PACKAGES`` and ``${PACKAGE_NAME}_MODULES`` within
``CMakeLists.txt``.)  For single namespace packages, the entries in
these two variables is the same.  For example, ::

    IF(PyTrilinos_ENABLE_Teuchos)
      APPEND_SET(${PACKAGE_NAME}_PACKAGES Teuchos)
      APPEND_SET(${PACKAGE_NAME}_MODULES  Teuchos)
    ENDIF(PyTrilinos_ENABLE_Teuchos)

In this instance, the build system now expects to find a SWIG
interface file in the source directory ``src/Teuchos.i`` that defines
module ``PyTrilinos.Teuchos``.  The end products will be placed in the
build directory ``src/PyTrilinos``::

    src/PyTrilinos/Teuchos.py
    src/PyTrilinos/Teuchos.pyc
    src/PyTrilinos/_Teuchos.so

Nested Namespace Packages
-------------------------

Using ``NOX`` as an example, the ``LIB_OPTIONAL_DEP_PACKAGES``
variable in the ``cmake/Dependencies.cmake`` file should contain the
entry ``NOX`` and it should be listed in build order.

In the top-level ``CMakeLists.txt`` file, the variable
``PyTrilinos_PACKAGES`` should be appended as before, with a single
entry.  But ``PyTrilinos_MODULES`` should contain an entry for each
nested namespace::

    IF(PyTrilinos_ENABLE_NOX)
      APPEND_SET(${PACKAGE_NAME}_PACKAGES NOX)
      APPEND_SET(${PACKAGE_NAME}_MODULES  NOX.__init__  )
      APPEND_SET(${PACKAGE_NAME}_MODULES  NOX.Abstract  )
      APPEND_SET(${PACKAGE_NAME}_MODULES  NOX.StatusTest)
      APPEND_SET(${PACKAGE_NAME}_MODULES  NOX.Solver    )
      IF(NOX_ENABLE_Epetra)
        APPEND_SET(${PACKAGE_NAME}_MODULES NOX.Epetra.__init__ )
        APPEND_SET(${PACKAGE_NAME}_MODULES NOX.Epetra.Interface)
      ENDIF(NOX_ENABLE_Epetra)
    ENDIF(PyTrilinos_ENABLE_NOX)

For every entry in ``PyTrilnos_MODULES``, there should be a
corresponding SWIG file in the source directory::

    src/NOX.__init__.i
    src/NOX.Abstract.i
    src/NOX.StatusTest.i
    src/NOX.Solver.i
    src/NOX.Epetra.__init__.i
    src/NOX.Epetra.Interface.i

which will produce the following build products::

    src/PyTrilinos/NOX/__init__.py
    src/PyTrilinos/NOX/__init__.pyc
    src/PyTrilinos/NOX/___init__.so
    src/PyTrilinos/NOX/Abstract.py
    src/PyTrilinos/NOX/Abstract.pyc
    src/PyTrilinos/NOX/_Abstract.so
    src/PyTrilinos/NOX/StatusTest.py
    src/PyTrilinos/NOX/StatusTest.pyc
    src/PyTrilinos/NOX/_StatusTest.so
    src/PyTrilinos/NOX/Solver.py
    src/PyTrilinos/NOX/Solver.pyc
    src/PyTrilinos/NOX/_Solver.so
    src/PyTrilinos/NOX/Epetra/__init__.py
    src/PyTrilinos/NOX/Epetra/__init__.pyc
    src/PyTrilinos/NOX/Epetra/___init__.so
    src/PyTrilinos/NOX/Epetra/Interface.py
    src/PyTrilinos/NOX/Epetra/Interface.pyc
    src/PyTrilinos/NOX/Epetra/_Interface.so

The ``pytrilinos`` Library
--------------------------

If you develop a module that requires compiled code not generated by
SWIG, it should be put in the ``pytrilinos`` library.  Simply append
entries the the ``HEADERS`` and ``SOURCES`` variables in
``src/CMakeLists.txt`` file.

Package-Specific Configuration Options
--------------------------------------

If you need package-specific configuration options set, they should be
done so in ``src/CMakeLists.txt`` prior to the call to
``PACKAGE_CONFIGURE_FILE()`` and in ``cmake/PyTrilinos_config.h.in``.
Currently, the following variables are set depending upon the
top-level Trilinos configuration::

    HAVE_EPETRA
    HAVE_NOX_EPETRA
    HAVE_NOX_EPETRAEXT
    HAVE_MPI
