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

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

#. Add the package to the configure script so that PyTrilinos
   recognizes that it can use it.  Within ``configure.ac``, copy and
   paste one of the ::

      TAC_ARG_ENABLE_CAN_USE_PACKAGE

   macros, and modify the arguments for your package.

#. If your package uses nested namespaces, then the python interface
   should use corresponding nested modules.  To partially facilitate
   this, within the ``src/PyTrilinos`` (and/or the
   ``src-boost/PyTrilinos``) directory, make a directory with your
   package name.  Within that directory, create an empty file (via
   ``touch``, for example) named ``.dummy.in``.  At the end of
   ``configure.ac``, modify the ::

      AC_CONFIG_FILES

   macro to include the argument ::

      src/PyTrilinos/PACKAGE/.dummy

   where ``PACKAGE`` is the name of your package (and ``src`` could be
   ``src-boost`` if appropriate).  This may need to be repeated for
   more deeply nested namespaces (such as ``NOX/Epetra``, for
   example).

#. Tell the ``Makefile`` in the source directory (either ``src`` or
   ``src-boost``) to optionally enable the package.  Within
   ``src/Makefile.am``, you will find a series of ``automake``
   directives that look like ::

      @HAVE_PYTRILINOS_TEUCHOS_TRUE@ENABLE_TEUCHOS=true
      @HAVE_PYTRILINOS_TEUCHOS_FALSE@ENABLE_TEUCHOS=

   Copy and paste one of these sets and change (in this example) the
   four occurences of ``TEUCHOS`` to the (all-caps version of the)
   name of your package.

#. Gain access to the exported variables of the package's Makefile.
   Within this same source directory ``Makefile.am``, include the
   package export Makefile.  For example, for Teuchos, you will see
   ::

      # Teuchos
      if HAVE_PYTRILINOS_TEUCHOS
      include $(top_builddir)/../teuchos/Makefile.export.teuchos
      ...
      endif

   Change the case-sensitive Teuchos package names to your
   case-sensitive package names.

#. Within this same ``if`` block within this ``Makefile.am``, set up
   the build variables.  Within the ``src`` directory, these variables
   are ::

      PACKAGE_INTERFACES = ...
      PACKAGE_PROXIES    = ...

   and in the ``src-boost`` directory, they are ::

      PACKAGE_WRAPPERS = ...
      PACKAGE_PROXIES  = ...

   where ``PACKAGE`` is the (all-caps version of the) name of your
   package.  ``PACKAGE_INTERFACES`` should be a space-delimited list
   of swig interface files.  ``PACKAGE_PROXIES`` should be a list of
   python proxy files, each with ``PyTrilinos/`` directory prefix.
   ``PACKAGE_WRAPPERS`` should be a list of boost C++ wrapper files
   that implement the BOOST_PYTHON_MODULE macro.

   Typically, you will have a single swig interface file named after
   your package with a ``.i`` extension; a single python proxy file
   named after you package with a ``.py`` extension; and a single
   boost C++ wrapper named after your package with a ``_wrap.cpp``
   suffix.  In ``src`` you will need to create the ``.i`` file; in
   ``src-boost``, you will have to create both the ``_wrap.cpp`` and
   ``.py`` files.

#. Again, within this same ``Makefile.am``, after these
   package-specific definitions, you will find, for example ::

      PROXIES = ...

   where the right-hand side is a list of all of the individual
   package ``_PROXIES`` variables.  Add you package to this and other
   related lists.

#. This should be sufficient for getting started.  From the
   ``PyTrilinos`` main directory, run the ``bootstrap`` command to
   generate the ``configure`` and ``Makefile.in`` files that will be
   used by the top-level ``configure`` script.
