This section explains the structure of an HPX module.
The tool create_library_skeleton.py
can be used to generate a basic skeleton. To create a library skeleton, run the
tool in the
libs subdirectory with the module name as an argument:
This creates a skeleton with the necessary files for an HPX module. It will not create any actual source files. The structure of this skeleton is as follows:
README.rst should be always included which explains the basic purpose of
the library and a link to the generated documentation.
CMakeLists.txt is created in the root directory of the module. By
default it contains a call to
add_hpx_module which takes care of most of the
boilerplate required for a module. You only need to fill in the source and
header files in most cases.
add_hpx_module requires a module name. Optional flags are:
DEPRECATION_WARNINGS: Enables deprecation warnings for the module.
Optional single-value arguments are:
COMPATIBILITY_HEADERS: Can be
OFF, or left out. Enables compatibility headers. Creates a variable which can be turned on or off by the user when set to
OFF. If left out the option is completely disabled.
INSTALL_BINARIES: Install the resulting library.
Optional multi-value arguments-are:
SOURCES: List of source files.
HEADERS: List of header files.
COMPAT_HEADERS: List of compatibility header files.
DEPENDENCIES: Libraries that this module depends on, such as other modules.
CMAKE_SUBDIRS: List of subdirectories to add to the module.
include directory should contain only headers that other libraries need.
For each of those headers, an automatic header test to check for self
containment will be generated. Private headers should be placed under the
src directory. This allows for clear separation. The
may include additional CMake scripts needed to generate the respective build
Compatibility headers (forwarding headers for headers whose location is changed
when creating a module, if moving them from the main library) should be placed
include_compatibility directory. This directory is not created by
Documentation is placed in the
docs folder. A empty skeleton for the index
is created, which is picked up by the main build system and will be part of the
generated documentation. Each header inside the
include directory will
automatically be processed by Doxygen and included into the documentation. If a
header should be excluded from the API reference, a comment
sphinx:undocumented needs to be added.
Tests are placed in suitable subdirectories of
When in doubt, consult existing modules for examples on how to structure the module.