Adding New Modules to PyTrilinos
================================

If you want to add a Trilinos package as a new module in PyTrilinos,
here are the necessary steps.

#. In file ``cmake/dependencies/TrilinosPackagesDependencies.xml``,
   search for XML element ``<Package name="PyTrilinos" ...>`` and add
   the package name to attribute ``LIB_OPTIONAL_DEP_PACKAGES``.  It is
   important that packages be listed in build order.

#. In the top-level ``CMakeLists.txt`` file, you will find a series of
   if-blocks that look like this::

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

   Add a similar if-block for your new package, making sure it is
   placed in build-order relative to the other packages.  See the
   logic for the ``NOX`` package if your package supports nested
   namespaces (sub-modules).

#. If your package uses nested namespaces, then the python interface
   should use corresponding nested modules.  Supporting this
   infrastructure is detailed in the section .. _`Nested Modules`.

#. If your package will require compiled code that will be archived in
   the ``pytrilinos`` shared library, add the headers and sources to
   ``src/CMakeLists.txt``, using the existing if-blocks as a guide.

#. Add your package by writing the required SWIG interface files.  For
   a standard PACKAGE, it will be in the file

      ``PACKAGE.i``

   For a sub-module within a package that supports nested namespaces,
   the SWIG interface file will be named::

      ``PACKAGE.NAMESPACE.i``

   where ``NAMESPACE`` is the namespace and nested namespaces are
   handled with additional ``.`` characters in the file name.  In both
   cases, of course, ``PACKAGE`` will be replaced with your package
   name.
