BasicPlugin

Module defining commands to facilitate the building of plugins:

basic_plugin

Create a plugin library, with or without a separate registration library to avoid ODR violations.

basic_plugin(<name> <suffix> [<options>])

Options

Source specification options

IMPL_SOURCE <implementation-source>...

Specify source to compile into the plugin’s interface implementation library, if appropriate. The implementation should not invoke any registration definition macros or the ODR will be violated.

REG_SOURCE <registration-source>...

Specify source to compile into the plugin registration library, intended only for runtime injection (via e.g. dlopen(3)) into an executable, and not for dynamic linking.

Note

  • If REG_SOURCE is omitted, we look for <name>_<suffix>.cc

  • If IMPL_SOURCE is omitted, we look for <name>.cc

Dependency specification options

LIBRARIES [CONDITIONAL|INTERFACE|PRIVATE|PROTECTED|PUBLIC|REG] <library-dependency>...

Specify targets and/or libraries upon which the implementation (INTERFACE, PUBLIC, PRIVATE), or registration (REG) libraries should depend. If implementation and registration share a dependency not inherited by public callers of the implementation, specify the library twice with one mention prefaced with PRIVATE and the other with REG.

Note

  • The registration library has an automatic dependence on the implementation library (if present).

  • If PUBLIC or INTERFACE dependencies are specified and there is no implementation source, then the plugin will be built as a shared library rather than as a module, and all responsibility for ODR violations rests with the plugin builder.

  • An additional dependency designation, CONDITIONAL, is accepted and is intended for use by intermediate CMake functions that add dependencies to a library. CONDITIONAL is identical to PUBLIC without making a statement about the shared or module nature of the combined implementation/registration library or the presence of a public (non-plugin) calling interface.

Other options

ALIAS <alias>...

Create the specified CMake alias targets to the implementation library.

ALLOW_UNDERSCORES

Normally, neither <name> nor <suffix> may contain underscores in order to avoid possible ambiguities. Allow them with this option at your own risk.

BASENAME_ONLY

Do not add the relative path (directories delimited by _) to the front of the plugin library name.

EXPORT_SET <export-name>

Add the library to the <export-name> export set.

IMPL_TARGET_VAR <var>

Return the—possibly calculated—name of the implementation library target in <var>.

LOCAL_INCLUDE_DIRS <dir>...

Headers may be found in <dir>… at build time.

NOP

Option / argument disambiguator; no other function.

NO_EXPORT

Do not export this plugin.

NO_INSTALL

Do not install the generated library or libraries.

SOVERSION <version>

The library’s compatibility version (cf CMake SOVERSION property).

USE_BOOST_UNIT

The plugin uses Boost unit test functions and should be compiled and linked accordingly.

USE_PROJECT_NAME

New in version 3.23.00.

The project name will be prepended to the plugin library name, separated by _

VERSION

The library’s build version will be set to CETMODULES_CURRENT_PROJECT_VERSION (cf CMake VERSION property).

Deprecated options

SOURCE <source>...

Specify sources to compile into the plugin.

Deprecated since version 2.11: use IMPL_SOURCE, REG_SOURCE and LIBRARIES REG instead.

USE_PRODUCT_NAME

Deprecated since version 2.0: use USE_PROJECT_NAME instead.

Non-option arguments

<name>

The name stem for the library to be generated.

<suffix>

The category of plugin to be generated.

See also

cet_make_library()

cet_build_plugin

Build a plugin of a specific type.

cet_build_plugin(<name> <base> <arg> ...)

Details

cet_build_plugin() attempts to locate a command to invoke to build a plugin <name> of type <base>.

If there exists a CMake variable <unscoped-base>_builder (where <unscoped-base> is <base> after stripping any namespace prefix (*::), the first element of its value will be searched for as a command to invoke, and any further elements will be prepended to <arg> .... Otherwise, a command <base> or <base>_plugin will be invoked if found.

If a suitable command <cmd>() is found, it shall be invoked:

<cmd>(<name> <args>)

If no suitable command is found but there exists a CMake variable <base>_LIBRARIES, the following command shall be invoked:

basic_plugin(<name> <base> LIBRARIES ${<base>_LIBRARIES} <arg> ...)
cet_collect_plugin_builders

Generate and install a CMake wrapper file to include plugin builders.

cet_collect_plugin_builders(<dest-subdir> [<name>] [<options>])

Options

LIST <type> ...

Specify explicit builders to include; <name> is required.

NOP

Option / argument disambiguator; no other function.

Non-option arguments

<dest-subdir>

Destination for the generated CMake file.

<name>

The basename (without extension) of the generated CMake file. Required if LIST <type> ... is present; otherwise defaults to ${CETMODULES_CURRENT_PROJECT_NAME}PluginBuilders.

Details

Generate a CMake file ${PROJECT_BINARY_DIR}/<dest-subdir>/<name>.cmake which includes generated plugin builders <type> ... specified by LIST <type> ... if present; otherwise all those generated by cet_make_plugin_builder() since cet_collect_plugin_builders() was called last.

cet_make_plugin_builder

Generate a plugin builder function using cet_write_plugin_builder() and register it for collection by cet_collect_plugin_builders().

cet_make_plugin_builder(<type> <base> <dest-subdir> [<options>] <args>)

See also

cet_write_plugin_builder()

cet_write_plugin_builder

Generate a plugin builder function using cet_write_plugin_builder().

cet_write_plugin_builder(<type> <base> <dest-subdir> [<options>] <args>)

Options

INSTALL_BUILDER

The generated file shall be installed in ${CMAKE_INSTALL_PREFIX}/<dest-subdir>.

NOP

Option / argument disambiguator; no other function.

SUFFIX <suffix>

See also

basic_plugin().

Details

Generate a file ${PROJECT_BINARY_DIR}/<dest-subdir>/<type>.cmake defining a function:

macro(<type> NAME)
  <func>(${NAME} <base-ish> ${ARGN} <args>)
endmacro()
If <type> and <base> are the same:

  • <func> is basic_plugin()

  • <base-ish> is <suffix> if specified, or <base> after stripping any namespace prefix (*::).

Otherwise: