.. toctree::
   :hidden:

.. _buildExtModules:


Building Custom Modules
=======================

Motivation
----------
.. sidebar:: Source Code

   An example external folder with custom Basilisk modules and message definitions can be downloaded
   :download:`here </../../docs/source/install/External.zip>`.


It is recommended that third party modules be created within a single folder external to the basilisk project tree.
This allows one to replace the basilisk project files completely separate from the third party module files.

.. note::

   To learn how to write Basilisk module, see the documentation at :ref:`making-modules`.

Usage
-----
To build external you must pass the file path to cmake

.. code-block:: console

    cmake --preset full -DEXTERNAL_MODULES_PATH="<path-to-external-module-directory>"

Both absolute or relative paths to the external module folder are acceptable.  Let the sample folder with custom
Basilisk code be called ``ExternalModules`` for the sake of this documentation.  Further, assume it is located next to
the Basilisk source directory. From the Basilisk source directory the command line build argument would be:

.. code-block:: console

    cmake --preset full -DEXTERNAL_MODULES_PATH="../<path-to-external-module-directory>/ExternalModules"

Passing the external module's path as above (Xcode, MS Visual Studio or makefile) allows CMake to create build rules
that integrate the external modules as targets along side the Basilisk components build. An IDE shows these under a
folder called ``ExternalModules``.


Directory Structure
-------------------
The external module inclusion follows a strict directory structure resembling the existing Basilisk repository.
A single folder contains all the custom Basilisk modules and message definitions in a specific
sub-folder structure shown below.

::

    custom-modules
    ├── ExternalModules
    ├── _GeneralModuleFiles
    ├── modules
    │   ├── moduleA
    │   │   ├── _UnitTest
    │   │   │   └── test_moduleA.py
    │   │   ├── moduleA.cpp
    │   │   ├── moduleA.h
    │   │   ├── moduleA.i
    │   │   └── moduleA.rst
    │   └── moduleB
    │       ├── _UnitTest
    │       │   └── test_moduleB.py
    │       ├── moduleB.cpp
    │       ├── moduleB.h
    │       ├── moduleB.i
    │       └── moduleB.rst
    └── msgPayloadDef
        ├── msgDefinitionA.h
        └── msgDefinitionB.h

- ``custom-modules``:  This is the parent folder that holds all the custom Basilisk modules, support files and messages.
    Note that this folder can have any name, `custom-modules` is just a sample name here.

- ``ExternalModules``: (required, must have this name) This folder contains sub-folders for each custom Basilisk
    module. This folder contains the typical source code required to build and test a module. The sub-folders have the
    individual module names.

- ``ExternalModules/_GeneralModuleFiles``: (optional, but must have this name) This is useful for source code which
    is shared between the multiple modules. If the answer to the question “Will this code need to be included in more
    than one module?” is yes. Then, that support code belongs in ``_GeneralModuleFiles``. While building external
    modules the Basilisk build system links ``_GeneralModuleFiles`` to these external modules. The files should be
    located directly inside ``_GeneralModulesFiles``, no sub folders are supported in this module.

- ``msgPayloadDef``: (optional, must have this name) This folder contains the definition of all the message
    header files.


Frequently Asked Questions
--------------------------

#. Can I store my custom Basilisk folder on another drive?

- On Linux and macOS, yes.
- On Window this must be on the same drive as the Basilisk source

#. How flexible are the folder names?

- While the primary folder, called ``ExternalModules`` above, can assume any name, the key sub-folders must follow the
  exact naming shown above. If you change this you must write your own ``cmake`` file.

#. How do I import these custom modules when I write a Basilisk python simulation script?

- The custom Basilisk modules are built into a ``Basilisk.ExternalModules`` package.  For example, to load a module
  called ``customCppModule``, use::

        from Basilisk.ExternalModules import customCppModule