Provided by: ycm-cmake-modules_0.13.0-3_all 
NAME
ycm-modules - YCM Modules Reference
GENERIC MODULES
ExtractVersion
Extracts version numbers from a version string:
extract_version (<name> [REVERSE_NAME])
Tries to extract the following variables (the second version is used if REVERSE_NAME is set as argument):
<name>_MAJOR_VERSION or <name>_VERSION_MAJOR - <name> major version
<name>_MINOR_VERSION or <name>_VERSION_MINOR - <name> minor version
<name>_PATCH_VERSION or <name>_VERSION_PATCH - <name> patch version
<name>_TWEAK_VERSION or <name>_VERSION_TWEAK - <name> tweak version
<name>_VERSION_COUNT - number of version components, 0 to 4
GetAllCMakeProperties
Return a list containing the names of all known CMake Properties.
Only properties returned by cmake --help-property-list are returned, custom properties will not be on the
returned list.
Properties containing <CONFIG> or <LANG> are expanded to the correct property name.
GitInfo
Extract information from a git repository.
git_commit_info
Extract information about one commit from one git repository in SOURCE DIR:
git_commit_info([SOURCE DIR <dir>]
[PREFIX <prefix>]
[REVISION <rev>]
[FATAL])
If SOURCE_DIR is a git repository, it checks the given REVISION and sets the following variables:
<PREFIX>_GIT_COMMIT_DESCRIBE
The output of git describe <ref>.
<PREFIX>_GIT_COMMIT_DESCRIBE_CONTAINS
The output of git describe --contains <ref>.
<PREFIX>_GIT_COMMIT_TAG
The most recent tag that is reachable from a commit.
<PREFIX>_GIT_COMMIT_REVISION
The number of commits since the beginning of the git history.
<PREFIX>_GIT_COMMIT_TAG_REVISION
The number of commits since the last tag.
<PREFIX>_GIT_COMMIT_DATE_REVISION
The number of commits since the beginning of the day.
<PREFIX>_GIT_COMMIT_AUTHOR_DATE
The commit author date.
<PREFIX>_GIT_COMMIT_AUTHOR_TIME
The commit author time.
<PREFIX>_GIT_COMMIT_AUTHOR_TZ
The commit author time zone.
<PREFIX>_GIT_COMMIT_AUTHOR_NAME
The commit author name.
<PREFIX>_GIT_COMMIT_AUTHOR_EMAIL
The commit author e-mail.
<PREFIX>_GIT_COMMIT_COMMITTER_DATE
The commit committer date.
<PREFIX>_GIT_COMMIT_COMMITTER_TIME
The commit author time.
<PREFIX>_GIT_COMMIT_COMMITTER_TZ
The commit author time zone.
<PREFIX>_GIT_COMMIT_COMMITTER_NAME
The commit committer name.
<PREFIX>_GIT_COMMIT_COMMITTER_EMAIL
The commit committer email.
<PREFIX>_GIT_COMMIT_HASH
The commit hash.
<PREFIX>_GIT_COMMIT_HASH_SHORT
The abbreviated commit hash.
<PREFIX>_GIT_COMMIT_SUBJECT
The commit log message subject line.
<PREFIX>_GIT_COMMIT_BODY
The commit log message body.
If SOURCE_DIR is not set, then the PROJECT_SOURCE_DIR cmake variable is used.
If PREFIX is not set, then the PROJECT_NAME cmake variable is used.
REVISION can be a commit hash, a tag, a branch, or anything that git can parse as a revision. If
REVISION` is not set, then ``HEAD is used.
If FATAL is set, a fatal error is emitted when the source dir is not a git repository, or when git
was not found. This is disabled by default to allow downloads from non-git sources (archives,
wrappers, etc.), but can be enabled if required.
git_wt_info
Extract information about current working tree from one git repository in SOURCE DIR:
git_wt_info([SOURCE DIR <dir>]
[PREFIX <prefix>]
[FATAL])
If SOURCE_DIR is a git repository, it checks current revision and sets the following variables:
<PREFIX>_GIT_WT_DESCRIBE
The output of git describe HEAD.
<PREFIX>_GIT_WT_DESCRIBE_CONTAINS
The output of git describe --contains HEAD.
<PREFIX>_GIT_WT_TAG
The most recent tag that is reachable from current commit.
<PREFIX>_GIT_WT_REVISION
The number of commits since the beginning of the git history.
<PREFIX>_GIT_WT_TAG_REVISION
The number of commits since the last tag.
<PREFIX>_GIT_WT_DATE_REVISION
The number of commits since the beginning of the day.
<PREFIX>_GIT_WT_AUTHOR_DATE
The current commit author date.
<PREFIX>_GIT_WT_AUTHOR_TIME
The current commit author time.
<PREFIX>_GIT_WT_AUTHOR_TZ
The current commit author time zone.
<PREFIX>_GIT_WT_AUTHOR_NAME
The current commit author name.
<PREFIX>_GIT_WT_AUTHOR_EMAIL
The current commit author e-mail.
<PREFIX>_GIT_WT_COMMITTER_DATE
The current commit committer date.
<PREFIX>_GIT_WT_COMMITTER_TIME
The current commit author time.
<PREFIX>_GIT_WT_COMMITTER_TZ
The current commit author time zone.
<PREFIX>_GIT_WT_COMMITTER_NAME
The current commit committer name.
<PREFIX>_GIT_WT_COMMITTER_EMAIL
The current commit committer email.
<PREFIX>_GIT_WT_HASH
The current commit hash.
<PREFIX>_GIT_WT_HASH_SHORT
The abbreviated commit hash.
<PREFIX>_GIT_WT_SUBJECT
The current commit log message subject line.
<PREFIX>_GIT_WT_BODY
The current commit log message body.
<PREFIX>_GIT_WT_DIRTY
Whether the current working tree is clean or not.
If SOURCE_DIR is not set, then the PROJECT_SOURCE_DIR cmake variable is used.
If PREFIX is not set, then the PROJECT_NAME cmake variable is used.
If FATAL is set, a fatal error is emitted when the source dir is not a git repository, or when git
was not found. This is disabled by default to allow downloads from non-git sources (archives,
wrappers, etc.), but can be enabled if required.
IncludeUrl
Adds the include_url() command that useful to download and include other CMake modules from a given url.
include_url
Downloads a file from given url and includes it:
include_url(<url> # Url to be downloaded
[DESTINATION <destination>] # Where the file will be saved
[EXPECTED_HASH <ALGO=value>] # Verify downloaded file's hash
[EXPECTED_MD5 <sum>] # Short-hand for "EXPECTED_HASH MD5=sum"
[DOWNLOAD_ONCE] # Download the file only once
[DOWNLOAD_ALWAYS] # Download the file every time
[OPTIONAL] # Do not fail file cannot be included
[RESULT_VARIABLE <variable>] # The local path for the file included
[RETRIES <retries>] # Try download <retries> times (default 3)
[QUIET] # Don't print anything
#--Download arguments-----------
[INACTIVITY_TIMEOUT <timeout>] # Timeout after <timeout> seconds of inactivity
[TIMEOUT <timeout>] # Timeout after <timeout> seconds
[STATUS <status>] # Download status variable
[LOG <log>] # Download log variable
[SHOW_PROGRESS] # Show download progress
[TLS_VERIFY <on|off>] # Check certificates
[TLS_CAINFO <file>] # Custom Certificate Authority file
#--Include arguments------------
[NO_POLICY_SCOPE] # Do not manage a new policy entry
)
The include_url macro downloads a file from given url and includes it. It works both in -P script mode
and when configuring a CMakeLists.txt file.
If DESTINATION is specified, the file is saved at the given location with the original file name, if
<destination> is a directory, or with the given file name, if <destination> is a file name.
The arguments EXPECTED_HASH, EXPECTED_MD5 are used to ensure that the file included is the one expected.
If the <url> is a local file (i.e. starts with file://) the hash check is performed also on the file
converted to the non-native end-of-line style. See the documentation of the file() command for further
information about these arguments.
If the DOWNLOAD_ONCE option is specified, the file is not downloaded if the file already exists and the
hash is correct. If the DOWNLOAD_ALWAYS option is specified, the file is downloaded at every CMake
execution, and an error is raised on failure. If none of these two option is specifies, the default
behaviour is to try to download the file at every CMake execution, but no error is raised if the download
fails if a version of the file already exists. This is useful when CMake should try to update the file to
the latest version, before including it.
If the OPTIONAL option is specified, no error will be caused if for any reason the file cannot be
downloaded or included. If RESULT_VARIABLE is given, the variable will be set to the full filename which
has been downloaded and included or NOTFOUND if it failed. See the documentation of the file() command
for further information about these arguments.
If the RETRIES option is specified, the download will be tried If the QUIET option is specified, the
command will emit no output.
The arguments INACTIVITY_TIMEOUT, TIMEOUT, STATUS, LOG, SHOW_PROGRESS, TLS_VERIFY, and TLS_CAINFO are
passed to the file(DOWNLOAD) command. See the documentation of the file() command for a detailed
description of these arguments.
The arguments NO_POLICY_SCOPE is passed to the include() command. See the documentation of the include()
and cmake_policy() commands for a detailed description of this argument.
ReplaceImportedTargets
Adds the replace_imported_targets() command that useful to replace paths with imported targets in link
variables (like <FOO>_LIBRARIES) and targets.
replace_imported_targets
Replace imported targets in a list of and targets and paths:
replace_imported_targets(<var> [target [target [...]]])
Each path in var corrisponding to one of the targets will be replaced with the corrisponding target,
taking care to remove the relative optimized and debug keywords.
For each existing target in var, the following properties will be searched for imported locations of
targets, and, if set, will be replaced in the same way:
IMPORTED_LINK_DEPENDENT_LIBRARIES
IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
IMPORTED_LINK_INTERFACE_LIBRARIES
IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
INTERFACE_LINK_LIBRARIES
LINK_INTERFACE_LIBRARIES
LINK_INTERFACE_LIBRARIES_<CONFIG>
LINK_LIBRARIES
StandardFindModule
Try to find a package using a cmake config file, or pkgconfig:
standard_find_module(<name>
<pkgconfig name>
[NOT_REQUIRED]
[QUIET]
[SKIP_CMAKE_CONFIG]
[SKIP_PKG_CONFIG]
[TARGET <target>]
[REPLACE_TARGETS <target> [...]]
)
If the package is found, the following variables (where possible) are created:
<name>_FOUND - System has <name>
<name>_INCLUDE_DIRS - <name> include directory
<name>_LIBRARIES - <name> libraries
<name>_DEFINITIONS - Additional compiler flags for <name>
<name>_VERSION - <name> version
<name>_MAJOR_VERSION - <name> major version
<name>_MINOR_VERSION - <name> minor version
<name>_PATCH_VERSION - <name> patch version
<name>_TWEAK_VERSION - <name> tweak version
<name>_VERSION_COUNT - Number of version components, 0 to 4
For each library that requires to be linked (i.e. -llib) it creates:
<name>_<LIB>_LIBRARY_RELEASE (cached, advanced)
<name>_<LIB>_LIBRARY_DEBUG (cached, advanced, and empty by default)
<name>_<LIB>_LIBRARY
<name>_<LIB>_LIBRARY_FOUND
In a FindXXX.cmake module, this macro can be used at the beginning. The NOT_REQUIRED can be added to
avoid failing if the package was not found, but pkg-config is installed. The QUIET argument can be used
to hide the output from find_package_handle_standard_args. If <name>_FOUND is FALSE at the end, more
“custom” searches can be used (for windows, etc.)
If SKIP_CMAKE_CONFIG or SKIP_PKG_CONFIG are set, the relative step is skipped
If TARGET is specified, in pkg-config mode, an imported target will be created using the first library
returned by pkg-config as imported location.
The REPLACE_TARGETS can be used to pass a list of imported targets that will be detected in variables and
target properties, and replaced with the corresponding target.
If one of the STANDARD_FIND_MODULE_USE_IMPORTED_TARGET or STANDARD_FIND_MODULE_USE_IMPORTED_TARGET_<name>
are enabled, and a TARGET is specified, the <name>_LIBRARIES variable content is replaced with the
imported target.
If one of the variables STANDARD_FIND_MODULE_DEBUG or STANDARD_FIND_MODULE_DEBUG_<name> is enabled,
prints more useful debug output
PACKAGING HELPER MODULES
InstallBasicPackageFiles
A helper module to make your package easier to be found by other projects.
install_basic_package_files
Create and install a basic version of cmake config files for your project:
install_basic_package_files(<Name>
COMPATIBILITY <compatibility>
[VERSION <version>]
[ARCH_INDEPENDENT]
[NO_EXPORT | EXPORT <export>] # (default = "EXPORT <Name>")
[NO_SET_AND_CHECK_MACRO]
[NO_CHECK_REQUIRED_COMPONENTS_MACRO]
[VARS_PREFIX <prefix>] # (default = "<Name>")
[EXPORT_DESTINATION <destination>]
[INSTALL_DESTINATION <destination>]
[NAMESPACE <namespace>] # (default = "<Name>::")
[EXTRA_PATH_VARS_SUFFIX path1 [path2 ...]]
[CONFIG_TEMPLATE <file>]
[UPPERCASE_FILENAMES | LOWERCASE_FILENAMES]
[DEPENDENCIES <dependency1> "<dependency2> [...]" ...]
[PRIVATE_DEPENDENCIES <dependency1> "<dependency2> [...]" ...]
[INCLUDE_FILE <file> | INCLUDE_CONTENT <content>]
[COMPONENT <component>] # (default = "<Name>")
)
Depending on UPPERCASE_FILENAMES and LOWERCASE_FILENAMES, this function generates 3 files:
• <Name>ConfigVersion.cmake or <name>-config-version.cmake
• <Name>Config.cmake or <name>-config.cmake
• <Name>Targets.cmake or <name>-targets.cmake
If neither UPPERCASE_FILENAMES nor LOWERCASE_FILENAMES is set, a file <Name>Config.cmake.in or
<name>-config.cmake.in is searched, and the convention is chosed according to the file found. If no file
was found, the uppercase convention is used.
The DEPENDENCIES argument can be used to set a list of dependencies that will be searched using the
find_dependency() command from the CMakeFindDependencyMacro module. Dependencies can be followed by any
of the possible find_dependency() argument. In this case, all the arguments must be specified within
double quotes (e.g. "<dependency> 1.0.0 EXACT", or "<dependency> CONFIG"). The PRIVATE_DEPENDENCIES
argument is similar to DEPENDENCIES, but these dependencies are included only when BUILD_SHARED_LIBS is
OFF. If a libraries is declared STATIC, OBJECT or INTERFACE, and they link to some dependency, these
should be added using the DEPENDENCIES argument, since the PRIVATE_DEPENDENCIES argument would work only
when BUILD_SHARED_LIBS is disabled.
When using a custom template file, the @PACKAGE_DEPENDENCIES@ string is replaced with the code checking
for the dependencies specified by these two argument.
If the ARCH_INDEPENDENT option is enabled, the installed package version will be considered compatible
even if it was built for a different architecture than the requested architecture.
Each file is generated twice, one for the build directory and one for the installation directory. The
INSTALL_DESTINATION argument can be passed to install the files in a location different from the default
one (${CMAKE_INSTALL_DATADIR}/cmake/${Name} if the ARCH_INDEPENDENT option is enabled,
${CMAKE_INSTALL_LIBDIR}/cmake/${Name} otherwise). The EXPORT_DESTINATION argument can be passed to
generate the files in the build tree in a location different from the default one (CMAKE_BINARY_DIR). If
this is a relative path, it is considered relative to the CMAKE_CURRENT_BINARY_DIR directory.
The build directory is exported to the CMake user package registry if the build option
CMAKE_EXPORT_PACKAGE_REGISTRY is set.
The <Name>ConfigVersion.cmake file is generated using write_basic_package_version_file(). The VERSION,
COMPATIBILITY, and
``
ARCH_INDEPENDENT``arguments are passed to this function.
VERSION shall be in the form <major>[.<minor>[.<patch>[.<tweak>]]]]. If no VERSION is given, the
PROJECT_VERSION variable is used. If this hasn’t been set, it errors out. The VERSION argument is also
used to replace the @PACKAGE_VERSION@ string in the configuration file.
COMPATIBILITY shall be any of the options accepted by the write_basic_package_version_file() command
(AnyNewerVersion, SameMajorVersion, SameMinorVersion [CMake 3.11], or ExactVersion). These options are
explained in write_basic_package_version_file() command documentation. If your project has more
elaborate version matching rules, you will need to write your own custom ConfigVersion.cmake file instead
of using this macro.
The <Name>Config.cmake file is generated using configure_package_config_file(). The
NO_SET_AND_CHECK_MACRO, NO_CHECK_REQUIRED_COMPONENTS_MACRO, and arguments are passed to this function.
By default install_basic_package_files() also generates the two helper macros set_and_check() and
check_required_components() into the <Name>Config.cmake file. set_and_check() should be used instead of
the normal set() command for setting directories and file locations. Additionally to setting the
variable it also checks that the referenced file or directory actually exists and fails with a
FATAL_ERROR otherwise. This makes sure that the created <Name>Config.cmake file does not contain wrong
references. When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into the
``<Name>Config.cmake file.
By default, install_basic_package_files() append a call to check_required_components(<Name>) in
<Name>Config.cmake file if the package supports components. This macro checks whether all requested,
non-optional components have been found, and if this is not the case, sets the <Name>_FOUND variable to
FALSE, so that the package is considered to be not found. It does that by testing the
<Name>_<Component>_FOUND variables for all requested required components. When using the
NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated into the <Name>Config.cmake file.
Finally, the files in the build and install directory are exactly the same.
See the documentation of CMakePackageConfigHelpers module for further information and references therein.
If the CONFIG_TEMPLATE argument is passed, the specified file is used as template for generating the
configuration file, otherwise this module expects to find a <Name>Config.cmake.in or
<name>-config.cmake.in file either in current source directory. If the file does not exist, a very basic
file is created.
A set of variables are checked and passed to configure_package_config_file() as PATH_VARS. For each of
the SUFFIX considered, if one of the variables:
<VARS_PREFIX>_(BUILD|INSTALL)_<SUFFIX>
(BUILD|INSTALL)_<VARS_PREFIX>_<SUFFIX>
is defined, the <VARS_PREFIX>_<SUFFIX> variable will be defined before configuring the package. In order
to use that variable in the config file, you have to add a line:
set_and_check(<VARS_PREFIX>_<SUFFIX> \"@PACKAGE_<VARS_PREFIX>_<SUFFIX>@\")
if the path must exist or just:
set(<VARS_PREFIX>_<SUFFIX> \"@PACKAGE_<VARS_PREFIX>_<SUFFIX>@\")
if the path could be missing.
These variable will have different values whether you are using the package from the build tree or from
the install directory. Also these files will contain only relative paths, meaning that you can move the
whole installation and the CMake files will still work.
Default PATH_VARS suffixes are:
BINDIR BIN_DIR
SBINDIR SBIN_DIR
LIBEXECDIR LIBEXEC_DIR
SYSCONFDIR SYSCONF_DIR
SHAREDSTATEDIR SHAREDSTATE_DIR
LOCALSTATEDIR LOCALSTATE_DIR
LIBDIR LIB_DIR
INCLUDEDIR INCLUDE_DIR
OLDINCLUDEDIR OLDINCLUDE_DIR
DATAROOTDIR DATAROOT_DIR
DATADIR DATA_DIR
INFODIR INFO_DIR
LOCALEDIR LOCALE_DIR
MANDIR MAN_DIR
DOCDIR DOC_DIR
more suffixes can be added using the EXTRA_PATH_VARS_SUFFIX argument.
The <Name>Targets.cmake is generated using export(EXPORT) in the build tree and install(EXPORT) in the
installation directory. The targets are exported using the value for the NAMESPACE argument as namespace.
The export can be passed using the EXPORT argument. If no export is used (e.g. for a CMake script
library), pass NO_EXPORT.
If the INCLUDE_FILE argument is passed, the content of the specified file (which might contain
@variables@) is appended to the generated <Name>Config.cmake file. If the INCLUDE_CONTENT argument is
passed, the specified content (which might contain @variables@) is appended to the generated
<Name>Config.cmake file. When a CONFIG_TEMPLATE is passed, or a <Name>ConfigVersion.cmake.in or a
<name>-config-version.cmake.in file is available, these 2 arguments are used to replace the
``@INCLUDED_CONTENT@ string in this file. This allows one to inject custom code to this file, useful
e.g. to set additional variables which are loaded by downstream projects.
Note that content specified with INCLUDE_FILE or INCLUDE_CONTENT cannot reference any of the PATH_VARS
because this content is not expanded by configure_package_config_file().
If the COMPONENT argument is passed, it is forwarded to the install() commands, otherwise <Name> is used.
AddUninstallTarget
Add the “uninstall” target for your project:
include(AddUninstallTarget)
will create a file cmake_uninstall.cmake in the build directory and add a custom target uninstall (or
UNINSTALL on Visual Studio and Xcode) that will remove the files installed by your package (using
install_manifest.txt). See also
https://gitlab.kitware.com/cmake/community/wikis/FAQ#can-i-do-make-uninstall-with-cmake
The AddUninstallTarget module must be included in your main CMakeLists.txt. If included in a subdirectory
it does nothing. This allows you to use it safely in your main CMakeLists.txt and include your project
using add_subdirectory (for example when using it with FetchContent).
If the uninstall target already exists, the module does nothing.
AddInstallRPATHSupport
Add support to RPATH during installation to the project and the targets
add_install_rpath_support
Add support to RPATH during installation to the project:
target_append_install_rpath
Add extra paths to RPATH for a specific target:
target_append_install_rpath(<target>
<INSTALL_DESTINATION destination>
[LIB_DIRS dir [dir]]
[DEPENDS condition [condition]])
Arguments:
- ``INSTALL_DESTINATION`` path where the target will be installed.
- ``LIB_DIRS`` list of directories to be added to the RPATH. These
directories will be added "relative" w.r.t. the ``INSTALL_DESTINATION``.
- ``DEPENDS`` list of conditions that should be ``TRUE`` to enable
RPATH, for example ``FOO; NOT BAR``.
SUPERBUILD HELPER MODULES
FindOrBuildPackage
Searches for a package and builds it if it cannot be found.
find_or_build_package
Searches for a package and builds it if it cannot be found:
find_or_build_package(<PackageName> <find_package_args>)
This module tries to locate a package using find_package(). If the package cannot be found it tries to
build it, by including Build<package>. This file should contain the instructions to download and build
the package (for example using ExternalProject)
The arguments passed to the function, are passed to the find_package() command.
FIXME Figure out how to handle the REQUIRED and QUIET arguments
If the package was found, the USE_SYSTEM_<PackageName> cached variable can be disabled in order to force
CMake to build the package instead of using the one found on the system. To automatically force CMake to
build all the packages that are also found on the system, the YCM_DISABLE_SYSTEM_PACKAGES cache variable
can be enabled.
This function sets these variables:
HAVE_SYSTEM_<PackageName> # The package was found on the system
HAVE_<PackageName> # The package is available
The user should use the latest, to check if a package is available, instead of checking using
<PackageName>_FOUND. For example
FIXME Check uppercase (${_PKG}) and lowercase (${_pkg}) variables
find_or_build_package(Foo)
if(HAVE_Foo)
...
endif()
CMAKE_DISABLE_BUILD_PACKAGE_<PackageName>
Using this variable, building a package is explicitly forbidden. therefore if the package cannot be
found on the system, the HAVE_<PackageName> will be set to false.
YCMEPHelper
A helper for ExternalProject:
ycm_ep_helper(<name>
[DOCS]
[TYPE <type>]
[STYLE <style>]
[COMPONENT <component>] (default = "external")
[FOLDER <folder> (default = "<component>")
[REPOSITORY <repo>]
[EXCLUDE_FROM_ALL <0|1>]
#--Git and Hg only arguments-----------
[TAG <tag>]
#--Svn only arguments-----------
[REVISION <revision>]
[USERNAME <username>]
[PASSWORD <password>]
[TRUST_CERT <0|1>]
#--CMake arguments---------
[CMAKE_ARGS]
[CMAKE_CACHE_ARGS]
[CMAKE_CACHE_DEFAULT_ARGS]
[DEPENDS]
[DOWNLOAD_COMMAND]
[UPDATE_COMMAND]
[PATCH_COMMAND]
[CONFIGURE_COMMAND]
[BUILD_COMMAND]
[INSTALL_COMMAND]
[TEST_COMMAND]
[CLEAN_COMMAND] (not in ExternalProject)
[TEST_AFTER_INSTALL]
[TEST_BEFORE_INSTALL]
[TEST_EXCLUDE_FROM_MAIN]
)
YCM_BOOTSTRAP()
NON_INTERACTIVE_BUILD
YCM_BOOTSTRAP_BASE_ADDRESS
YCM_SKIP_HASH_CHECK
YCM_BOOTSTRAP_VERBOSE
YCM_EP_INSTALL_DIR
YCM_EP_ADDITIONAL_CMAKE_ARGS
YCM_<COMPONENT>_COLOR
YCM_<COMPONENT>_BGCOLOR
YCM_<COMPONENT>_NODECOLOR
TODO Add variable YCM_INSTALL_PREFIX
StyleBITBUCKET
StyleGITHUB
StyleGITLAB_ROBOTOLOGY
StyleGNOME
StyleKDE
StyleLOCAL
StyleNONE
StyleSOURCEFORGE
FIND PACKAGE MODULES
Findassimp
Find the Open Asset Importer Library (assimp)
Input variables
The following variables may be set to influence this module’s behavior:
ASSIMP_VERBOSE
to output a detailed log of this module.
Imported Targets
This module defines the IMPORTED target assimp::assimp for the library assimp.
Result Variables
This module defines the following variables:
assimp_FOUND
true if assimp has been found and can be used
ASSIMP_ROOT_DIR
the root directory where the installation can be found
ASSIMP_INCLUDE_DIRS
include directories for assimp
ASSIMP_LIBRARIES
libraries to link against assimp
ASSIMP_LIBRARY_DIRS
link directories
ASSIMP_VERSION
ASSIMP version
ASSIMP_VERSION_MAJOR
ASSIMP major version
ASSIMP_VERSION_MINOR
ASSIMP minor version
ASSIMP_VERSION_REVISION
ASSIMP revision version
FindACE
Try to find the ACE library
Targets set:
ACE::ACE (links the ACE library)
ACE::ACE_INLINE (INTERFACE library for ACE inlines only)
Variables set:
ACE_FOUND - System has ACE library
ACE_LIBRARIES - ACE link libraries
ACE_INCLUDE_DIRS - ACE library include directories
ACE_DEFINITIONS - Additional compiler flags for ACE library
ACE_VERSION - ACE library version
ACE_MAJOR_VERSION - ACE major version
ACE_MINOR_VERSION - ACE minor version
ACE_BETA_VERSION - ACE beta version
Options variables:
ACE_INLINE (default ON)
The ACE::ACE target passes __ACE_INLINE__ by default, this can be
changed by setting ACE_INLINE = OFF.
The ACE_DEFINITIONS variable is also influenced by the same option.
FindAtlas
Find the Atlas (and Lapack) libraries
FindCFW2CANAPI
Created:
CFW2CANAPI_INC_DIRS - Directories to include to use esdcan api
CFW2CANAPI_LIB - Default library to link against to use the esdcan API
CFF2CANAPI_FOUND - If false, don't try to use esdcan API
FindDRAGONFLYAPI
Created:
DRAGONFLYAPI_INC_DIRS - Directories to include to use dragonfly API
DRAGONFLYAPI_LIB - Default library to link against to use the dragonfly API
DRAGONFLYAPI_FOUND - If false, don't try to use dragonfly API
FindESDCANAPI
Created:
ESDCANAPI_INC_DIRS - Directories to include to use esdcan api
ESDCANAPI_LIB - Default library to link against to use the esdcan API
ESDCANAPI_FOUND - If false, don't try to use esdcan API
FindFreenect
Try to find the Freenect library. Once done this will define the following variables:
Freenect_FOUND - System has Freenect
Freenect_INCLUDE_DIRS - Freenect include directory
Freenect_LIBRARIES - Freenect libraries
Freenect_DEFINITIONS - Additional compiler flags for Freenect
Freenect_VERSION - Freenect version
Freenect_MAJOR_VERSION - Freenect major version
Freenect_MINOR_VERSION - Freenect minor version
Freenect_PATCH_VERSION - Freenect patch version
FindFTDI
Try to find ftdi. Once done this will define:
FTDI_FOUND - system has ftdi
FTDI_INCLUDE_DIR - ~ the ftdi include directory
FTDI_LIBRARY - Link these to use ftdi
FindFuse
Try to find the Fuse library. Once done this will define the following variables:
Fuse_FOUND - System has Fuse
Fuse_INCLUDE_DIRS - Fuse include directory
Fuse_LIBRARIES - Fuse libraries
Fuse_DEFINITIONS - Additional compiler flags for Fuse
Fuse_VERSION - Fuse version
Fuse_MAJOR_VERSION - Fuse major version
Fuse_MINOR_VERSION - Fuse minor version
Fuse_PATCH_VERSION - Fuse patch version
Fuse_TWEAK_VERSION - Fuse tweak version
FindGLFW3
Find the GLFW3 framework.
IMPORTED Targets
This module defines the IMPORTED target GLFW3::GLFW3, if GLFW3 has been found.
Result Variables
This module defines the following variables:
GLFW3_INCLUDE_DIRS - include directories for GLFW3
GLFW3_LIBRARIES - libraries to link against GLFW3
GLFW3_FOUND - true if GLFW3 has been found and can be used
Environment Variables
If the library is not found on system paths, the GLFW3_ROOT environment variable can be used to locate
the lbrary.
FindGLM
Find the OpenGL Mathematics (glm)
Input variables
The following variables may be set to influence this module’s behavior:
GLM_VERBOSE
to output a detailed log of this module.
Imported Targets
This module defines the IMPORTED target glm for the library glm.
Result Variables
This module defines the following variables:
GLM_FOUND
true if assimp has been found and can be used
GLM_INCLUDE_DIRS
include directories for assimp
GLM_VERSION
GLM version
GLM_VERSION_MAJOR
GLM major version
GLM_VERSION_MINOR
GLM minor version
GLM_VERSION_PATCH
GLM patch version
FindGooCanvas
Try to find the GooCanvas library. Once done this will define the following variables:
GooCanvas_FOUND - System has GooCanvas
GooCanvas_INCLUDE_DIRS - GooCanvas include directory
GooCanvas_LIBRARIES - GooCanvas libraries
GooCanvas_DEFINITIONS - Additional compiler flags for GooCanvas
GooCanvas_VERSION - GooCanvas version
GooCanvas_MAJOR_VERSION - GooCanvas major version
GooCanvas_MINOR_VERSION - GooCanvas minor version
GooCanvas_PATCH_VERSION - GooCanvas patch version
GooCanvas_TWEAK_VERSION - GooCanvas tweak version
If the library is found, the imported target GooCanvas::goocanvas is created.
FindGooCanvasMM
Try to find the GooCanvasMM library. Once done this will define the following variables:
GooCanvasMM_FOUND - System has GooCanvasMM
GooCanvasMM_INCLUDE_DIRS - GooCanvasMM include directory
GooCanvasMM_LIBRARIES - GooCanvasMM libraries
GooCanvasMM_DEFINITIONS - Additional compiler flags for GooCanvasMM
GooCanvasMM_VERSION - GooCanvasMM version
GooCanvasMM_MAJOR_VERSION - GooCanvasMM major version
GooCanvasMM_MINOR_VERSION - GooCanvasMM minor version
GooCanvasMM_PATCH_VERSION - GooCanvasMM patch version
GooCanvasMM_TWEAK_VERSION - GooCanvasMM tweak version
If the library is found, the imported target GooCanvasMM::goocanvasmm is created.
FindGSL
Try to find GSL library Once run this will define:
GSL_FOUND
GSL_INCLUDE_DIR
GSL_INCLUDE_DIRS
GSL_LIBRARIES
GSL_LINK_DIRECTORIES
GSLCBLAS_LIBRARY
GSL_LIBRARY
FindGtkDatabox
Try to find the GtkDatabox library. Once done this will define the following variables:
GtkDatabox_FOUND - System has GtkDatabox
GtkDatabox_INCLUDE_DIRS - GtkDatabox include directory
GtkDatabox_LIBRARIES - GtkDatabox libraries
GtkDatabox_DEFINITIONS - Additional compiler flags for GtkDatabox
GtkDatabox_VERSION - GtkDatabox version
GtkDatabox_MAJOR_VERSION - GtkDatabox major version
GtkDatabox_MINOR_VERSION - GtkDatabox minor version
GtkDatabox_PATCH_VERSION - GtkDatabox patch version
GtkDatabox_TWEAK_VERSION - GtkDatabox tweak version
If the library is found, the imported target GtkDatabox::gtkdatabox is created.
FindGtkDataboxMM
Try to find the GtkDataboxMM library. Once done this will define the following variables:
GtkDataboxMM_FOUND - System has GtkDataboxMM
GtkDataboxMM_INCLUDE_DIRS - GtkDataboxMM include directory
GtkDataboxMM_LIBRARIES - GtkDataboxMM libraries
GtkDataboxMM_DEFINITIONS - Additional compiler flags for GtkDataboxMM
GtkDataboxMM_VERSION - GtkDataboxMM version
GtkDataboxMM_MAJOR_VERSION - GtkDataboxMM major version
GtkDataboxMM_MINOR_VERSION - GtkDataboxMM minor version
GtkDataboxMM_PATCH_VERSION - GtkDataboxMM patch version
GtkDataboxMM_TWEAK_VERSION - GtkDataboxMM tweak version
If the library is found, the imported target GtkDataboxMM::gtkdataboxmm is created.
FindI2C
Find the I2C device library.
Once done this will define the following variables:
I2C_INCLUDE_DIRS - I2C include directory
I2C_LIBRARIES - I2C libraries
I2C_FOUND - if false, you cannot build anything that requires I2C
FindIPOPT
Try to locate the IPOPT library
On non Windows systems, use pkg-config to try to locate the library, if this fails then try to locate the
library in the directory pointed by the IPOPT_DIR environment variable.
On Windows systems, just try to find the library using the IPOPT_DIR environment variable.
Create the following variables:
IPOPT_INCLUDE_DIRS - Directories to include to use IPOPT
IPOPT_LIBRARIES - Default library to link against to use IPOPT
IPOPT_DEFINITIONS - Flags to be added to linker's options
IPOPT_LINK_FLAGS - Flags to be added to linker's options
IPOPT_FOUND - If false, don't try to use IPOPT
FindIPP
Try to find the IPP library.
FindLibdc1394
Try to find the libdc1394 library. Once done this will define the following variables:
Libdc1394_FOUND - System has libdc1394
Libdc1394_INCLUDE_DIRS - libdc1394 include directory
Libdc1394_LIBRARIES - libdc1394 libraries
Libdc1394_DEFINITIONS - Additional compiler flags for libdc1394
Libdc1394_VERSION - libdc1394 version
Libdc1394_MAJOR_VERSION - libdc1394 major version
Libdc1394_MINOR_VERSION - libdc1394 minor version
Libdc1394_PATCH_VERSION - libdc1394 patch version
FindLibedit
Try to find NetBSD Editline library (libedit), a Berkeley-style licensed command line editor library
provides generic line editing, history, and tokenization functions, similar to those found in GNU
Readline. Once done this will define the following variables:
Libedit_FOUND - System has Editline library
Libedit_INCLUDE_DIRS - Editline library include directory
Libedit_LIBRARIES - Editline library libraries
Libedit_DEFINITIONS - Additional compiler flags for Editline library
Libedit_VERSION - Editline library version
Libedit_MAJOR_VERSION - Editline library major version
Libedit_MINOR_VERSION - Editline library minor version
Environment variables used to locate the Editline library:
READLINE_DIR - Libedit root directory
Cached variables used to locate the NetBSD Editline library:
Libedit_INCLUDE_DIR - the Libedit include directory
Libedit_LIBRARY_RELEASE - NetBSD Editline library (release)
Libedit_LIBRARY_DEBUG - NetBSD Editline library (debug)
FindLibOVR
Find the LibOVR library in Oculus Rift SDK.
IMPORTED Targets
This module defines the following IMPORTED targets if LibOVR has been found:
LibOVR::OVRKernel
LibOVR::OVR
Result Variables
This module defines the following variables:
LibOVR_FOUND - System has LibOVR
LibOVR_VERSION - LibOVR version
LibOVR_VERSION_PRODUCT - LibOVR product version
LibOVR_VERSION_MAJOR - LibOVR major version
LibOVR_VERSION_MINOR - LibOVR minor version
LibOVR_VERSION_PATCH - LibOVR patch version
LibOVR_VERSION_BUILD - LibOVR build number
LibOVR_VERSION_STRING - LibOVR version
LibOVR_VERSION_DETAILED_STRING - LibOVR version (including build number)
LibOVR_INCLUDE_DIRS - Include directories for LibOVR
LibOVR_LIBRARIES - libraries to link against LibOVR
FindLibusb1
Try to find the libusb-1 library. Once done this will define the following variables:
Libusb1_FOUND - System has libusb-1
Libusb1_INCLUDE_DIRS - libusb-1 include directory
Libusb1_LIBRARIES - libusb-1 libraries
Libusb1_DEFINITIONS - Additional compiler flags for libusb-1
Libusb1_VERSION - libusb-1 version
Libusb1_MAJOR_VERSION - libusb-1 major version
Libusb1_MINOR_VERSION - libusb-1 minor version
Libusb1_PATCH_VERSION - libusb-1 patch version
FindLibv4l2
Try to find the libv4l2 library. Once done this will define the following variables:
Libv4l2_FOUND - System has libv4l2
Libv4l2_INCLUDE_DIRS - libv4l2 include directory
Libv4l2_LIBRARIES - libv4l2 libraries
Libv4l2_DEFINITIONS - Additional compiler flags for libv4l2
Libv4l2_VERSION - libv4l2 version
Libv4l2_MAJOR_VERSION - libv4l2 major version
Libv4l2_MINOR_VERSION - libv4l2 minor version
Libv4l2_PATCH_VERSION - libv4l2 patch version
Libv4l2_TWEAK_VERSION - libv4l2 tweak version
FindLibv4lconvert
Try to find the libv4lconvert library. Once done this will define the following variables:
Libv4lconvert_FOUND - System has libv4lconvert
Libv4lconvert_INCLUDE_DIRS - libv4lconvert include directory
Libv4lconvert_LIBRARIES - libv4lconvert libraries
Libv4lconvert_DEFINITIONS - Additional compiler flags for libv4lconvert
Libv4lconvert_VERSION - libv4lconvert version
Libv4lconvert_MAJOR_VERSION - libv4lconvert major version
Libv4lconvert_MINOR_VERSION - libv4lconvert minor version
Libv4lconvert_PATCH_VERSION - libv4lconvert patch version
Libv4lconvert_TWEAK_VERSION - libv4lconvert tweak version
FindNVIDIACg
Try to find NVIDIACg libraries
FindODE
Options:
ODE_DOUBLE_PRECISION -use double precision ode libraries
ODE_STATIC -link against static libraries
On exit create the following variables:
ODE_INCLUDE_DIRS - Directories to include to use ODE
ODE_LIBRARIES - Default library to link against to use ODE
ODE_FOUND - If false, library not found
FindOpenCV
Find OpenCV - variables set:
OpenCV_FOUND
OpenCV_LIBRARIES
OpenCV_INCLUDE_DIRS
This script is a combination from multiple sources that use different variable names; the names are
reconciled at the end of the script.
Todo
Check if this module is still needed with recent CMake releases.
Todo
Check if the license is correct
FindOpenGL
Wrap kitware’s original FindOpenGL. Standardize variables.
In windows require you set OpenGL_DIR
Set:
OpenGL_FOUND
OpenGL_LIBRARIES
OpenGL_INCLUDE_DIRS
Todo
Check if this module is still needed with recent CMake releases.
FindOpenNI
Try to find the OpenNI library. Once done this will define the following variables:
OpenNI_FOUND - System has OpenNI
OpenNI_INCLUDE_DIRS - OpenNI include directory
OpenNI_LIBRARIES - OpenNI libraries
OpenNI_DEFINITIONS - Additional compiler flags for OpenNI
OpenNI_VERSION - OpenNI version
OpenNI_MAJOR_VERSION - OpenNI major version
OpenNI_MINOR_VERSION - OpenNI minor version
OpenNI_PATCH_VERSION - OpenNI patch version
FindPLXCANAPI
Created:
PLXCANAPI_INC_DIRS - Directories to include to use esdcan api
PLXCANAPI_LIB - Default library to link against to use the esdcan API
PLXCANAPI_FOUND - If false, don't try to use esdcan API
FindPortAudio
Try to find the PortAudio library.
FindqpOASES
Try to find the qpOASES library. Once done this will define the following variables:
qpOASES_FOUND - System has qpOASES
qpOASES_INCLUDE_DIRS - qpOASES include directory
qpOASES_LIBRARIES - qpOASES libraries
qpOASES does not have an “install” step, and the includes are in the source tree, while the libraries are
in the build tree. Therefore the environment and cmake variables qpOASES_SOURCE_DIR and
qpOASES_BINARY_DIR will be used to locate the includes and libraries.
FindReadline
Try to find GNU Readline, a library for easy editing of command lines. Once done this will define the
following variables:
Readline_FOUND - System has GNU Readline
Readline_INCLUDE_DIRS - GNU Readline include directory
Readline_LIBRARIES - GNU Readline libraries
Readline_DEFINITIONS - Additional compiler flags for GNU Readline
Readline_VERSION - GNU Readline version
Readline_MAJOR_VERSION - GNU Readline major version
Readline_MINOR_VERSION - GNU Readline minor version
Environment variables used to locate the GNU Readline library:
READLINE_DIR - Readline root directory
Cached variables used to locate the GNU Readline library:
Readline_INCLUDE_DIR - the Readline include directory
Readline_LIBRARY_RELEASE - GNU Readline library (release)
Readline_LIBRARY_DEBUG - GNU Readline library (debug)
FindSQLite
Try to find the SQLite library. Once done this will define the following variables:
SQLite_FOUND - System has SQLite
SQLite_INCLUDE_DIRS - SQLite include directory
SQLite_LIBRARIES - SQLite libraries
SQLite_DEFINITIONS - Additional compiler flags for SQLite
SQLite_VERSION - SQLite version
SQLite_MAJOR_VERSION - SQLite major version
SQLite_MINOR_VERSION - SQLite minor version
SQLite_PATCH_VERSION - SQLite patch version
SQLite_TWEAK_VERSION - SQLite tweak version
FindStage
Try to find Stage, a library for easy editing of command lines. Once done this will define the following
variables:
Stage_FOUND - System has Stage
Stage_INCLUDE_DIRS - Stage include directory
Stage_LIBRARIES - Stage libraries
Stage_DEFINITIONS - Additional compiler flags for Stage
Stage_VERSION - Stage version
Stage_MAJOR_VERSION - Stage major version
Stage_MINOR_VERSION - Stage minor version
FindTinyXML
Try to find the TinyXML library. Once done this will define the following variables:
TinyXML_FOUND - System has TinyXML
TinyXML_INCLUDE_DIRS - TinyXML include directory
TinyXML_LIBRARIES - TinyXML libraries
TinyXML_DEFINITIONS - Additional compiler flags for TinyXML
TinyXML_VERSION - TinyXML version
TinyXML_MAJOR_VERSION - TinyXML major version
TinyXML_MINOR_VERSION - TinyXML minor version
TinyXML_PATCH_VERSION - TinyXML patch version
FindYamlCpp
Try to find the YamlCpp library. Once done this will define the following variables:
YamlCpp_FOUND - System has YamlCpp
YamlCpp_INCLUDE_DIRS - YamlCpp include directory
YamlCpp_LIBRARIES - YamlCpp libraries
YamlCpp_DEFINITIONS - Additional compiler flags for YamlCpp
YamlCpp_VERSION - YamlCpp version
YamlCpp_MAJOR_VERSION - YamlCpp major version
YamlCpp_MINOR_VERSION - YamlCpp minor version
YamlCpp_PATCH_VERSION - YamlCpp patch version
YamlCpp_TWEAK_VERSION - YamlCpp tweak version
BUILD PACKAGE MODULES
BuildECM
ECM - extra-cmake-modules (from KDE project)
BuildEigen3
Eigen3
BuildGazeboYARPPlugins
GazeboYARPPlugins
BuildGooCanvas
GooCanvas
BuildGooCanvasMM
GooCanvasMM
BuildGtkDatabox
GtkDatabox
BuildGtkDataboxMM
GtkDataboxMM
BuildICUB
ICUB
BuildqpOASES
qpOASES
BuildTinyXML
TinyXML
BuildYARP
YARP
CMAKE PROPOSED MODULES
These modules are patched versions of the ones included in CMake.
ExternalProject
External Project Definition
ExternalProject_Add
The ExternalProject_Add() function creates a custom target to drive download, update/patch,
configure, build, install and test steps of an external project:
ExternalProject_Add(<name> [<option>...])
The individual steps within the process can be driven independently if required (e.g. for CDash
submission) and extra custom steps can be defined, along with the ability to control the step
dependencies. The directory structure used for the management of the external project can also be
customized. The function supports a large number of options which can be used to tailor the
external project behavior.
Directory Options:
Most of the time, the default directory layout is sufficient. It is largely an
implementation detail that the main project usually doesn’t need to change. In some
circumstances, however, control over the directory layout can be useful or necessary. The
directory options are potentially more useful from the point of view that the main build
can use the ExternalProject_Get_Property() command to retrieve their values, thereby
allowing the main project to refer to build artifacts of the external project.
PREFIX <dir>
Root directory for the external project. Unless otherwise noted below, all other
directories associated with the external project will be created under here.
TMP_DIR <dir>
Directory in which to store temporary files.
STAMP_DIR <dir>
Directory in which to store the timestamps of each step. Log files from individual
steps are also created in here unless overriden by LOG_DIR (see Logging Options
below).
LOG_DIR <dir>
Directory in which to store the logs of each step.
DOWNLOAD_DIR <dir>
Directory in which to store downloaded files before unpacking them. This directory
is only used by the URL download method, all other download methods use SOURCE_DIR
directly instead.
SOURCE_DIR <dir>
Source directory into which downloaded contents will be unpacked, or for non-URL
download methods, the directory in which the repository should be checked out,
cloned, etc. If no download method is specified, this must point to an existing
directory where the external project has already been unpacked or cloned/checked
out.
NOTE:
If a download method is specified, any existing contents of the source directory
may be deleted. Only the URL download method checks whether this directory is
either missing or empty before initiating the download, stopping with an error if
it is not empty. All other download methods silently discard any previous
contents of the source directory.
BINARY_DIR <dir>
Specify the build directory location. This option is ignored if BUILD_IN_SOURCE is
enabled.
INSTALL_DIR <dir>
Installation prefix to be placed in the <INSTALL_DIR> placeholder. This does not
actually configure the external project to install to the given prefix. That must be
done by passing appropriate arguments to the external project configuration step,
e.g. using <INSTALL_DIR>.
If any of the above ..._DIR options are not specified, their defaults are computed as
follows. If the PREFIX option is given or the EP_PREFIX directory property is set, then an
external project is built and installed under the specified prefix:
TMP_DIR = <prefix>/tmp
STAMP_DIR = <prefix>/src/<name>-stamp
DOWNLOAD_DIR = <prefix>/src
SOURCE_DIR = <prefix>/src/<name>
BINARY_DIR = <prefix>/src/<name>-build
INSTALL_DIR = <prefix>
LOG_DIR = <STAMP_DIR>
Otherwise, if the EP_BASE directory property is set then components of an external project
are stored under the specified base:
TMP_DIR = <base>/tmp/<name>
STAMP_DIR = <base>/Stamp/<name>
DOWNLOAD_DIR = <base>/Download/<name>
SOURCE_DIR = <base>/Source/<name>
BINARY_DIR = <base>/Build/<name>
INSTALL_DIR = <base>/Install/<name>
LOG_DIR = <STAMP_DIR>
If no PREFIX, EP_PREFIX, or EP_BASE is specified, then the default is to set PREFIX to
<name>-prefix. Relative paths are interpreted with respect to CMAKE_CURRENT_BINARY_DIR at
the point where ExternalProject_Add() is called.
Download Step Options:
A download method can be omitted if the SOURCE_DIR option is used to point to an existing
non-empty directory. Otherwise, one of the download methods below must be specified
(multiple download methods should not be given) or a custom DOWNLOAD_COMMAND provided.
DOWNLOAD_COMMAND <cmd>...
Overrides the command used for the download step (generator expressions are
supported). If this option is specified, all other download options will be ignored.
Providing an empty string for <cmd> effectively disables the download step.
URL Download
URL <url1> [<url2>...]
List of paths and/or URL(s) of the external project’s source. When more than
one URL is given, they are tried in turn until one succeeds. A URL may be an
ordinary path in the local file system (in which case it must be the only URL
provided) or any downloadable URL supported by the file(DOWNLOAD) command. A
local filesystem path may refer to either an existing directory or to an
archive file, whereas a URL is expected to point to a file which can be
treated as an archive. When an archive is used, it will be unpacked
automatically unless the DOWNLOAD_NO_EXTRACT option is set to prevent it. The
archive type is determined by inspecting the actual content rather than using
logic based on the file extension.
URL_HASH <algo>=<hashValue>
Hash of the archive file to be downloaded. The argument should be of the form
<algo>=<hashValue> where algo can be any of the hashing algorithms supported
by the file() command. Specifying this option is strongly recommended for URL
downloads, as it ensures the integrity of the downloaded content. It is also
used as a check for a previously downloaded file, allowing connection to the
remote location to be avoided altogether if the local directory already has a
file from an earlier download that matches the specified hash.
URL_MD5 <md5>
Equivalent to URL_HASH MD5=<md5>.
DOWNLOAD_NAME <fname>
File name to use for the downloaded file. If not given, the end of the URL is
used to determine the file name. This option is rarely needed, the default
name is generally suitable and is not normally used outside of code internal
to the ExternalProject module.
DOWNLOAD_NO_EXTRACT <bool>
Allows the extraction part of the download step to be disabled by passing a
boolean true value for this option. If this option is not given, the
downloaded contents will be unpacked automatically if required. If extraction
has been disabled, the full path to the downloaded file is available as
<DOWNLOADED_FILE> in subsequent steps or as the property DOWNLOADED_FILE with
the ExternalProject_Get_Property() command.
DOWNLOAD_NO_PROGRESS <bool>
Can be used to disable logging the download progress. If this option is not
given, download progress messages will be logged.
TIMEOUT <seconds>
Maximum time allowed for file download operations.
HTTP_USERNAME <username>
Username for the download operation if authentication is required.
HTTP_PASSWORD <password>
Password for the download operation if authentication is required.
HTTP_HEADER <header1> [<header2>...]
Provides an arbitrary list of HTTP headers for the download operation. This
can be useful for accessing content in systems like AWS, etc.
TLS_VERIFY <bool>
Specifies whether certificate verification should be performed for https
URLs. If this option is not provided, the default behavior is determined by
the CMAKE_TLS_VERIFY variable (see file(DOWNLOAD)). If that is also not set,
certificate verification will not be performed. In situations where URL_HASH
cannot be provided, this option can be an alternative verification measure.
TLS_CAINFO <file>
Specify a custom certificate authority file to use if TLS_VERIFY is enabled.
If this option is not specified, the value of the CMAKE_TLS_CAINFO variable
will be used instead (see file(DOWNLOAD))
NETRC <level>
Specify whether the .netrc file is to be used for operation. If this option
is not specified, the value of the CMAKE_NETRC variable will be used instead
(see file(DOWNLOAD)) Valid levels are:
IGNORED
The .netrc file is ignored. This is the default.
OPTIONAL
The .netrc file is optional, and information in the URL is preferred.
The file will be scanned to find which ever information is not
specified in the URL.
REQUIRED
The .netrc file is required, and information in the URL is ignored.
NETRC_FILE <file>
Specify an alternative .netrc file to the one in your home directory if the
NETRC level is OPTIONAL or REQUIRED. If this option is not specified, the
value of the CMAKE_NETRC_FILE variable will be used instead (see
file(DOWNLOAD))
Git NOTE: A git version of 1.6.5 or later is required if this download method is used.
GIT_REPOSITORY <url>
URL of the git repository. Any URL understood by the git command may be used.
GIT_TAG <tag>
Git branch name, tag or commit hash. Note that branch names and tags should
generally be specified as remote names (i.e. origin/myBranch rather than
simply myBranch). This ensures that if the remote end has its tag moved or
branch rebased or history rewritten, the local clone will still be updated
correctly. In general, however, specifying a commit hash should be preferred
for a number of reasons:
• If the local clone already has the commit corresponding to the hash, no git
fetch needs to be performed to check for changes each time CMake is re-run.
This can result in a significant speed up if many external projects are
being used.
• Using a specific git hash ensures that the main project’s own history is
fully traceable to a specific point in the external project’s evolution. If
a branch or tag name is used instead, then checking out a specific commit
of the main project doesn’t necessarily pin the whole build to a specific
point in the life of the external project. The lack of such deterministic
behavior makes the main project lose traceability and repeatability.
If GIT_SHALLOW is enabled then GIT_TAG works only with branch names and tags.
A commit hash is not allowed.
GIT_REMOTE_NAME <name>
The optional name of the remote. If this option is not specified, it defaults
to origin.
GIT_SUBMODULES <module>...
Specific git submodules that should also be updated. If this option is not
provided, all git submodules will be updated.
GIT_SHALLOW <bool>
When this option is enabled, the git clone operation will be given the
--depth 1 option. This performs a shallow clone, which avoids downloading the
whole history and instead retrieves just the commit denoted by the GIT_TAG
option.
GIT_PROGRESS <bool>
When enabled, this option instructs the git clone operation to report its
progress by passing it the --progress option. Without this option, the clone
step for large projects may appear to make the build stall, since nothing
will be logged until the clone operation finishes. While this option can be
used to provide progress to prevent the appearance of the build having
stalled, it may also make the build overly noisy if lots of external projects
are used.
GIT_CONFIG <option1> [<option2>...]
Specify a list of config options to pass to git clone. Each option listed
will be transformed into its own --config <option> on the git clone command
line, with each option required to be in the form key=value.
Subversion
SVN_REPOSITORY <url>
URL of the Subversion repository.
SVN_REVISION -r<rev>
Revision to checkout from the Subversion repository.
SVN_USERNAME <username>
Username for the Subversion checkout and update.
SVN_PASSWORD <password>
Password for the Subversion checkout and update.
SVN_TRUST_CERT <bool>
Specifies whether to trust the Subversion server site certificate. If
enabled, the --trust-server-cert option is passed to the svn checkout and
update commands.
Mercurial
HG_REPOSITORY <url>
URL of the mercurial repository.
HG_TAG <tag>
Mercurial branch name, tag or commit id.
CVS
CVS_REPOSITORY <cvsroot>
CVSROOT of the CVS repository.
CVS_MODULE <mod>
Module to checkout from the CVS repository.
CVS_TAG <tag>
Tag to checkout from the CVS repository.
Update/Patch Step Options:
Whenever CMake is re-run, by default the external project’s sources will be updated if the
download method supports updates (e.g. a git repository would be checked if the GIT_TAG
does not refer to a specific commit).
UPDATE_COMMAND <cmd>...
Overrides the download method’s update step with a custom command. The command may
use generator expressions.
UPDATE_DISCONNECTED <bool>
When enabled, this option causes the update step to be skipped. It does not,
however, prevent the download step. The update step can still be added as a step
target (see ExternalProject_Add_StepTargets()) and called manually. This is useful
if you want to allow developers to build the project when disconnected from the
network (the network may still be needed for the download step though).
When this option is present, it is generally advisable to make the value a cache
variable under the developer’s control rather than hard-coding it. If this option is
not present, the default value is taken from the EP_UPDATE_DISCONNECTED directory
property. If that is also not defined, updates are performed as normal. The
EP_UPDATE_DISCONNECTED directory property is intended as a convenience for
controlling the UPDATE_DISCONNECTED behavior for an entire section of a project’s
directory hierarchy and may be a more convenient method of giving developers control
over whether or not to perform updates (assuming the project also provides a cache
variable or some other convenient method for setting the directory property).
PATCH_COMMAND <cmd>...
Specifies a custom command to patch the sources after an update. By default, no
patch command is defined. Note that it can be quite difficult to define an
appropriate patch command that performs robustly, especially for download methods
such as git where changing the GIT_TAG will not discard changes from a previous
patch, but the patch command will be called again after updating to the new tag.
Configure Step Options:
The configure step is run after the download and update steps. By default, the external
project is assumed to be a CMake project, but this can be overridden if required.
CONFIGURE_COMMAND <cmd>...
The default configure command runs CMake with options based on the main project. For
non-CMake external projects, the CONFIGURE_COMMAND option must be used to override
this behavior (generator expressions are supported). For projects that require no
configure step, specify this option with an empty string as the command to execute.
CMAKE_COMMAND /.../cmake
Specify an alternative cmake executable for the configure step (use an absolute
path). This is generally not recommended, since it is usually desirable to use the
same CMake version throughout the whole build. This option is ignored if a custom
configure command has been specified with CONFIGURE_COMMAND.
CMAKE_GENERATOR <gen>
Override the CMake generator used for the configure step. Without this option, the
same generator as the main build will be used. This option is ignored if a custom
configure command has been specified with the CONFIGURE_COMMAND option.
CMAKE_GENERATOR_PLATFORM <platform>
Pass a generator-specific platform name to the CMake command (see
CMAKE_GENERATOR_PLATFORM). It is an error to provide this option without the
CMAKE_GENERATOR option.
CMAKE_GENERATOR_TOOLSET <toolset>
Pass a generator-specific toolset name to the CMake command (see
CMAKE_GENERATOR_TOOLSET). It is an error to provide this option without the
CMAKE_GENERATOR option.
CMAKE_GENERATOR_INSTANCE <instance>
Pass a generator-specific instance selection to the CMake command (see
CMAKE_GENERATOR_INSTANCE). It is an error to provide this option without the
CMAKE_GENERATOR option.
CMAKE_ARGS <arg>...
The specified arguments are passed to the cmake command line. They can be any
argument the cmake command understands, not just cache values defined by -D...
arguments (see also CMake Options). In addition, arguments may use generator
expressions.
CMAKE_CACHE_ARGS <arg>...
This is an alternate way of specifying cache variables where command line length
issues may become a problem. The arguments are expected to be in the form
-Dvar:STRING=value, which are then transformed into CMake set() commands with the
FORCE option used. These set() commands are written to a pre-load script which is
then applied using the cmake -C command line option. Arguments may use generator
expressions.
CMAKE_CACHE_DEFAULT_ARGS <arg>...
This is the same as the CMAKE_CACHE_ARGS option except the set() commands do not
include the FORCE keyword. This means the values act as initial defaults only and
will not override any variables already set from a previous run. Use this option
with care, as it can lead to different behavior depending on whether the build
starts from a fresh build directory or re-uses previous build contents.
SOURCE_SUBDIR <dir>
When no CONFIGURE_COMMAND option is specified, the configure step assumes the
external project has a CMakeLists.txt file at the top of its source tree (i.e. in
SOURCE_DIR). The SOURCE_SUBDIR option can be used to point to an alternative
directory within the source tree to use as the top of the CMake source tree instead.
This must be a relative path and it will be interpreted as being relative to
SOURCE_DIR. When BUILD_IN_SOURCE 1 is specified, the BUILD_COMMAND is used to point
to an alternative directory within the source tree.
Build Step Options:
If the configure step assumed the external project uses CMake as its build system, the
build step will also. Otherwise, the build step will assume a Makefile-based build and
simply run make with no arguments as the default build step. This can be overridden with
custom build commands if required.
BUILD_COMMAND <cmd>...
Overrides the default build command (generator expressions are supported). If this
option is not given, the default build command will be chosen to integrate with the
main build in the most appropriate way (e.g. using recursive make for Makefile
generators or cmake --build if the project uses a CMake build). This option can be
specified with an empty string as the command to make the build step do nothing.
BUILD_IN_SOURCE <bool>
When this option is enabled, the build will be done directly within the external
project’s source tree. This should generally be avoided, the use of a separate build
directory is usually preferred, but it can be useful when the external project
assumes an in-source build. The BINARY_DIR option should not be specified if
building in-source.
BUILD_ALWAYS <bool>
Enabling this option forces the build step to always be run. This can be the easiest
way to robustly ensure that the external project’s own build dependencies are
evaluated rather than relying on the default success timestamp-based method. This
option is not normally needed unless developers are expected to modify something the
external project’s build depends on in a way that is not detectable via the step
target dependencies (e.g. SOURCE_DIR is used without a download method and
developers might modify the sources in SOURCE_DIR).
BUILD_BYPRODUCTS <file>...
Specifies files that will be generated by the build command but which might or might
not have their modification time updated by subsequent builds. These ultimately get
passed through as BYPRODUCTS to the build step’s own underlying call to
add_custom_command().
Install Step Options:
If the configure step assumed the external project uses CMake as its build system, the
install step will also. Otherwise, the install step will assume a Makefile-based build and
simply run make install as the default build step. This can be overridden with custom
install commands if required.
INSTALL_COMMAND <cmd>...
The external project’s own install step is invoked as part of the main project’s
build. It is done after the external project’s build step and may be before or after
the external project’s test step (see the TEST_BEFORE_INSTALL option below). The
external project’s install rules are not part of the main project’s install rules,
so if anything from the external project should be installed as part of the main
build, these need to be specified in the main build as additional install()
commands. The default install step builds the install target of the external
project, but this can be overridden with a custom command using this option
(generator expressions are supported). Passing an empty string as the <cmd> makes
the install step do nothing.
Test Step Options:
The test step is only defined if at least one of the following TEST_... options are
provided.
TEST_COMMAND <cmd>...
Overrides the default test command (generator expressions are supported). If this
option is not given, the default behavior of the test step is to build the external
project’s own test target. This option can be specified with <cmd> as an empty
string, which allows the test step to still be defined, but it will do nothing. Do
not specify any of the other TEST_... options if providing an empty string as the
test command, but prefer to omit all TEST_... options altogether if the test step
target is not needed.
TEST_BEFORE_INSTALL <bool>
When this option is enabled, the test step will be executed before the install step.
The default behavior is for the test step to run after the install step.
TEST_AFTER_INSTALL <bool>
This option is mainly useful as a way to indicate that the test step is desired but
all default behavior is sufficient. Specifying this option with a boolean true value
ensures the test step is defined and that it comes after the install step. If both
TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL are enabled, the latter is silently
ignored.
TEST_EXCLUDE_FROM_MAIN <bool>
If enabled, the main build’s default ALL target will not depend on the test step.
This can be a useful way of ensuring the test step is defined but only gets invoked
when manually requested.
Output Logging Options:
Each of the following LOG_... options can be used to wrap the relevant step in a script to
capture its output to files. The log files will be created in LOG_DIR if supplied or
otherwise the STAMP_DIR directory with step-specific file names.
LOG_DOWNLOAD <bool>
When enabled, the output of the download step is logged to files.
LOG_UPDATE <bool>
When enabled, the output of the update step is logged to files.
LOG_PATCH <bool>
When enabled, the output of the patch step is logged to files.
LOG_CONFIGURE <bool>
When enabled, the output of the configure step is logged to files.
LOG_BUILD <bool>
When enabled, the output of the build step is logged to files.
LOG_INSTALL <bool>
When enabled, the output of the install step is logged to files.
LOG_TEST <bool>
When enabled, the output of the test step is logged to files.
LOG_MERGED_STDOUTERR <bool>
When enabled, stdout and stderr will be merged for any step whose output is being
logged to files.
LOG_OUTPUT_ON_FAILURE <bool>
This option only has an effect if at least one of the other LOG_<step> options is
enabled. If an error occurs for a step which has logging to file enabled, that
step’s output will be printed to the console if LOG_OUTPUT_ON_FAILURE is set to
true. For cases where a large amount of output is recorded, just the end of that
output may be printed to the console.
Terminal Access Options:
Steps can be given direct access to the terminal in some cases. Giving a step access to the
terminal may allow it to receive terminal input if required, such as for authentication
details not provided by other options. With the Ninja generator, these options place the
steps in the console job pool. Each step can be given access to the terminal individually
via the following options:
USES_TERMINAL_DOWNLOAD <bool>
Give the download step access to the terminal.
USES_TERMINAL_UPDATE <bool>
Give the update step access to the terminal.
USES_TERMINAL_CONFIGURE <bool>
Give the configure step access to the terminal.
USES_TERMINAL_BUILD <bool>
Give the build step access to the terminal.
USES_TERMINAL_INSTALL <bool>
Give the install step access to the terminal.
USES_TERMINAL_TEST <bool>
Give the test step access to the terminal.
Target Options:
DEPENDS <targets>...
Specify other targets on which the external project depends. The other targets will
be brought up to date before any of the external project’s steps are executed.
Because the external project uses additional custom targets internally for each
step, the DEPENDS option is the most convenient way to ensure all of those steps
depend on the other targets. Simply doing add_dependencies(<name> <targets>) will
not make any of the steps dependent on <targets>.
EXCLUDE_FROM_ALL <bool>
When enabled, this option excludes the external project from the default ALL target
of the main build.
STEP_TARGETS <step-target>...
Generate custom targets for the specified steps. This is required if the steps need
to be triggered manually or if they need to be used as dependencies of other
targets. If this option is not specified, the default value is taken from the
EP_STEP_TARGETS directory property. See ExternalProject_Add_Step() below for
further discussion of the effects of this option.
INDEPENDENT_STEP_TARGETS <step-target>...
Generate custom targets for the specified steps and prevent these targets from
having the usual dependencies applied to them. If this option is not specified, the
default value is taken from the EP_INDEPENDENT_STEP_TARGETS directory property. This
option is mostly useful for allowing individual steps to be driven independently,
such as for a CDash setup where each step should be initiated and reported
individually rather than as one whole build. See ExternalProject_Add_Step() below
for further discussion of the effects of this option.
Miscellaneous Options:
LIST_SEPARATOR <sep>
For any of the various ..._COMMAND options, replace ; with <sep> in the specified
command lines. This can be useful where list variables may be given in commands
where they should end up as space-separated arguments (<sep> would be a single space
character string in this case).
COMMAND <cmd>...
Any of the other ..._COMMAND options can have additional commands appended to them
by following them with as many COMMAND ... options as needed (generator expressions
are supported). For example:
ExternalProject_Add(example
... # Download options, etc.
BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
)
It should also be noted that each build step is created via a call to ExternalProject_Add_Step().
See that command’s documentation for the automatic substitutions that are supported for some
options.
Obtaining Project Properties
ExternalProject_Get_Property
The ExternalProject_Get_Property() function retrieves external project target properties:
ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
The function stores property values in variables of the same name. Property names correspond to
the keyword argument names of ExternalProject_Add(). For example, the source directory might be
retrieved like so:
ExternalProject_Get_property(myExtProj SOURCE_DIR)
message("Source dir of myExtProj = ${SOURCE_DIR}")
Explicit Step Management
The ExternalProject_Add() function on its own is often sufficient for incorporating an external project
into the main build. Certain scenarios require additional work to implement desired behavior, such as
adding in a custom step or making steps available as manually triggerable targets. The
ExternalProject_Add_Step(), ExternalProject_Add_StepTargets() and ExternalProject_Add_StepDependencies
functions provide the lower level control needed to implement such step-level capabilities.
ExternalProject_Add_Step
The ExternalProject_Add_Step() function specifies an additional custom step for an external
project defined by an earlier call to ExternalProject_Add():
ExternalProject_Add_Step(<name> <step> [<option>...])
<name> is the same as the name passed to the original call to ExternalProject_Add(). The specified
<step> must not be one of the pre-defined steps (mkdir, download, update, skip-update, patch,
configure, build, install or test). The supported options are:
COMMAND <cmd>...
The command line to be executed by this custom step (generator expressions are supported).
This option can be repeated multiple times to specify multiple commands to be executed in
order.
COMMENT "<text>..."
Text to be printed when the custom step executes.
DEPENDEES <step>...
Other steps (custom or pre-defined) on which this step depends.
DEPENDERS <step>...
Other steps (custom or pre-defined) that depend on this new custom step.
DEPENDS <file>...
Files on which this custom step depends.
BYPRODUCTS <file>...
Files that will be generated by this custom step but which might or might not have their
modification time updated by subsequent builds. This list of files will ultimately be
passed through as the BYPRODUCTS option to the add_custom_command() used to implement the
custom step internally.
ALWAYS <bool>
When enabled, this option specifies that the custom step should always be run (i.e. that it
is always considered out of date).
EXCLUDE_FROM_MAIN <bool>
When enabled, this option specifies that the external project’s main target does not depend
on the custom step.
WORKING_DIRECTORY <dir>
Specifies the working directory to set before running the custom step’s command. If this
option is not specified, the directory will be the value of the CMAKE_CURRENT_BINARY_DIR at
the point where ExternalProject_Add_Step() was called.
LOG <bool>
If set, this causes the output from the custom step to be captured to files in the external
project’s LOG_DIR if supplied or STAMP_DIR.
USES_TERMINAL <bool>
If enabled, this gives the custom step direct access to the terminal if possible.
The command line, comment, working directory and byproducts of every standard and custom step are
processed to replace the tokens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR>
<TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with their corresponding property values defined
in the original call to ExternalProject_Add().
ExternalProject_Add_StepTargets
The ExternalProject_Add_StepTargets() function generates targets for the steps listed. The name of
each created target will be of the form <name>-<step>:
ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
Creating a target for a step allows it to be used as a dependency of another target or to be
triggered manually. Having targets for specific steps also allows them to be driven independently
of each other by specifying targets on build command lines. For example, you may be submitting to
a sub-project based dashboard where you want to drive the configure portion of the build, then
submit to the dashboard, followed by the build portion, followed by tests. If you invoke a custom
target that depends on a step halfway through the step dependency chain, then all the previous
steps will also run to ensure everything is up to date.
If the NO_DEPENDS option is specified, the step target will not depend on the dependencies of the
external project (i.e. on any dependencies of the <name> custom target created by
ExternalProject_Add()). This is usually safe for the download, update and patch steps, since they
do not typically require that the dependencies are updated and built. Using NO_DEPENDS for any of
the other pre-defined steps, however, may break parallel builds. Only use NO_DEPENDS where it is
certain that the named steps genuinely do not have dependencies. For custom steps, consider
whether or not the custom commands require the dependencies to be configured, built and installed.
Internally, ExternalProject_Add() calls ExternalProject_Add_Step() to create each step. If any
STEP_TARGETS or INDEPENDENT_STEP_TARGETS were specified, then ExternalProject_Add_StepTargets()
will also be called after ExternalProject_Add_Step(). INDEPENDENT_STEP_TARGETS have the NO_DEPENDS
option set, whereas STEP_TARGETS do not. Other than that, the two options result in
ExternalProject_Add_StepTargets() being called in the same way. Even if a step is not mentioned in
either of those two options, ExternalProject_Add_StepTargets() can still be called later to
manually define a target for the step.
The STEP_TARGETS and INDEPENDENT_STEP_TARGETS options for ExternalProject_Add() are generally the
easiest way to ensure targets are created for specific steps of interest. For custom steps,
ExternalProject_Add_StepTargets() must be called explicitly if a target should also be created for
that custom step. An alternative to these two options is to populate the EP_STEP_TARGETS and
EP_INDEPENDENT_STEP_TARGETS directory properties. These act as defaults for the step target
options and can save having to repeatedly specify the same set of step targets when multiple
external projects are being defined.
ExternalProject_Add_StepDependencies
The ExternalProject_Add_StepDependencies() function can be used to add dependencies to a step. The
dependencies added must be targets CMake already knows about (these can be ordinary executable or
library targets, custom targets or even step targets of another external project):
ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
This function takes care to set both target and file level dependencies and will ensure that
parallel builds will not break. It should be used instead of add_dependencies() whenever adding a
dependency for some of the step targets generated by the ExternalProject module.
Examples
The following example shows how to download and build a hypothetical project called FooBar from github:
include(ExternalProject)
ExternalProject_Add(foobar
GIT_REPOSITORY git@github.com:FooCo/FooBar.git
GIT_TAG origin/release/1.2.3
)
For the sake of the example, also define a second hypothetical external project called SecretSauce, which
is downloaded from a web server. Two URLs are given to take advantage of a faster internal network if
available, with a fallback to a slower external server. The project is a typical Makefile project with no
configure step, so some of the default commands are overridden. The build is only required to build the
sauce target:
find_program(MAKE_EXE NAMES gmake nmake make)
ExternalProject_Add(secretsauce
URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
https://www.somecompany.com/downloads/sauce-2.7.zip
URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
CONFIGURE_COMMAND ""
BUILD_COMMAND ${MAKE_EXE} sauce
)
Suppose the build step of secretsauce requires that foobar must already be built. This could be enforced
like so:
ExternalProject_Add_StepDependencies(secretsauce build foobar)
Another alternative would be to create a custom target for foobar’s build step and make secretsauce
depend on that rather than the whole foobar project. This would mean foobar only needs to be built, it
doesn’t need to run its install or test steps before secretsauce can be built. The dependency can also be
defined along with the secretsauce project:
ExternalProject_Add_StepTargets(foobar build)
ExternalProject_Add(secretsauce
URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
https://www.somecompany.com/downloads/sauce-2.7.zip
URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
CONFIGURE_COMMAND ""
BUILD_COMMAND ${MAKE_EXE} sauce
DEPENDS foobar-build
)
Instead of calling ExternalProject_Add_StepTargets(), the target could be defined along with the foobar
project itself:
ExternalProject_Add(foobar
GIT_REPOSITORY git@github.com:FooCo/FooBar.git
GIT_TAG origin/release/1.2.3
STEP_TARGETS build
)
If many external projects should have the same set of step targets, setting a directory property may be
more convenient. The build step target could be created automatically by setting the EP_STEP_TARGETS
directory property before creating the external projects with ExternalProject_Add():
set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
Lastly, suppose that secretsauce provides a script called makedoc which can be used to generate its own
documentation. Further suppose that the script expects the output directory to be provided as the only
parameter and that it should be run from the secretsauce source directory. A custom step and a custom
target to trigger the script can be defined like so:
ExternalProject_Add_Step(secretsauce docs
COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
WORKING_DIRECTORY <SOURCE_DIR>
COMMENT "Building secretsauce docs"
ALWAYS TRUE
EXCLUDE_FROM_MAIN TRUE
)
ExternalProject_Add_StepTargets(secretsauce docs)
The custom step could then be triggered from the main build like so:
cmake --build . --target secretsauce-docs
CMakeParseArguments
Parse arguments given to a macro or a function.
cmake_parse_arguments() is intended to be used in macros or functions for parsing the arguments given to
that macro or function. It processes the arguments and defines a set of variables which hold the values
of the respective options.
cmake_parse_arguments(<prefix>
<options>
<one_value_keywords>
<multi_value_keywords>
[CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY|CMAKE_PARSE_ARGUMENTS_KEEP_EMPTY]
args...
)
The <options> argument contains all options for the respective macro, i.e. keywords which can be used
when calling the macro without any value following, like e.g. the OPTIONAL keyword of the install()
command.
The <one_value_keywords> argument contains all keywords for this macro which are followed by one value,
like e.g. DESTINATION keyword of the install() command.
The <multi_value_keywords> argument contains all keywords for this macro which can be followed by more
than one value, like e.g. the TARGETS or FILES keywords of the install() command.
When done, cmake_parse_arguments() will have defined for each of the keywords listed in <options>,
<one_value_keywords> and <multi_value_keywords> a variable composed of the given <prefix> followed by “_”
and the name of the respective keyword. These variables will then hold the respective value from the
argument list. For the <options> keywords this will be TRUE or FALSE.
All remaining arguments are collected in a variable <prefix>_UNPARSED_ARGUMENTS, this can be checked
afterwards to see whether your macro was called with unrecognized parameters.
The cmake CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY (old behaviour) and CMAKE_PARSE_ARGUMENTS_KEEP_EMPTY options
decide how empty arguments should be handled. If none of these options is set, for backwards
compatibility, if CMAKE_MINIMUM_REQUIRED_VERSION < 3.0.0, the default behaviour is to skip empty
arguments, otherwise the default behaviour is to keep them. Using the
CMAKE_PARSE_ARGUMENTS_DEFAULT_SKIP_EMPTY variable the user can explicitly set the default behaviour in
current scope.
As an example here a my_install() macro, which takes similar arguments as the real install() command:
function(MY_INSTALL)
set(options OPTIONAL FAST)
set(oneValueArgs DESTINATION RENAME)
set(multiValueArgs TARGETS CONFIGURATIONS)
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}" )
...
Assume my_install() has been called like this:
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
After the cmake_parse_arguments() call the macro will have set the following variables:
MY_INSTALL_OPTIONAL = TRUE
MY_INSTALL_FAST = FALSE (this option was not used when calling my_install()
MY_INSTALL_DESTINATION = "bin"
MY_INSTALL_RENAME = "" (was not used)
MY_INSTALL_TARGETS = "foo;bar"
MY_INSTALL_CONFIGURATIONS = "" (was not used)
MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (no value expected after "OPTIONAL"
You can then continue and process these variables.
Keywords terminate lists of values, e.g. if directly after a one_value_keyword another recognized
keyword follows, this is interpreted as the beginning of the new option. E.g. my_install(TARGETS foo
DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to “OPTIONAL”, but
MY_INSTALL_DESTINATION would be empty and MY_INSTALL_OPTIONAL would be set to TRUE therefore.
If the “CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY” option is set, cmake_parse_argumentswill not consider empty
arguments. Therefore
my_install(DESTINATION "" TARGETS foo "" bar)
Will set
MY_INSTALL_DESTINATION = (unset)
MY_INSTALL_MULTI = "foo;bar"
Using the “CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY” option instead, will set
MY_INSTALL_SINGLE = ""
MY_INSTALL_MULTI = "foo;;bar"
It is also important to note that:
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}" )
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
Will behave differently, because in the latter case empty arguments are not passed to
cmake_parse_arguments.
DEPRECATED MODULES
WARNING:
These modules are deprecated and should not be used in new code.
YCMDefaultDirs
COPYRIGHT
Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT)
0.13. Nov 05, 2023 YCM-MODULES(7)