You are reading the documentation for version 3.0 of ProMod3.
You may also want to read the documentation for:
1.3
2.0
2.1
3.1
3.2
ProMod3‘s Share Of CMake
Introduction
This section describes the set of ProMod3‘s own set of CMake functions (or
macros) fed from the cmake_support directory. Those could be easily put
into three categories of varying relevance for you:
- Functions used to integrate your contribution into ProMod3. Its all about
adding files to the documentation, declaring unit tests and code management.
Almost all of them have their home in the file
PROMOD3.cmake .
- Then there is a set of functions needed to set up CMake itself. Those are
little helpers to find tools, external packages and such. These are found in
Find<DEPENDENCY>.cmake files.
- The last and probably least relevant category for you is also to be found in
PROMOD3.cmake . There is a set of functions used to define more
CMake functionality. You only need to consider those if you dare to extend
this set up.
Best practices for using our home-brew CMake functions are found in the
various CMakeLists.txt files in the project’s directory tree.
Functions For Module/ Action Maintenance
Module definition
Default dependencies in a module NAME :
_NAME depends on NAME_pymod and promod3_NAME (if that exists)
promod3_NAME depends on promod3_NAME_headers
-
module
module(NAME name
SOURCES source1 source2
HEADERS header1 header2 [IN_DIR dir]
[header3 header4 [IN_DIR dir]]
[DEPENDS_ON dep1 dep2]
[HEADER_OUTPUT_DIR dir]
[LINK link_cmds])
Define a ProMod3 module from a set of C++ files. This will define the
following make targets (where NAME is the provided module name):
promod3_NAME : builds library libpromod3_NAME
promod3_NAME_headers : copies all header files
The parameters are:
NAME
- Specify the name of the module.
SOURCES
- Set of C++ source files to be compiled.
HEADERS
- Set of C++ header files to be copied. If the headers are located in
a different directory than the current one, you must group them by directory
and provide the directory name
dir with IN_DIR dir after listing the
header files in said directory.
DEPENDS_ON
- Add dependencies on other targets (e.g.
promod3_MOD for another
ProMod3 module).
HEADER_OUTPUT_DIR
- Define alternative folder to which to copy header files. Default is
promod3/NAME .
LINK
- Add dependencies to external libraries. You may use some predefines set of
libraries here, such as
${OST_LIBRARIES} and ${BOOST_LIBRARIES} .
-
pymod
pymod(NAME name
CPP source1 source2
PY source source2 [IN_DIR dir]
[source3 source4 [IN_DIR dir]]
[TRANSLATE dict END_TRANSLATE]
[OUTPUT_DIR dir]
[DEPENDS_ON dep1 dep2]
[NEED_CONFIG_HEADER])
Define the Python interface of a ProMod3 module from a set of C++
wrappers and/or Python files. This will define the following make targets
(where NAME is the provided module name):
_NAME : builds library _NAME for Python wrapper around C++
NAME_pymod : copies (and/or translates) all Python files
The parameters are:
NAME
- Specify the name of the module.
CPP
- Set of C++ source files to be compiled.
PY
Set of Python source files to be copied. If the files are located in
a different directory than the current one, you must group them by directory
and provide the directory name dir with IN_DIR dir after listing the
header files in said directory.
If a Python source file needs to be translated by CMake, provide the
dictionary after putting TRANSLATE . This assumes a <FILE>.py.in for
<FILE>.py . END_TRANSLATE marks the end of the translation
dictionary.
OUTPUT_DIR
- Define alternative folder (within Python tree) to place python files.
Default is
promod3/NAME .
DEPENDS_ON
- Add dependencies on other targets (e.g.
promod3_MOD for another
ProMod3 module).
NEED_CONFIG_HEADER
- Makes the module depending on the config_header target, which provides the
headers in the
config directory.
-
convert_module_data
convert_module_data(MODULE name
FILE file
SCRIPT script
[ARGS args])
Use a Python script to convert a portable binary file to a non-portable one.
Calls python SCRIPT in_path out_path ARGS (with access to OST and
ProMod3),
where in_path = portable_FILE
(within path of current CMakeLists.txt )
and out_path = share/promod3/MODULE_data/FILE
(within the stage directory).
If given, args can also be multiple arguments (must be put in “” then).
Unit Tests
-
promod3_unittest
promod3_unittest(MODULE name
SOURCES source1 [source2 ...]
[LINK library1/ linker flag1 [library2/ linker flag2 ...]]
[DATA data1 [data2 ...]]
[TARGET target]
[BASE_TARGET base_target])
Add unit tests to ProMod3. Unit tests should go in module-wise so all
source files containing test code go by a single call of
promod3_unittest() . Test data also needs to be registered
here, since it will be copied to the build directory. That way, inside your
code you do not need to set a special path to your data. Additionally, since
it is out of the source tree, you may change test data as you like, without
the Git repository noticing. Calling promod3_unittest() will
create a set of certain make targets for you, beside feeding codetest .
The parameters are:
MODULE
- Specify the name of the module these tests are made for. Needs to be set,
needs to be a single word. Ends up in
make help as a prefix, nothing
will break if it does not match the name of any existing module.
SOURCES
- Describe a set of files hosting unit test code here. If its a wild mix of
C++ and Python files does not matter, CMake will sort this out for
you. But the programming language makes a difference for the
make
targets produced. C++ files will all be gathered in a single
test_suite_<MODULE>_run target (there is also a _xml target but
this is for tools for automated testing). Python code works on a ‘one
target per file’ basis. So test_foo.py will have own target
test_foo.py_run .
LINK
- Add additional libraries and linker flags for C++ source files. Has no
effect on Python tests.
DATA
- Define test data. Instead of giving data directories its own
CMakeLists.txt , those files are added here. Usually located
somewhere in a dedicated data subtree, files need to be given with
a path relative to this directory. That path will then be created in the
build directory.
TARGET
- This defines an additional dependency for the unit test. That is, before
running this unit test, this target will be built.
BASE_TARGET
- This defines an alternative base target to which to add this unit test.
By default all unit tests are registered to be executed with the
codetest target. This can be overridden by using this argument.
Documentation
-
add_doc_source
add_doc_source(NAME name
RST rst1 [rst2...])
Add reStructuredText sources for the doc build system. This is most preferable
used in doc directories for keeping the documentation sorted per
module. This does not create any make targets. Lists filled here will all
be evaluated in the doc/CMakeLists.txt of the repository root.
The parameters are:
NAME
- Specify the name of the module this branch of documentation belongs to.
Needs to be set, needs to be a single word. Using module names is best
practice, while nothing will break if it does not refer to an existing one.
You will find a directory in
doc/source with that name in the build
root.
RST
- Describe a set of files containing the documentation. Feed it a single file
name or a CMake list.
-
add_doc_dependency
add_doc_dependency(NAME name
DEP dependency1 [dependency2...])
Add a dependency to the doc build system. For an existing name, add some
dependencies when it comes to building documentation. Mostly for internal use.
The parameters are:
NAME
- Specify a name the dependencies belong to. This name needs to be already
known in the doc build system. Names of Python modules are good, otherwise
names introduced by
add_doc_source() work well. Dependencies
will be create for all reStructuredText files listed by
add_doc_source() under this name and for all make
targets related to the documentation.
DEP
- Hand over a dependency here or a CMake list. Files work, if given with
absolute path.
Actions
-
pm_action
pm_action(ACTION action-script
TARGET target)
Add an action to ProMod3. Actions are scripts called by the pm launcher
and should all live in the actions directory as executable files.
Adding an action means connecting its file with the given target to be copied
to the libexec directory. No dedicated make target will be
created.
The parameters are:
ACTION
- Name of the action to be added. Should start with
pm- . Needs to be
an existing file in the same directory as the invoking
CMakeLists.txt .
TARGET
- Provide a
make target to trigger copying the action’s script file. The
target has to be created before any action may be attached to it.
|
Contents
Search
Enter search terms or a module, class or function name.
Previous topic
test_actions - Testing Actions
Next topic
Using Binary Files In ProMod3
You are here
|