Creating a New Module¶

Directory Structure¶

For the purpose of this example, let’s assume we are creating a new module called ‘mod’ (for ‘modeling’). Let’s create a directory named mod under the ‘modules’ directory in the OpenStructure development tree, and populate it with the three subdirectories src, pymod, and tests. Then we add a CMakeLists.txt file in the ‘mod’ directory, consisting of three lines:

add_subdirectory(src)
add_subdirectory(pymod)
add_subdirectory(tests)

The Module Code¶

In the src subdirectory we put the code that implements the functionality of the new module, plus a config.hh header file.

Here is a skeleton of one of the files in the directory , modeling_new_class.hh:

#ifndef OST_MOD_NEW_CLASS_HH
#define OST_MOD_NEW_CLASS_HH

#include <ost/mod/module_config.hh>

// All other necessary includes go here

namespace ost { namespace mod {

class DLLEXPORT_OST_MOD NewClass {
 public:
   void NewMethod();

  // All declarations of NewClass go here

};

}} // namespaces

#endif

And here is the skeleton of the corresponding modeling_new_class.cc file:

#include "modeling_new_class.hh"

using namespace ost::mol;
using namespace ost::mod;

// All other necessary includes and namespace directives
// go here

void NewClass::NewMethod():
{
  // Implementation
}

// Implementation code for NewClass goes here

Obviously, the src directory can contain many files, each implementing classes and functions that will end up in the module. In order to build and stage the module shared library, a CMakeLists.txt file needs to be written for the src directory:

set(OST_MOD_SOURCES
modeling_new_class.cc
// All other source files
)

set(OST_MOD_HEADERS
modeling_new_class.hh
// All other header files
)

 module(NAME mod SOURCES "${OST_MOD_SOURCES}"
        HEADERS ${OST_MOD_HEADERS}
        DEPENDS_ON mol mol_alg)

The line containing the DEPENDS_ON directive lists all the modules on which the new module depends (in this case mol and ost.mol.alg). The module macro will take care of staging the headers, in this case into ost/mod and compiling, linking and staging of a library with the name libost_mod.so (libost_gmod.dylib on macOS).

module(NAME mol SOURCES atom_handle.cc impl/atom_impl.cc
       HEADERS atom_impl.hh IN_DIR impl
       atom_handle.hh)

The module_config.hh header is required for each module to setup the environment on Windows: Each public class, method and function needs to marked with DLLEXPORT or DLLIMPORT to teach the linker where to look for the symbol. The correct use of either DLLIMPORT and DLLEXPORT is depending on the context: While compiling a header file that is part of the same shared library, DLLEXPORT must be used. When compiling a header that is part of an external shared library, DLLIMPORT must be used. A typical module_config header looks like this:

#ifndef OST_MOD_MODULE_CONFIG_HH
#define OST_MOD_MODULE_CONFIG_HH

#include <ost/base.hh>

#if defined(OST_MODULE_OST_MOD)
#  define DLLEXPORT_OST_MOD DLLEXPORT
#else
#  define DLLEXPORT_OST_MOD DLLIMPORT
#endif
#endif

The Testing Framework¶

The tests directory contains code for unit tests. The code is compiled and executed when one invokes compilation using the ‘make check’ command. Tests are run by means of the Boost Unitests Library. Before coding the test routines, the required skeleton needs to be put in place.

The main code is put into ‘tests.cc’, which will become the test executable. There are only 3 lines required

#define BOOST_TEST_DYN_LINK
#define BOOST_TEST_MODULE ost_mod
#include <boost/test/unit_test.hpp>

Based on the two macros BOOST_TEST_DYN_LINK and BOOST_TEST_MODULE, the boost unit test framework will introduce a main function that executes all the unit tests that we will define next.

The definition of the actual unit tests is done in separate .cc files. Create the test_modeling_new_class.cc file and fill it with the following code:

#define BOOST_TEST_DYN_LINK
#include <boost/test/unit_test.hpp>

#include <ost/mod/modeling_new_class.hh>

      using namespace ost;
using namespace ost::mod;


BOOST_AUTO_TEST_SUITE(mod_new_class)

BOOST_AUTO_TEST_CASE(mode_trivial_case)
{
  // ... your test code here...
}

BOOST_AUTO_TEST_CASE(somewhat_more_involved_case)
{
  // ... your test code here...
}

BOOST_AUTO_TEST_SUITE_END()

We again have to define the BOOST_TEST_DYN_LINK macro before including the boost unit test headers. This will tell the boost unit test libraries that we intend to use dynamic linking. Then we include the functions and classes we would like to write unit tests for. In this file, all the normal Boost Test Library macros and functions can be used. (For example BOOST_CHECK, BOOST_FAIL, etc.)

Here is finally the build script skeleton that needs to be put into mod/tests/:

set(OST_MOD_UNIT_TESTS
tests.cc
test_modeling.cc
)

ost_unittest(mod "${OST_MOD_UNIT_TESTS}")
target_link_libraries(ost_mol ost_mol_alg ost_mod)

In the last line the call to the ‘target_link_libraries’ function contains the names of the modules on which the ‘mod’ unit test code depends (in this case, the mol and ost.mol.alg modules), in addition to the mod module itself.

The Python Wrapper¶

Finally, the module API is exported to Python using the Boost Python Library. In mod/pymod, the wrapper code for the classes in the new module is put into a file named wrap_mod.cc:

#include <boost/python.hpp>
using namespace boost::python;

#include <ost/mod/modeling_new_class.hh>

using namespace ost::mol;
using namespace ost::mod;

// All other necessary includes and namespace directives
// go here

BOOST_PYTHON_MODULE(_mod)
{
  class_<NewClass>("NewClass", init<>() )
    .def("NewMethod", &NewClass::NewMethod)
  ;

  // All other Boost Python code goes here
}

The mod/pymod directory must obviously contain a CMakeLists.txt file:

set(OST_MOD_PYMOD_SOURCES
wrap_mod.cc
)

pymod(NAME mod OUTPUT_DIR ost/mod
      CPP ${OST_MOD_PYMOD_SOURCES} PY __init__.py)

The directory should also contain an __init__.py file with the following content:

from _mod import *

In case one wants to implement Python-only functionality for the new module, any number of function definitions can be added to the __init__.py file.

That’s it! The next time the OpenStructure project is compiled, the new module will be built and made available at both the C++ and the Python level.