API Modules¶

This page holds the documentation of the CMake functions that are provided to the users of the CPFCMake package.

Argument Notation¶

Here are some examples to explain how the function argument notation must be interpreted.

PACKAGE_NAMESPACE string: The function expects the required key-word PACKAGE_NAMESPACE to be followed by a single string.
[PUBLIC_HEADER file1 [file2 ...]]: The function expects the optional key-word PUBLIC_HEADER followed by one or more paths to source files. If not otherwise specified, paths must be absolute or relative to CMAKE_CURRENT_SOURCE_DIR.
[ENABLE_CLANG_TIDY_TARGET bool]: The function expects the optional key-word ENABLE_CLANG_TIDY_TARGET followed by either TRUE or FALSE.
PACKAGE_ARCHIVE_FORMATS <7Z|TBZ2|TGZ ...>: The function expects the required key-word PACKAGE_ARCHIVE_FORMATS to be followed by one or multiple values of the listed enum 7Z, TBZ2 and TGZ.

Argument Sub-Lists¶

Example:

[PLUGIN_DEPENDENCIES
    PLUGIN_DIRECTORY dir
    PLUGIN_TARGETS target1 [target2 ...]
[list2 ...]]

Some options are complex enough to require sub-lists of key-word value pairs. In this example PLUGIN_DEPENDENCIES separates multiple sub-lists for plugin definitions. In a function call this could look like this:

cpfAddCppPackageComponent(
    ...
    PLUGIN_DEPENDENCIES
        PLUGIN_DIRECTORY plugin
        PLUGIN_TARGETS MyPlugin1 MyPlugin2
    PLUGIN_DEPENDENCIES
        PLUGIN_DIRECTORY platforms
        PLUGIN_TARGETS Qt5::QWindowsIntegrationPlugin
    ...
)

Module cpfInit.cmake¶

This must be included at the top of your root CMakeLists.txt file.

It adds all CPF modules to the CMAKE_MODULE_PATH allows including them with their short filenames only.
It sets the global variable CPF_MINIMUM_CMAKE_VERSION and checks that the currently run CMake version meets the requirement.
Sets the CMake policies that are required for CPF projects.
It includes further CPF modules that are needed in the root CMakeLists.txt file.

Module cpfAddPackages.cmake¶

This module provides the following function.

cpfAddPackages()

cpfAddPackages()¶

cpfAddPackages(
    [GLOBAL_FILES file1 [file2 ...]]
)

The function is called in all CPF CI-projects.

This calls add_subdirectory() for all the packages that are defined in the package.cmake file.
This adds the global custom targets. see GlobalTargets
Initiates some global variables.

Arguments¶

GLOBAL_FILES¶

This option can be used to add further files to the pipeline target. This can be useful to make global files like a README.md or LICENSE.txt visible in a Visual Studio solution.

Module cpfPackageProject.cmake¶

This module provides the following function.

cpfPackageProject()
cpfFinalizePackageProject()

cpfPackageProject()¶

cpfPackageProject(
    COMPONENTS component_subdir1 component_subdir2 ...
    TARGET_NAMESPACE string
    [BRIEF_DESCRIPTION string]
    [LONG_DESCRIPTION string]
    [OWNER string]
    [WEBPAGE_URL string]
    [MAINTAINER_EMAIL string]
    [LANGUAGES language1 language2 ...]
    [PACKAGE_ARCHIVES
        PACKAGE_ARCHIVE_CONTENT_TYPE <CT_RUNTIME|CT_RUNTIME_PORTABLE excludedTargets|CT_DEVELOPER|CT_SOURCES|CT_DOCUMENTATION>
        PACKAGE_ARCHIVE_FORMATS <7Z|TBZ2|TGZ|TXZ|TZ|ZIP|DEB ...>
        [PACKAGE_ARCHIVE_FORMAT_OPTIONS
            [SYSTEM_PACKAGES_DEB packageListString ]
        ]
        [PACKAGE_ARCHIVE_CONTENT_TYPE ...]
    ...]
    [VERSION_COMPATIBILITY_SCHEME [ExactVersion] ]
)

This macro is called at the beginning of a cpf-packages CMakeLists.txt file. This function calls the project() function to create the package-level project. It automatically reads the version number of the package from the packages git repository or a provided version file and uses it to initiated the cmake variables PROJECT_VERSION and PROJECT_VERSION_<digit> variables.

Arguments¶

LANGUAGES¶

The value of this argument is passed on to the underlying project() call. It determines for which compilers cmake will look. When the argument is not given, the default value CXX C is used.

TARGET_NAMESPACE¶

As a namespace for the packages cmake target names. When clients of your package import your targets they will have to use that namespace like this:

find_package(YourPackage COMPONENTS YourLib)

add_executable(TheirExe)
target_link_libraries(TheirExe yourTargetNamespace::YourLib)

It is also reccomended that you use this internally as well because it makes your cmake code ignorant to the fact if a target is imported or inlined.

BRIEF_DESCRIPTION¶

A short description in one sentence about what the package does. This is only relevant if a debian package archive is created.

LONG_DESCRIPTION¶

A longer description of the package. This is only relevant if a debian package archive is created.

OWNER¶

The value is only used when compiling with MSVC. It is than used in the copyright notice that is displayed on the Details tab of the file-properties window of the generated binary files.

If you plan to allow using a package as EXTERNAL package in some other CI-project, you have to hard-code this value in the packages CMakeLists file. Using a variable from the CI-project in order to remove duplication between your packages will not work, because clients will not have the value of that variable.

WEBPAGE_URL¶

A web address from where the source-code and/or the documentation of the package can be obtained. This is required for Debian packages.

MAINTAINER_EMAIL¶

An email address under which the maintainers of the package can be reached. This is only used when creating Debian package archives.

PACKAGE_ARCHIVES¶

This keyword opens a sub-list of arguments that are used to specify a list of packages that have the same content, but different formats. The argument can be given multiple times, in order to define a variety of package formats and content types. The argument takes two lists as sub-arguments. A package archive is created for each combination of the elements in the sub-argument lists. For example: argument PACKAGE_ARCHIVES PACKAGE_ARCHIVE_CONTENT_TYPE CT_RUNTIME_PORTABLE PACKAGE_ARCHIVE_FORMATS ZIP;7Z will cause the creation of a zip and a 7z archive that both contain the packages executables and all depended on shared libraries. Adding another argument PACKAGE_ARCHIVES PACKAGE_ARCHIVE_CONTENT_TYPE CT_RUNTIME PACKAGE_ARCHIVE_FORMATS DEB will cause the additional creation of a debian package that relies on external dependencies being provided by other packages.

Sub-Options:

PACKAGE_ARCHIVE_CONTENT_TYPE¶

CT_RUNTIME: The package archive contains the executables and shared libraries that are produced by this package. This can be used for packages that either do not depend on any shared libraries or only on shared libraries that are provided externally by the system.
CT_RUNTIME_PORTABLE listExcludedTargets: The package archive will include the packages executables and shared libraries and all depended on shared libraries. This is useful for creating portable packages that do not rely on any system provided shared libraries. The CT_RUNTIME_PORTABLE keyword can be followed by a list of depended on targets that belong to shared libraries that should not be included in the package, because they are provided by the system.
CT_DEVELOPER: The package archive will include all package binaries, header files and cmake config files for importing the package in another project. This content type is supposed to be used for binary library packages that are used in other projects. Note that for msvc debug configurations the package will also include source files to allow debugging into the package. The package does not include dependencies which are supposed to be imported separately by consuming projects.
CT_SOURCES: The package archive contains the files that are needed to compile the package.

PACKAGE_ARCHIVE_FORMATS¶

7Z |TBZ2 | TGZ | TXZ | TZ | ZIP: Packs the distributed files into one of the following archive formats: .7z, .tar.bz2, .tar.gz, .tar.xz, tar.Z, .zip
DEB: Creates a debian package .deb file. This will only be created when the dpkg tool is available.

PACKAGE_ARCHIVE_FORMAT_OPTIONS¶

A list of keyword arguments that contain further options for the creation of the package archives.

[SYSTEM_PACKAGES_DEB]: This is only relevant when using the DEB package format. The option must be a string that contains the names and versions of the debian packages that provide the excluded shared libraries from the CT_RUNTIME option. E.g. libc6 (>= 2.3.1-6), libc6 (< 2.4) on which the package depends.

VERSION_COMPATIBILITY_SCHEME¶

This option determines which versions of the package are can compatible to each other. This is only of interest for shared library packages. For compatible versions it should be possible to replace an older version with a newer one by simply replacing the library file or on linux by changing the symlink that points to the used library. Not that it is still the developers responsibility to implement the library in a compatible way. This option will only influence which symlinks are created, output file names and the version.cmake files that are used to import the library.

Note

Currently only ExactVersion scheme is available, so you do not need to set this option.

Schemes:

ExactVersion: This option means, that different versions of the library are not compatible. This is the most simple scheme and relieves developers from the burdon of keeping things compatible.

cpfFinalizePackageProject()¶

In single component packages this must be called after adding the component. It will create some custom targets that are required for installing and creating package archives.

Module cpfAddCppPackageComponent.cmake¶

This module provides the following functions.

cpfAddCppPackageComponent()
cpfQt5AddUIAndQrcFiles()

cpfAddCppPackageComponent()¶

cpfAddCppPackageComponent(
    TYPE <GUI_APP|CONSOLE_APP|LIB|INTERFACE_LIB>
    [BRIEF_DESCRIPTION string]
    [LONG_DESCRIPTION string]
    [PUBLIC_HEADER file1 [file2 ...]]
    [PRODUCTION_FILES file1 [file2 ...]]
    [EXE_FILES file1 [file2 ...]]
    [PUBLIC_FIXTURE_HEADER header1 [header2 ...]]
    [FIXTURE_FILES file1 [file2 ...]]
    [TEST_FILES file1 [file2 ...]]
    [LINKED_LIBRARIES <PRIVATE|PUBLIC|INTERFACE> target1 ... [ <PRIVATE|PUBLIC|INTERFACE> targetX ...]]
    [LINKED_TEST_LIBRARIES <PRIVATE|PUBLIC|INTERFACE> target1 ... [ <PRIVATE|PUBLIC|INTERFACE> targetX ...]]
    [COMPILE_OPTIONS [BEFORE] <INTERFACE|PUBLIC|PRIVATE>]
    [PLUGIN_DEPENDENCIES
        PLUGIN_DIRECTORY dir
        PLUGIN_TARGETS target1 [target2 ...]
    ...]
    [ENABLE_ABI_API_COMPATIBILITY_REPORT_TARGETS bool]
    [ENABLE_ABI_API_STABILITY_CHECK_TARGETS bool]
    [ENABLE_CLANG_FORMAT_TARGETS bool]
    [ENABLE_CLANG_TIDY_TARGET bool]
    [ENABLE_OPENCPPCOVERAGE_TARGET bool]
    [ENABLE_PACKAGE_DOX_FILE_GENERATION bool]
    [ENABLE_PRECOMPILED_HEADER bool]
    [ENABLE_RUN_TESTS_TARGET bool]
    [ENABLE_VALGRIND_TARGET bool]
    [ENABLE_VERSION_RC_FILE_GENERATION bool]
    [TEST_EXE_ARGUMENTS arg1 [arg2 ...]]
    [HAS_GOOGLE_TEST_EXE bool]
    [CPP_NAMESPACE] string
)

Adds a C++ package-component to a CPF project. The name of the package-component is the same as the name of the directory in which the package-components CMakeLists.txt file is located. The function provides a large list of options that allow defining the features that the package-component should provide.

A C++ package-component consists of a main binary target that has the same name as the package-component and some helper binary targets for tests and test utilities. The names of the created targets are:

# Binary Targets of MyPackage
MyComponent             # The executable or library
libMyComponent          # The implementation library.
MyComponent_fixtures    # A library for test test utility code.
MyComponent_tests       # A text executabl.

# Alias Targets of MyComponent with TARGET_NAMESPACE mypckg
mypckg::MyComponent
mypckg::libMyComponent
mypckg::MyComponent_fixtures
mypckg::MyComponent_tests

The function will create alias targets for all binary targets that have the package namespace prepended. It is recommended to use the alias names in other packages, which enables to smoothly switch between inlined and imported packages.

Providing the function with optional arguments will switch on more of CPF’s functionality like test-targets, code-analysis, packaging or documentation generation.

Example¶

Here is an example that uses cpfAddCppPackageComponent() in a CMakeLists.txt file to create C++ library package.

# MyLib/CMakeLists.txt

include(cpfAddCppPackageComponent)
include(cpfConstants)

cpfPackageProject(
    TARGET_NAMESPACE                      myl
    WEBPAGE_URL                           "http://www.awsomelib.com/index.html"
    MAINTAINER_EMAIL                      "hans@awsomelib.com"
    COMPONENTS                            SINGLE_COMPONENT
    PACKAGE_ARCHIVES
      PACKAGE_ARCHIVE_CONTENT_TYPE    CT_DEVELOPER
      PACKAGE_ARCHIVE_FORMATS                 7Z
    PACKAGE_ARCHIVES
      PACKAGE_ARCHIVE_CONTENT_TYPE    CT_RUNTIME
      PACKAGE_ARCHIVE_FORMATS                 ZIP
    PACKAGE_ARCHIVES
      PACKAGE_ARCHIVE_CONTENT_TYPE   CT_RUNTIME Qt5::Core Qt5::Test Qt5::Gui_GL Qt5::QXcbIntegrationPlugin
      PACKAGE_ARCHIVE_FORMATS DEB
      PACKAGE_ARCHIVE_FORMAT_OPTIONS SYSTEM_PACKAGES_DEB "libqt5core5a, libqt5gui5"
)

################# Define package-component files #################
set( PACKAGE_PUBLIC_HEADERS
    MyFunction.h
)

set( PACKAGE_PRODUCTION_FILES
    MyFunction.cpp
    MyPrivateFunction.h
    MyPrivateFunction.cpp
)

set( PACKAGE_FIXTURE_FILES
    TestFixtures/MyFunction_fixtures.cpp
    TestFixtures/MyFunction_fixtures.h
)

set( PACKAGE_TEST_FILES
    Tests/MyFunction_tests.cpp
)

set(PACKAGE_LINKED_LIBRARIES
    Qt5::Core
    Qt5::Gui
)

set(PACKAGE_LINKED_TEST_LIBRARIES
    GMock::gmock
)

set( qtPlatformPlugins
    PLUGIN_DIRECTORY  platforms
    PLUGIN_TARGETS            Qt5::QWindowsIntegrationPlugin Qt5::QXcbIntegrationPlugin
)

set( myPlugin
    PLUGIN_DIRECTORY  plugins
    PLUGIN_TARGETS            MyPlugin
)

################# Add Package #################
cpfAddCppPackageComponent(
    TYPE                    LIB
    PUBLIC_HEADER           ${PACKAGE_PUBLIC_HEADERS}
    PRODUCTION_FILES        ${PACKAGE_PRODUCTION_FILES}
    FIXTURE_FILES           ${PACKAGE_FIXTURE_FILES}
    TEST_FILES              ${PACKAGE_TEST_FILES}
    LINKED_LIBRARIES        ${PACKAGE_LINKED_LIBRARIES}
    LINKED_TEST_LIBRARIES   ${PACKAGE_LINKED_TEST_LIBRARIES}
    PLUGIN_DEPENDENCIES     ${qtPlatformPlugins}
    PLUGIN_DEPENDENCIES     ${myPlugin}
)

cpfFinalizePackageProject()

Arguments¶

TYPE¶

The type of the main binary target of the package.

GUI_APP = Executable with switched of console. Use this for Qt applications with GUI;
CONSOLE_APP = Console application;
LIB = Library
INTERFACE_LIB = Header only library

BRIEF_DESCRIPTION¶

A short description in one sentence about what the package-component does. This is included in the generated documentation page of the package-component and in some package archive types. On Windows it is also displayed on the Details tab of the file-properties window of the generated main binary file.

LONG_DESCRIPTION¶

A longer description of the package. This is included in the generated doxygen documentation page of the package-component.

PUBLIC_HEADER¶

All header files that declare functions or classes that are supposed to be used by consumers of a library package. The public headers will automatically be put into binary package archives, while header files in the PRODUCTION_FILES are not included.

PRODUCTION_FILES¶

All files that belong to the production target. If the target is an executable, there should be a main.cpp that is used for the executable.

PRODUCTION_FILES¶

For package-components of type GUI_APP or CONSOLE_APP, this variable that must be added to the executable itself. On windows this can be .rc files or the icon for the executable.

PUBLIC_FIXTURE_HEADER¶

All header files in the fixture library that are required by external clients of the library. If the fixture library is only used by this package, this can be empty.

FIXTURE_FILES¶

All files that belong to the test fixtures target.

TEST_FILES¶

All files that belong to the test executable target.

COMPILE_OPTIONS¶

The values of this argument are simply piped through to a call of the CMake function target_compile_options() for each generated binary target. For further information about the possible values refer to the CMake documentation.

LINKED_LIBRARIES¶

The names of the library targets that are linked to the main binary target. Just like in CMakes target_link_libraries() function you can use the PUBLIC, PRIVATE and INTERFACE keywords.

LINKED_TEST_LIBRARIES¶

The names of the library targets that are linked to the test fixture library and the test executable. Use this to specify dependencies of the test targets that are not needed in the production code, like fixture libraries from other packages.

PLUGIN_DEPENDENCIES¶

This keyword opens a sub-list of arguments that are used to define plugin dependencies of the package. Multiple PLUGIN_DEPENDENCIES sub-lists can be given to allow having multiple plugin subdirectories.

The plugin targets are shared libraries that are explicitly loaded by the package-components executables and on which the package has no link dependency. If a target in the list does not exist when the function is called, it will be silently ignored. If a given target is an internal target, an artificial dependency between the plugin target and the package-components executables is created to make sure the plugin is compilation is up-to-date before the executable is build.

Adding this options makes sure that the plugin library is build before the executable and copied besides it in the PLUGIN_DIRECTORY.

Sub-Options:

PLUGIN_DIRECTORY: A directory relative to the package’s executables in which the plugin libraries must be deployed so they are found by the executable. This if often a plugins directory.

PLUGIN_TARGETS: The name of the targets that provide the plugin libraries.

ENABLE_ABI_API_COMPATIBILITY_REPORT_TARGETS¶

This option can be used to enable or disable the abi-compliance-checker_<package> target. This option is ignored on non-Linux platforms. Setting this argument overrides the value of the global CPF_ENABLE_ABI_API_COMPATIBILITY_REPORT_TARGETS variable for this package.

ENABLE_ABI_API_STABILITY_CHECK_TARGETS¶

This option can be used to enable or disable the enforcement of version compatibility between the current version and the last release version. It requires option ENABLE_ABI_API_COMPATIBILITY_REPORT_TARGETS to be set. Setting this argument overrides the value of the global CPF_ENABLE_ABI_API_STABILITY_CHECK_TARGETS variable for this package.

ENABLE_CLANG_FORMAT_TARGETS¶

This option can be used to enable or disable the clang-format_<binary-target> target. Setting this argument overrides the value of the global CPF_ENABLE_CLANG_FORMAT_TARGETS variable for this package. Enabling the clang-format target requires two dependencies.

Clang-format must be available in the PATH on Linux platforms. If you use Visual Studio 2017 or later you should choose to install clang-format in the Visual Studio installer.
You need to add the a Sources/.clang-format file to your project. This file defines the formatting rules. You can also add this file with the GLOBAL_FILES argument to your project to make it visible in the Visual Studio solution. Read the clang-format documentation to see what you have to put into that file.

ENABLE_CLANG_TIDY_TARGET¶

This option can be used to enable or disable the clang-tidy_<package> target. This option is ignored if the compiler is not clang. Setting this argument overrides the value of the global CPF_ENABLE_CLANG_TIDY_TARGET variable for this package.

ENABLE_OPENCPPCOVERAGE_TARGET¶

This option can be used to enable or disable the opencppcoverage_<package> target. This option is ignored on non-Windows platforms. Setting this argument overrides the value of the global CPF_ENABLE_OPENCPPCOVERAGE_TARGET variable for this package.

ENABLE_PACKAGE_DOX_FILE_GENERATION¶

If this option is given, the package-component will generate a standard package-component documentation .dox file. The file contains the brief and long package-component description as well as some links to other generated html content like test-coverage reports or abi-compatibility reports. Setting this argument overrides the value of the global CPF_ENABLE_PACKAGE_DOX_FILE_GENERATION variable for this package.

ENABLE_PRECOMPILED_HEADER¶

This option can be used to enable or disable the use of pre-compiled headers for the packages binary targets. Using the this option requires the cotire dependency. Setting this argument overrides the value of the global CPF_ENABLE_PRECOMPILED_HEADER variable for this package.

ENABLE_RUN_TESTS_TARGET¶

This option can be used to enable or disable the runAllTests_<package> and runFastTests_<package> targets. The option is ignored if the package-component does not have a test executable. Setting this argument overrides the value of the global CPF_ENABLE_RUN_TESTS_TARGET variable for this package.

ENABLE_VALGRIND_TARGET¶

This option can be used to enable or disable the valgrind_<package> target. The option is ignored when not compiling with gcc and debug information. Setting this argument overrides the value of the global CPF_ENABLE_VALGRIND_TARGET variable for this package.

ENABLE_VERSION_RC_FILE_GENERATION¶

By default the CPF generates a version.rc file for MSVC that is used to inject some version information into the binary files. If this version.rc file does not fit your needs, you can disable its generation with this option and provide your custom made .rc file.

TEST_EXE_ARGUMENTS¶

This option can be used to pass a list of arguments to the test executable when building the runAllTests_<package> or runFastTests_<package> targets. This can be usefull in cases where the test executable needs information from the build-system like a directory for test files etc. When using the “Visual Studio” generator family, these arguments are also set to the “Debugging -> Command Arguments” option to make sure that the same arguments are passed to the test executable during debugging.

Example .. code-block:: none

TEST_EXE_ARGUMENTS
–TestWorkingDirectory “${CMAKE_BINARY_DIR}/TestFiles” –TestDataDirectory “${CMAKE_SOURCE_DIR}/TestData”

HAS_GOOGLE_TEST_EXE¶

This option only has an effect when using a Visual Studio Generator. When this option is set to true, cpfAddCppPackageComponent() will create an empty file <test-exe>.is_google_test that lies beside the create test executable. Set this option to true when you use the <a href=”https://github.com/csoltenborn/GoogleTestAdapter”>GoogleTestAdapter</a> and it fails to find your tests.

CPP_NAMESPACE¶

The C++ namespace that is used in the generated cpfPackageVersion_<package>.h header file. It defaults to the TARGET_NAMESPACE of the current package project if not given.

cpfQt5AddUIAndQrcFiles()¶

cpfQt5AddUIAndQrcFiles( sources )

Parameter sources must be passed by name. The function calls the qt5_wrap_ui() and qt5_add_resources() for all files in the given source files that have the .ui or .qrc file extension. It adds the generated files to the list. It may be necessary to call this function when Qt is used in combination with pre-compiled headers.

Module cpfAddFilePackageComponent.cmake¶

This module provides the following function.

cpfAddFilePackageComponent()

cpfAddFilePackageComponent()¶

cpfAddFilePackageComponent(
    SOURCES file1 ...
)

This function creates a target that does nothing, but is only used as a file container. This makes sure that the files are included in a Visual Studio solution.

Arguments¶

SOURCES¶

A list of files that are added to the package. The paths must be relative to the current source directory or absolute.

Module cpfAddDoxygenPackageComponent.cmake¶

This module provides the following function.

cpfAddDoxygenPackageComponent()

cpfAddDoxygenPackageComponent()¶

cpfAddDoxygenPackageComponent(
    [PROJECT_NAME name]
    DOXYGEN_CONFIG_FILE absPath
    DOXYGEN_LAYOUT_FILE absPath
    DOXYGEN_STYLESHEET_FILE absPath
    [SOURCES relPath1 [relPath2 ... ]]
    [ADDITIONAL_PACKAGES externalPackage1 [externalPackage2 ...]]
    [HTML_HEADER absPath]
    [HTML_FOOTER absPath]
    [PROJECT_LOGO absPath]
    [PLANTUML_JAR_PATH absPath]
    [RUN_DOXYINDEXER]
    [DOXYGEN_BIN_DIR]
)

This function adds a package-component that runs the doxygen documentation generator on the owned packages of your CI-project. The package-component can also contain extra files containing global documentation that does not belong to any other package.

All files specified with the key-word arguments are added to the targets source files.

More information about the documentation generation can be found on the page Documentation generation and in the cpfAddDoxygenPackageComponent() tutorial.

Arguments¶

PROJECT_NAME¶

The value of this argument is the name that appears in the header of the doxygen documentation. This is set to the name of the CI-project if no value is specified. Note that this overrides the value of the PROJECT_NAME variable in the DOXYGEN_CONFIG_FILE.

DOXYGEN_CONFIG_FILE¶

This must be set to the absolute path of the Doxygen configuration file. You should be aware that the file is not directly passed to Doxygen. In order to inject the values of CMake variables into the Doxygen configuration, the file is used as a template to generate the file Generated/\<config\>/_CPF/documentation/tempDoxygenConfig.txt. This generated file is the one that is used as the input for the call of Doxygen. After building the new package-component for the first time you can open the file and see that it overwrites some values of the configuration variables at the bottom of the file.

The following variables in the configuration file are overwritten. Changing them in the given template will have no effect.

PROJECT_NAME                (set to the value of the PROJECT_NAME option)
OUTPUT_DIRECTORY            (set to "Generated/<config>/html/doxygen")
HTML_OUTPUT                 (set to "html")
INPUT                       (set to Sources and the directories with the generated package-component documentation dox files)
EXCLUDE                     (set to the external packages source directories that are not listed in ADDITIONAL_PACKAGES)
DOTFILE_DIRS                (set to "Generated/<config>/html/doxygen/external")
LAYOUT_FILE                 (set to the path of the DOXYGEN_LAYOUT_FILE option)
GENERATE_HTML               (set to YES)
HTML_EXTRA_STYLESHEET       (set to the path of the DOXYGEN_STYLESHEET_FILE option)
HTML_HEADER                 (only if HTML_HEADER option is set)
HTML_FOOTER                 (only if HTML_FOOTER option is set)
PROJECT_LOGO                (only if PROJECT_LOGO option is set)
PLANTUML_JAR_PATH           (only if PLANTUML_JAR_PATH option is set)
SEARCHDATA_FILE             (set to "searchdata.xml")

DOXYGEN_LAYOUT_FILE¶

Absolute path to the used DoxygenLayout.xml file.

DOXYGEN_STYLESHEET_FILE¶

Absolute path to the used DoxygenStylesheet.css file.

SOURCES¶

Additional files that will be parsed by doxygen and that can contain global documentation.

ADDITIONAL_PACKAGES¶

Packages that are not owned by this ci-project, but should also be parsed by doxygen in order to add them to the documentation.

HTML_HEADER¶

The header.html file used by doxygen.

PROJECT_LOGO¶

An .svg or .png file that is copied to the doxygen output directory and can then be used in the documentation.

PLANT_UML_JAR¶

The absolute path to the plantuml.jar which doxygen uses to generate UML-diagramms from <a href=”http://plantuml.com/”>PlantUML</a> code in doxygen comments. Setting this enables you to use Doxygen’s startuml command.

RUN_DOXYINDEXER¶

This option can be added to also run the doxyindexer tool to generate the searchdata.db directory that is required when using the server-side search feature of doxygen. The directory will be created in the Generated/\<config\>/html/cgi-bin directory.

DOXYGEN_BIN_DIR¶

This option can be set to the directory that contains the doxygen executable if CPFCMake is not able to find the correct one.

Module cpfAddSphinxPackageComponent.cmake¶

This module provides the following function.

cpfAddSphinxPackageComponent()

cpfAddSphinxPackageComponent()¶

cpfAddSphinxPackageComponent(
    [SOURCE_DIR]                    absDir
    [CONFIG_FILE_DIR]               absDir
    [OTHER_FILES]                   file1 ...
    [OUTPUT_SUBDIR]                 relDir
    [ADDITIONAL_SPHINX_ARGUMENTS]   arg1 val1 arg2 val2 ...
    [SOURCE_SUFFIXES]               extension1 extension2 ...
)

This function creates a target that runs the python based sphinx documentation generator using a given configuration file. The source directory for sphinx is the <rootdir>/Sources directory.

Arguments¶

SOURCE_DIR¶

The base directory in which sphinx searches for files that contribute to the documentation. When the argument is not given, CMAKE_SOURCE_DIR is used in order to look for documentation files in all package-components of the CI-project.

CONFIG_FILE_DIR¶

A relative path to the directory that holds the conf.py file that configures your sphinx project. When not given, the source directory of the package-component is used.

OTHER_FILES¶

All other files that belong to the documentation package.

OUTPUT_SUBDIR¶

This option can be used to add extra subdirectories to the o

ADDITIONAL_SPHINX_ARGUMENTS¶

A list of command line arguments that are passed on to the sphinx tool.

SOURCE_SUFFIX¶

This should be a list of file extensions without a leading dot. It must be set when you use the source_suffix variable in your sphinx config file to enable the parsing of other file types. Getting this wrong will break the out-of-date mechanism for the created target. This means that the build-system may not always re-build the target after making changes to the source files.

Module cpfAddPythonPackageComponent.cmake¶

This module provides the following function.

cpfAddPythonPackageComponent()

cpfAddPythonPackageComponent()¶

cpfAddPythonPackageComponent(
    SOURCES                           file1 ...
    [TEST_SCRIPT]                     relativeScriptPath
    [TEST_SCRIPT_ARGUMENTS]           args
)

This functions adds a file package that contains the given source files. It can also create unit test run targets if the TEST_SCRIPT is given. The function will create a cpfPackageVersion_<package-component>.py file in the packages source directory which can be used to retrieve the version of the component. This file should be generated in the binary directory but due to lacking python knowledge I currently do not know how to handle this situation. So the current work-around is to git-ignore the generated file in the source tree.

Arguments¶

SOURCES¶

A list with all the files that belong to the package component. Paths can be either relative to the current source directory or absolute.

TEST_SCRIPT¶

A path to a pathon file that runs the unit tests of the package-component. If this is given an extra runAllTests_<package-component> target is created that can be build to run the tests.

TEST_SCRIPT_ARGUMENTS¶

This can be used to hand additional arguments to the TEST_SCRIPT.

API Modules¶

Argument Notation¶

Argument Sub-Lists¶

Module cpfInit.cmake¶

Module cpfAddPackages.cmake¶

cpfAddPackages()¶

Arguments¶

GLOBAL_FILES¶

Module cpfPackageProject.cmake¶

cpfPackageProject()¶

Arguments¶

LANGUAGES¶

TARGET_NAMESPACE¶

BRIEF_DESCRIPTION¶

LONG_DESCRIPTION¶

OWNER¶

WEBPAGE_URL¶

MAINTAINER_EMAIL¶

PACKAGE_ARCHIVES¶

PACKAGE_ARCHIVE_CONTENT_TYPE¶

PACKAGE_ARCHIVE_FORMATS¶

PACKAGE_ARCHIVE_FORMAT_OPTIONS¶

VERSION_COMPATIBILITY_SCHEME¶

cpfFinalizePackageProject()¶

Module cpfAddCppPackageComponent.cmake¶

cpfAddCppPackageComponent()¶

Example¶

Arguments¶

TYPE¶

BRIEF_DESCRIPTION¶

LONG_DESCRIPTION¶

PUBLIC_HEADER¶

PRODUCTION_FILES¶

PRODUCTION_FILES¶

PUBLIC_FIXTURE_HEADER¶

FIXTURE_FILES¶

TEST_FILES¶

COMPILE_OPTIONS¶

LINKED_LIBRARIES¶

LINKED_TEST_LIBRARIES¶

PLUGIN_DEPENDENCIES¶

ENABLE_ABI_API_COMPATIBILITY_REPORT_TARGETS¶

ENABLE_ABI_API_STABILITY_CHECK_TARGETS¶

ENABLE_CLANG_FORMAT_TARGETS¶

ENABLE_CLANG_TIDY_TARGET¶

ENABLE_OPENCPPCOVERAGE_TARGET¶

ENABLE_PACKAGE_DOX_FILE_GENERATION¶

ENABLE_PRECOMPILED_HEADER¶

ENABLE_RUN_TESTS_TARGET¶

ENABLE_VALGRIND_TARGET¶

ENABLE_VERSION_RC_FILE_GENERATION¶

TEST_EXE_ARGUMENTS¶

HAS_GOOGLE_TEST_EXE¶

CPP_NAMESPACE¶

cpfQt5AddUIAndQrcFiles()¶

Module cpfAddFilePackageComponent.cmake¶

cpfAddFilePackageComponent()¶

Arguments¶

SOURCES¶

Module cpfAddDoxygenPackageComponent.cmake¶

cpfAddDoxygenPackageComponent()¶

Arguments¶

PROJECT_NAME¶

DOXYGEN_CONFIG_FILE¶

DOXYGEN_LAYOUT_FILE¶

DOXYGEN_STYLESHEET_FILE¶

SOURCES¶

ADDITIONAL_PACKAGES¶

HTML_HEADER¶

HTML_FOOTER¶

PROJECT_LOGO¶

PLANT_UML_JAR¶

RUN_DOXYINDEXER¶

DOXYGEN_BIN_DIR¶

Module cpfAddSphinxPackageComponent.cmake¶

cpfAddSphinxPackageComponent()¶

Arguments¶

SOURCE_DIR¶

CONFIG_FILE_DIR¶

OTHER_FILES¶