Provided by: ycm-cmake-modules_0.13.0-2_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)