.\" Man page generated from reStructuredText.
.
.TH "YCM-MODULES" "7" "Jan 15, 2021" "0.12." "YCM"
.SH NAME
ycm-modules \- YCM Modules Reference
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH GENERIC MODULES
.SS ExtractVersion
.sp
Extracts version numbers from a version string:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
extract_version (<name> [REVERSE_NAME])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Tries to extract the following variables (the second version is used
if REVERSE_NAME is set as argument):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS GetAllCMakeProperties
.sp
Return a list containing the names of all known CMake Properties.
.sp
Only properties returned by \fBcmake \-\-help\-property\-list\fP are returned,
custom properties will not be on the returned list.
.sp
Properties containing \fB<CONFIG>\fP or \fB<LANG>\fP are expanded to the correct
property name.
.SS GitInfo
.sp
Extract information from a git repository.
.INDENT 0.0
.TP
.B git_commit_info
Extract information about one commit from one git repository in
\fBSOURCE DIR\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
git_commit_info([SOURCE DIR <dir>]
                [PREFIX <prefix>]
                [REVISION <rev>]
                [FATAL])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If \fBSOURCE_DIR\fP is a git repository, it checks the given
\fBREVISION\fP and sets the following variables:
.INDENT 7.0
.TP
.B \fB<PREFIX>_GIT_COMMIT_DESCRIBE\fP
The output of \fBgit describe <ref>\fP\&.
.TP
.B \fB<PREFIX>_GIT_COMMIT_DESCRIBE_CONTAINS\fP
The output of \fBgit describe \-\-contains <ref>\fP\&.
.TP
.B \fB<PREFIX>_GIT_COMMIT_TAG\fP
The most recent tag that is reachable from a commit.
.TP
.B \fB<PREFIX>_GIT_COMMIT_REVISION\fP
The number of commits since the beginning of the git history.
.TP
.B \fB<PREFIX>_GIT_COMMIT_TAG_REVISION\fP
The number of commits since the last tag.
.TP
.B \fB<PREFIX>_GIT_COMMIT_DATE_REVISION\fP
The number of commits since the beginning of the day.
.TP
.B \fB<PREFIX>_GIT_COMMIT_AUTHOR_DATE\fP
The commit author date.
.TP
.B \fB<PREFIX>_GIT_COMMIT_AUTHOR_TIME\fP
The commit author time.
.TP
.B \fB<PREFIX>_GIT_COMMIT_AUTHOR_TZ\fP
The commit author time zone.
.TP
.B \fB<PREFIX>_GIT_COMMIT_AUTHOR_NAME\fP
The commit author name.
.TP
.B \fB<PREFIX>_GIT_COMMIT_AUTHOR_EMAIL\fP
The commit author e\-mail.
.TP
.B \fB<PREFIX>_GIT_COMMIT_COMMITTER_DATE\fP
The commit committer date.
.TP
.B \fB<PREFIX>_GIT_COMMIT_COMMITTER_TIME\fP
The commit author time.
.TP
.B \fB<PREFIX>_GIT_COMMIT_COMMITTER_TZ\fP
The commit author time zone.
.TP
.B \fB<PREFIX>_GIT_COMMIT_COMMITTER_NAME\fP
The commit committer name.
.TP
.B \fB<PREFIX>_GIT_COMMIT_COMMITTER_EMAIL\fP
The commit committer email.
.TP
.B \fB<PREFIX>_GIT_COMMIT_HASH\fP
The commit hash.
.TP
.B \fB<PREFIX>_GIT_COMMIT_HASH_SHORT\fP
The abbreviated commit hash.
.TP
.B \fB<PREFIX>_GIT_COMMIT_SUBJECT\fP
The commit log message subject line.
.TP
.B \fB<PREFIX>_GIT_COMMIT_BODY\fP
The commit log message body.
.UNINDENT
.sp
If \fBSOURCE_DIR\fP is not set, then the \fBPROJECT_SOURCE_DIR\fP cmake
variable is used.
.sp
If \fBPREFIX\fP is not set, then the \fBPROJECT_NAME\fP cmake variable is
used.
.sp
\fBREVISION\fP can be a commit hash, a tag, a branch, or anything that
git can parse as a revision. If \fBREVISION\(ga is not set, then \(ga\(gaHEAD\fP
is used.
.sp
If \fBFATAL\fP 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.
.UNINDENT
.INDENT 0.0
.TP
.B git_wt_info
Extract information about current working tree from one git
repository in \fBSOURCE DIR\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
git_wt_info([SOURCE DIR <dir>]
            [PREFIX <prefix>]
            [FATAL])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If \fBSOURCE_DIR\fP is a git repository, it checks current revision and
sets the following variables:
.INDENT 7.0
.TP
.B \fB<PREFIX>_GIT_WT_DESCRIBE\fP
The output of \fBgit describe HEAD\fP\&.
.TP
.B \fB<PREFIX>_GIT_WT_DESCRIBE_CONTAINS\fP
The output of \fBgit describe \-\-contains HEAD\fP\&.
.TP
.B \fB<PREFIX>_GIT_WT_TAG\fP
The most recent tag that is reachable from current commit.
.TP
.B \fB<PREFIX>_GIT_WT_REVISION\fP
The number of commits since the beginning of the git history.
.TP
.B \fB<PREFIX>_GIT_WT_TAG_REVISION\fP
The number of commits since the last tag.
.TP
.B \fB<PREFIX>_GIT_WT_DATE_REVISION\fP
The number of commits since the beginning of the day.
.TP
.B \fB<PREFIX>_GIT_WT_AUTHOR_DATE\fP
The current commit author date.
.TP
.B \fB<PREFIX>_GIT_WT_AUTHOR_TIME\fP
The current commit author time.
.TP
.B \fB<PREFIX>_GIT_WT_AUTHOR_TZ\fP
The current commit author time zone.
.TP
.B \fB<PREFIX>_GIT_WT_AUTHOR_NAME\fP
The current commit author name.
.TP
.B \fB<PREFIX>_GIT_WT_AUTHOR_EMAIL\fP
The current commit author e\-mail.
.TP
.B \fB<PREFIX>_GIT_WT_COMMITTER_DATE\fP
The current commit committer date.
.TP
.B \fB<PREFIX>_GIT_WT_COMMITTER_TIME\fP
The current commit author time.
.TP
.B \fB<PREFIX>_GIT_WT_COMMITTER_TZ\fP
The current commit author time zone.
.TP
.B \fB<PREFIX>_GIT_WT_COMMITTER_NAME\fP
The current commit committer name.
.TP
.B \fB<PREFIX>_GIT_WT_COMMITTER_EMAIL\fP
The current commit committer email.
.TP
.B \fB<PREFIX>_GIT_WT_HASH\fP
The current commit hash.
.TP
.B \fB<PREFIX>_GIT_WT_HASH_SHORT\fP
The abbreviated commit hash.
.TP
.B \fB<PREFIX>_GIT_WT_SUBJECT\fP
The current commit log message subject line.
.TP
.B \fB<PREFIX>_GIT_WT_BODY\fP
The current commit log message body.
.TP
.B \fB<PREFIX>_GIT_WT_DIRTY\fP
Whether the current working tree is clean or not.
.UNINDENT
.sp
If \fBSOURCE_DIR\fP is not set, then the \fBPROJECT_SOURCE_DIR\fP cmake
variable is used.
.sp
If \fBPREFIX\fP is not set, then the \fBPROJECT_NAME\fP cmake variable is
used.
.sp
If \fBFATAL\fP 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.
.UNINDENT
.SS IncludeUrl
.sp
Adds the \fI\%include_url()\fP command that useful to download and include
other CMake modules from a given url.
.INDENT 0.0
.TP
.B include_url
.UNINDENT
.sp
Downloads a file from given url and includes it:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include_url(<url>                 # Url to be downloaded
   [DESTINATION <destination>]    # Where the file will be saved
   [EXPECTED_HASH <ALGO=value>]   # Verify downloaded file\(aqs 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\(aqt 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
   )
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fBinclude_url\fP macro downloads a file from given url and includes it.
It works both in \-P script mode and when configuring a CMakeLists.txt file.
.sp
If \fBDESTINATION\fP is specified, the file is saved at the given location with
the original  file name, if \fB<destination>\fP is a directory, or with the
given file  name, if \fB<destination>\fP is a file name.
.sp
The arguments \fBEXPECTED_HASH\fP, \fBEXPECTED_MD5\fP are used to ensure that the
file included is the one expected. If the \fB<url>\fP is a local file (i.e.
starts with \fBfile://\fP) the hash check is performed also on the file
converted to the non\-native end\-of\-line style.  See the documentation of the
\fI\%file()\fP command for further information about these arguments.
.sp
If the \fBDOWNLOAD_ONCE\fP option is specified, the file is not
downloaded if the file already exists and the hash is correct.
If the \fBDOWNLOAD_ALWAYS\fP 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.
.sp
If the \fBOPTIONAL\fP option is specified, no error will be caused if for any
reason the file cannot be downloaded or included.
If \fBRESULT_VARIABLE\fP 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 \fI\%file()\fP command for further information
about these arguments.
.sp
If the \fBRETRIES\fP option is specified, the download will be tried
If the \fBQUIET\fP option is specified, the command will emit no output.
.sp
The arguments \fBINACTIVITY_TIMEOUT\fP, \fBTIMEOUT\fP, \fBSTATUS\fP, \fBLOG\fP,
\fBSHOW_PROGRESS\fP, \fBTLS_VERIFY\fP, and \fBTLS_CAINFO\fP are passed to the
\fI\%file(DOWNLOAD)\fP command.  See the documentation of the
\fI\%file()\fP command for a detailed description of these arguments.
.sp
The arguments \fBNO_POLICY_SCOPE\fP is passed to the \fI\%include()\fP
command.  See the documentation of the \fI\%include()\fP and
\fI\%cmake_policy()\fP commands for a detailed description of this
argument.
.SS ReplaceImportedTargets
.sp
Adds the \fI\%replace_imported_targets()\fP command that useful to
replace paths with imported targets in link variables (like
\fB<FOO>_LIBRARIES\fP) and targets.
.INDENT 0.0
.TP
.B replace_imported_targets
.UNINDENT
.sp
Replace imported targets in a list of and targets and paths:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
replace_imported_targets(<var> [target [target [...]]])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Each path in \fBvar\fP corrisponding to one of the \fBtargets\fP will be
replaced with the corrisponding \fBtarget\fP, taking care to remove the
relative \fBoptimized\fP and \fBdebug\fP keywords.
.sp
For each existing target in \fBvar\fP, the following properties will be
searched for imported locations of targets, and, if set, will be
replaced in the same way:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS StandardFindModule
.sp
Try to find a package using a cmake config file, or pkgconfig:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
standard_find_module(<name>
                     <pkgconfig name>
                     [NOT_REQUIRED]
                     [QUIET]
                     [SKIP_CMAKE_CONFIG]
                     [SKIP_PKG_CONFIG]
                     [TARGET <target>]
                     [REPLACE_TARGETS <target> [...]]
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the package is found, the following variables (where possible)
are created:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For each library that requires to be linked (i.e. \fB\-llib\fP) it
creates:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<name>_<LIB>_LIBRARY_RELEASE (cached, advanced)
<name>_<LIB>_LIBRARY_DEBUG (cached, advanced, and empty by default)
<name>_<LIB>_LIBRARY
<name>_<LIB>_LIBRARY_FOUND
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In a \fBFindXXX.cmake\fP module, this macro can be used at the beginning.
The \fBNOT_REQUIRED\fP can be added to avoid failing if the package was not
found, but \fBpkg\-config\fP is installed.
The \fBQUIET\fP argument can be used to hide the output from
\fIfind_package_handle_standard_args\fP\&.
If \fB<name>_FOUND\fP is \fBFALSE\fP at the end, more “custom” searches can be
used (for windows, etc.)
.sp
If \fBSKIP_CMAKE_CONFIG\fP or \fBSKIP_PKG_CONFIG\fP are set, the relative step
is skipped
.sp
If \fBTARGET\fP is specified, in \fBpkg\-config\fP mode, an imported target will
be created using the first library returned by \fBpkg\-config\fP as imported
location.
.sp
The \fBREPLACE_TARGETS\fP 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.
.sp
If one of the \fBSTANDARD_FIND_MODULE_USE_IMPORTED_TARGET\fP or
\fBSTANDARD_FIND_MODULE_USE_IMPORTED_TARGET_<name>\fP are enabled, and
a \fBTARGET\fP is specified, the \fB<name>_LIBRARIES\fP variable content is
replaced with the imported target.
.sp
If one of the variables \fBSTANDARD_FIND_MODULE_DEBUG\fP or
\fBSTANDARD_FIND_MODULE_DEBUG_<name>\fP is enabled, prints more useful debug
output
.SH PACKAGING HELPER MODULES
.SS InstallBasicPackageFiles
.sp
A helper module to make your package easier to be found by other
projects.
.INDENT 0.0
.TP
.B install_basic_package_files
.UNINDENT
.sp
Create and install a basic version of cmake config files for your
project:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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>")
                           )
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Depending on \fBUPPERCASE_FILENAMES\fP and \fBLOWERCASE_FILENAMES\fP, this
function generates 3 files:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
\fB<Name>ConfigVersion.cmake\fP or \fB<name>\-config\-version.cmake\fP
.IP \(bu 2
\fB<Name>Config.cmake\fP or \fB<name>\-config.cmake\fP
.IP \(bu 2
\fB<Name>Targets.cmake\fP or \fB<name>\-targets.cmake\fP
.UNINDENT
.UNINDENT
.UNINDENT
.sp
If neither \fBUPPERCASE_FILENAMES\fP nor \fBLOWERCASE_FILENAMES\fP is
set, a file \fB<Name>Config.cmake.in\fP or
\fB<name>\-config.cmake.in\fP is searched, and the convention
is chosed according to the file found. If no file was found, the
uppercase convention is used.
.sp
The \fBDEPENDENCIES\fP argument can be used to set a list of dependencies
that will be searched using the \fBfind_dependency()\fP command
from the \fI\%CMakeFindDependencyMacro\fP module.
Dependencies can be followed by any of the possible
\fBfind_dependency()\fP argument.
In this case, all the arguments must be specified within double quotes (e.g.
\fB"<dependency> 1.0.0 EXACT"\fP, or \fB"<dependency> CONFIG"\fP).
The \fBPRIVATE_DEPENDENCIES\fP argument is similar to \fBDEPENDENCIES\fP, but
these dependencies are included only when \fI\%BUILD_SHARED_LIBS\fP is
\fBOFF\fP\&.
If a libraries is declared \fBSTATIC\fP, \fBOBJECT\fP or \fBINTERFACE\fP, and they
link to some dependency, these should be added using the \fBDEPENDENCIES\fP
argument, since the \fBPRIVATE_DEPENDENCIES\fP argument would work only when
\fI\%BUILD_SHARED_LIBS\fP is disabled.
.sp
When using a custom template file, the \fB@PACKAGE_DEPENDENCIES@\fP
string is replaced with the code checking for the dependencies
specified by these two argument.
.sp
If the \fBARCH_INDEPENDENT\fP option is enabled, the installed package version
will be considered compatible even if it was built for a different
architecture than the requested architecture.
.sp
Each file is generated twice, one for the build directory and one for
the installation directory.  The \fBINSTALL_DESTINATION\fP argument can be
passed to install the files in a location different from the default
one (\fB${CMAKE_INSTALL_DATADIR}/cmake/${Name}\fP if the \fBARCH_INDEPENDENT\fP
option is enabled, \fB${CMAKE_INSTALL_LIBDIR}/cmake/${Name}\fP otherwise).
The \fBEXPORT_DESTINATION\fP argument can be passed to
generate the files in the build tree in a location different from the default
one (\fBCMAKE_BINARY_DIR\fP).  If this is a relative path, it is
considered relative to the \fBCMAKE_CURRENT_BINARY_DIR\fP directory.
.sp
The build directory is exported to the CMake user package registry if the
build option \fBCMAKE_EXPORT_PACKAGE_REGISTRY\fP is set.
.sp
The \fB<Name>ConfigVersion.cmake\fP file is generated using
\fBwrite_basic_package_version_file()\fP\&. The \fBVERSION\fP,
\fBCOMPATIBILITY\fP, and 
.nf
\(ga\(ga
.fi
ARCH_INDEPENDENT\(ga\(gaarguments are passed to this
function.
.sp
\fBVERSION\fP shall be in the form \fB<major>[.<minor>[.<patch>[.<tweak>]]]]\fP\&.
If no \fBVERSION\fP is given, the \fBPROJECT_VERSION\fP variable is used.
If this hasn’t been set, it errors out.  The \fBVERSION\fP argument is also used
to replace the \fB@PACKAGE_VERSION@\fP string in the configuration file.
.sp
\fBCOMPATIBILITY\fP shall be any of the options accepted by the
\fBwrite_basic_package_version_file()\fP command
(\fBAnyNewerVersion\fP, \fBSameMajorVersion\fP, \fBSameMinorVersion\fP [CMake 3.11],
or \fBExactVersion\fP).
These options are explained in \fBwrite_basic_package_version_file()\fP
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.
.sp
The \fB<Name>Config.cmake\fP file is generated using
\fBconfigure_package_config_file()\fP\&. The
\fBNO_SET_AND_CHECK_MACRO\fP, \fBNO_CHECK_REQUIRED_COMPONENTS_MACRO\fP, and
arguments are passed to this function.
.sp
By default \fI\%install_basic_package_files()\fP also generates the two helper
macros \fBset_and_check()\fP and \fBcheck_required_components()\fP into the
\fB<Name>Config.cmake\fP file. \fBset_and_check()\fP should be used instead of the
normal \fI\%set()\fP 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 \fBFATAL_ERROR\fP otherwise.
This makes sure that the created \fB<Name>Config.cmake\fP file does not contain
wrong references.
When using the \fBNO_SET_AND_CHECK_MACRO, this macro is not generated into the
\(ga\(ga<Name>Config.cmake\fP file.
.sp
By default, \fI\%install_basic_package_files()\fP append a call to
\fBcheck_required_components(<Name>)\fP in \fB<Name>Config.cmake\fP 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
\fB<Name>_FOUND\fP variable to \fBFALSE\fP, so that the package is considered to
be not found. It does that by testing the \fB<Name>_<Component>_FOUND\fP
variables for all requested required components. When using the
\fBNO_CHECK_REQUIRED_COMPONENTS_MACRO\fP option, this macro is not generated
into the \fB<Name>Config.cmake\fP file.
.sp
Finally, the files in the build and install directory are exactly the same.
.sp
See the documentation of \fI\%CMakePackageConfigHelpers\fP module for
further information and references therein.
.sp
If the \fBCONFIG_TEMPLATE\fP argument is passed, the specified file
is used as template for generating the configuration file, otherwise
this module expects to find a \fB<Name>Config.cmake.in\fP or
\fB<name>\-config.cmake.in\fP file either in current source directory.
If the file does not exist, a very basic file is created.
.sp
A set of variables are checked and passed to
\fBconfigure_package_config_file()\fP as \fBPATH_VARS\fP\&. For each of the
\fBSUFFIX\fP considered, if one of the variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
<VARS_PREFIX>_(BUILD|INSTALL)_<SUFFIX>
(BUILD|INSTALL)_<VARS_PREFIX>_<SUFFIX>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
is defined, the \fB<VARS_PREFIX>_<SUFFIX>\fP variable will be defined
before configuring the package.  In order to use that variable in the
config file, you have to add a line:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set_and_check(<VARS_PREFIX>_<SUFFIX> \e"@PACKAGE_<VARS_PREFIX>_<SUFFIX>@\e")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
if the path must exist or just:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set(<VARS_PREFIX>_<SUFFIX> \e"@PACKAGE_<VARS_PREFIX>_<SUFFIX>@\e")
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
if the path could be missing.
.sp
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.
.sp
Default \fBPATH_VARS\fP suffixes are:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
more suffixes can be added using the \fBEXTRA_PATH_VARS_SUFFIX\fP
argument.
.sp
The \fB<Name>Targets.cmake\fP is generated using \fI\%export(EXPORT)\fP
in the build tree and \fI\%install(EXPORT)\fP in the installation
directory. The targets are exported using the value for the \fBNAMESPACE\fP
argument as namespace.
The export can be passed using the \fBEXPORT\fP argument. If no export is
used (e.g. for a CMake script library), pass \fBNO_EXPORT\fP\&.
.sp
If the \fBINCLUDE_FILE\fP argument is passed, the content of the specified file
(which might contain \fB@variables@\fP) is appended to the generated
\fB<Name>Config.cmake\fP file.
If the \fBINCLUDE_CONTENT\fP argument is passed, the specified content
(which might contain \fB@variables@\fP) is appended to the generated
\fB<Name>Config.cmake\fP file.
When a \fBCONFIG_TEMPLATE\fP is passed, or a \fB<Name>ConfigVersion.cmake.in\fP or
a \fB<name>\-config\-version.cmake.in file is available, these 2 arguments are
used to replace the \(ga\(ga@INCLUDED_CONTENT@\fP 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.
.sp
Note that content specified with \fBINCLUDE_FILE\fP or \fBINCLUDE_CONTENT\fP
cannot reference any of the \fBPATH_VARS\fP because this content is not
expanded by \fBconfigure_package_config_file()\fP\&.
.sp
If the \fBCOMPONENT\fP argument is passed, it is forwarded to the
\fI\%install()\fP commands, otherwise \fB<Name>\fP is used.
.SS AddUninstallTarget
.sp
Add the “uninstall” target for your project:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(AddUninstallTarget)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
will create a file \fBcmake_uninstall.cmake\fP in the build directory and add a
custom target \fBuninstall\fP (or \fBUNINSTALL\fP on Visual Studio and Xcode) that
will remove the files installed by your package (using
\fBinstall_manifest.txt\fP).
See also
\fI\%https://gitlab.kitware.com/cmake/community/wikis/FAQ#can\-i\-do\-make\-uninstall\-with\-cmake\fP
.sp
The \fI\%AddUninstallTarget\fP module must be included in your main
\fBCMakeLists.txt\fP\&. If included in a subdirectory it does nothing.
This allows you to use it safely in your main \fBCMakeLists.txt\fP and include
your project using \fBadd_subdirectory\fP (for example when using it with
\fBFetchContent\fP).
.sp
If the \fBuninstall\fP target already exists, the module does nothing.
.SS AddInstallRPATHSupport
.sp
Add support to RPATH during installation to the project and the targets
.INDENT 0.0
.TP
.B add_install_rpath_support
Add support to RPATH during installation to the project:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. code\-block:: cmake
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B add_install_rpath_support([BIN_DIRS dir [dir]]
[LIB_DIRS dir [dir]]
[INSTALL_NAME_DIR [dir]]
[DEPENDS condition [condition]]
[USE_LINK_PATH])
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Normally (depending on the platform) when you install a shared
library you can either specify its absolute path as the install name,
or leave just the library name itself. In the former case the library
will be correctly linked during run time by all executables and other
shared libraries, but it must not change its install location. This
is often the case for libraries installed in the system default
library directory (e.g. \fB/usr/lib\fP).
In the latter case, instead, the library can be moved anywhere in the
file system but at run time the dynamic linker must be able to find
it. This is often accomplished by setting environmental variables
(i.e. \fBLD_LIBRARY_PATH\fP on Linux).
This procedure is usually not desirable for two main reasons:
.INDENT 7.0
.IP \(bu 2
by setting the variable you are changing the default behaviour
of the dynamic linker thus potentially breaking executables (not as
destructive as \fBLD_PRELOAD\fP)
.IP \(bu 2
the variable will be used only by applications spawned by the shell
and not by other processes.
.UNINDENT
.sp
RPATH aims in solving the issues introduced by the second
installation method. Using run\-path dependent libraries you can
create a directory structure containing executables and dependent
libraries that users can relocate without breaking it.
A run\-path dependent library is a dependent library whose complete
install name is not known when the library is created.
Instead, the library specifies that the dynamic loader must resolve
the library’s install name when it loads the executable that depends
on the library. The executable or the other shared library will
hardcode in the binary itself the additional search directories
to be passed to the dynamic linker. This works great in conjunction
with relative paths.
This command will enable support to RPATH to your project.
It will enable the following things:
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
If the project builds shared libraries it will generate a run\-path
enabled shared library, i.e. its install name will be resolved
only at run time.
.IP \(bu 2
In all cases (building executables and/or shared libraries)
dependent shared libraries with RPATH support will have their name
resolved only at run time, by embedding the search path directly
into the built binary.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The command has the following parameters:
.INDENT 7.0
.TP
.B Options:
.INDENT 7.0
.IP \(bu 2
\fBUSE_LINK_PATH\fP: if passed the command will automatically adds to
the RPATH the path to all the dependent libraries.
.UNINDENT
.TP
.B Arguments:
.INDENT 7.0
.IP \(bu 2
\fBBIN_DIRS\fP list of directories when the targets (executable and
plugins) will be installed.
.IP \(bu 2
\fBLIB_DIRS\fP list of directories to be added to the RPATH. These
directories will be added “relative” w.r.t. the \fBBIN_DIRS\fP and
\fBLIB_DIRS\fP\&.
.IP \(bu 2
\fBINSTALL_NAME_DIR\fP directory where the libraries will be installed.
This variable will be used only if \fBCMAKE_SKIP_RPATH\fP or
\fBCMAKE_SKIP_INSTALL_RPATH\fP is set to \fBTRUE\fP as it will set the
\fBINSTALL_NAME_DIR\fP on all targets
.IP \(bu 2
\fBDEPENDS\fP list of conditions that should be \fBTRUE\fP to enable
RPATH, for example \fBFOO; NOT BAR\fP\&.
.UNINDENT
.UNINDENT
.sp
Note: see \fI\%https://gitlab.kitware.com/cmake/cmake/issues/16589\fP for further
details.
.UNINDENT
.INDENT 0.0
.TP
.B target_append_install_rpath
Add extra paths to RPATH for a specific target:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
\&.. code\-block:: cmake
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B target_append_install_rpath(<target>
<INSTALL_DESTINATION destination>
[LIB_DIRS dir [dir]]
[DEPENDS condition [condition]])
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Arguments:
.INDENT 7.0
.IP \(bu 2
\fBINSTALL_DESTINATION\fP path where the target will be installed.
.IP \(bu 2
\fBLIB_DIRS\fP list of directories to be added to the RPATH. These
directories will be added “relative” w.r.t. the \fBINSTALL_DESTINATION\fP\&.
.IP \(bu 2
\fBDEPENDS\fP list of conditions that should be \fBTRUE\fP to enable
RPATH, for example \fBFOO; NOT BAR\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SH SUPERBUILD HELPER MODULES
.SS FindOrBuildPackage
.sp
Searches for a package and builds it if it cannot be found.
.INDENT 0.0
.TP
.B find_or_build_package
.UNINDENT
.sp
Searches for a package and builds it if it cannot be found:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_or_build_package(<PackageName> <find_package_args>)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This module tries to locate a package using \fI\%find_package()\fP\&.
If the package cannot be found it tries to build it, by including
\fBBuild<package>\fP\&. This file should contain the instructions to
download and build the package (for example using
\fBExternalProject\fP)
.sp
The arguments passed to the function, are passed to the
\fI\%find_package()\fP command.
.sp
FIXME Figure out how to handle the REQUIRED and QUIET arguments
.sp
If the package was found, the \fBUSE_SYSTEM_<PackageName>\fP 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 \fBYCM_DISABLE_SYSTEM_PACKAGES\fP cache variable can be enabled.
.sp
This function sets these variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
HAVE_SYSTEM_<PackageName> # The package was found on the system
HAVE_<PackageName> # The package is available
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The user should use the latest, to check if a package is available,
instead of checking using \fB<PackageName>_FOUND\fP\&. For example
.sp
FIXME Check uppercase (${_PKG}) and lowercase (${_pkg}) variables
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
find_or_build_package(Foo)
if(HAVE_Foo)
  ...
endif()
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B CMAKE_DISABLE_BUILD_PACKAGE_<PackageName>
.UNINDENT
.sp
Using this variable, building a package is explicitly forbidden.
therefore if the package cannot be found on the system, the
\fBHAVE_<PackageName>\fP will be set to false.
.SS YCMEPHelper
.sp
A helper for \fBExternalProject\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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()
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B NON_INTERACTIVE_BUILD
.UNINDENT
.INDENT 0.0
.TP
.B YCM_BOOTSTRAP_BASE_ADDRESS
.UNINDENT
.INDENT 0.0
.TP
.B YCM_SKIP_HASH_CHECK
.UNINDENT
.INDENT 0.0
.TP
.B YCM_BOOTSTRAP_VERBOSE
.UNINDENT
.INDENT 0.0
.TP
.B YCM_EP_INSTALL_DIR
.UNINDENT
.INDENT 0.0
.TP
.B YCM_EP_ADDITIONAL_CMAKE_ARGS
.UNINDENT
.INDENT 0.0
.TP
.B YCM_<COMPONENT>_COLOR
.UNINDENT
.INDENT 0.0
.TP
.B YCM_<COMPONENT>_BGCOLOR
.UNINDENT
.INDENT 0.0
.TP
.B YCM_<COMPONENT>_NODECOLOR
.UNINDENT
.SS StyleBITBUCKET
.SS StyleGITHUB
.SS StyleGITLAB_ROBOTOLOGY
.SS StyleGNOME
.SS StyleKDE
.SS StyleLOCAL
.SS StyleNONE
.SS StyleSOURCEFORGE
.SH FIND PACKAGE MODULES
.SS Findassimp
.sp
Find the Open Asset Importer Library (assimp)
.SS Input variables
.sp
The following variables may be set to influence this module’s behavior:
.INDENT 0.0
.TP
.B \fBASSIMP_VERBOSE\fP
to output a detailed log of this module.
.UNINDENT
.SS Imported Targets
.sp
This module defines the \fI\%IMPORTED\fP target \fBassimp::assimp\fP for the
library assimp.
.SS Result Variables
.sp
This module defines the following variables:
.INDENT 0.0
.TP
.B \fBassimp_FOUND\fP
true if assimp has been found and can be used
.TP
.B \fBASSIMP_ROOT_DIR\fP
the root directory where the installation can be found
.TP
.B \fBASSIMP_INCLUDE_DIRS\fP
include directories for assimp
.TP
.B \fBASSIMP_LIBRARIES\fP
libraries to link against assimp
.TP
.B \fBASSIMP_LIBRARY_DIRS\fP
link directories
.TP
.B \fBASSIMP_VERSION\fP
ASSIMP version
.TP
.B \fBASSIMP_VERSION_MAJOR\fP
ASSIMP major version
.TP
.B \fBASSIMP_VERSION_MINOR\fP
ASSIMP minor version
.TP
.B \fBASSIMP_VERSION_REVISION\fP
ASSIMP revision version
.UNINDENT
.SS FindACE
.sp
Try to find the ACE library
.sp
Targets set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ACE::ACE (links the ACE library)
ACE::ACE_INLINE (INTERFACE library for ACE inlines only)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Variables set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Options variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindAtlas
.sp
Find the Atlas (and Lapack) libraries
.SS FindCFW2CANAPI
.sp
Created:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\(aqt try to use esdcan API
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindDRAGONFLYAPI
.sp
Created:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\(aqt try to use dragonfly API
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindESDCANAPI
.sp
Created:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\(aqt try to use esdcan API
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindFreenect
.sp
Try to find the Freenect library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindFTDI
.sp
Try to find ftdi.
Once done this will define:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
FTDI_FOUND \- system has ftdi
FTDI_INCLUDE_DIR \- ~ the ftdi include directory
FTDI_LIBRARY \- Link these to use ftdi
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindFuse
.sp
Try to find the Fuse library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindGLFW3
.sp
Find the GLFW3 framework.
.SS IMPORTED Targets
.sp
This module defines the \fI\%IMPORTED\fP target \fBGLFW3::GLFW3\fP,
if GLFW3 has been found.
.SS Result Variables
.sp
This module defines the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Environment Variables
.sp
If the library is not found on system paths, the \fBGLFW3_ROOT\fP
environment variable can be used to locate the lbrary.
.SS FindGLM
.sp
Find the OpenGL Mathematics (glm)
.SS Input variables
.sp
The following variables may be set to influence this module’s behavior:
.INDENT 0.0
.TP
.B \fBGLM_VERBOSE\fP
to output a detailed log of this module.
.UNINDENT
.SS Imported Targets
.sp
This module defines the \fI\%IMPORTED\fP target \fBglm\fP for the
library glm.
.SS Result Variables
.sp
This module defines the following variables:
.INDENT 0.0
.TP
.B \fBGLM_FOUND\fP
true if assimp has been found and can be used
.TP
.B \fBGLM_INCLUDE_DIRS\fP
include directories for assimp
.TP
.B \fBGLM_VERSION\fP
GLM version
.TP
.B \fBGLM_VERSION_MAJOR\fP
GLM major version
.TP
.B \fBGLM_VERSION_MINOR\fP
GLM minor version
.TP
.B \fBGLM_VERSION_PATCH\fP
GLM patch version
.UNINDENT
.SS FindGLUT
.sp
Wrap kitware’s original \fBFindGLUT\fP script to work on windows with
binary distribution. Standardize variables.
.sp
In windows require you set \fBGLUT_DIR\fP
.sp
Set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
GLUT_FOUND
GLUT_LIBRARIES
GLUT_INCLUDE_DIRS
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Check if this module is still needed with recent CMake releases.
.UNINDENT
.UNINDENT
.SS FindGooCanvas
.sp
Try to find the GooCanvas library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the library is found, the imported target \fBGooCanvas::goocanvas\fP is
created.
.SS FindGooCanvasMM
.sp
Try to find the GooCanvasMM library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the library is found, the imported target \fBGooCanvasMM::goocanvasmm\fP is
created.
.SS FindGSL
.sp
Try to find GSL library
Once run this will define:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
GSL_FOUND
GSL_INCLUDE_DIR
GSL_INCLUDE_DIRS
GSL_LIBRARIES
GSL_LINK_DIRECTORIES
GSLCBLAS_LIBRARY
GSL_LIBRARY
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindGtkDatabox
.sp
Try to find the GtkDatabox library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the library is found, the imported target \fBGtkDatabox::gtkdatabox\fP is
created.
.SS FindGtkDataboxMM
.sp
Try to find the GtkDataboxMM library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the library is found, the imported target \fBGtkDataboxMM::gtkdataboxmm\fP is
created.
.SS FindI2C
.sp
Find the I2C device library.
.sp
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
I2C_INCLUDE_DIRS    \- I2C include directory
I2C_LIBRARIES       \- I2C libraries
I2C_FOUND           \- if false, you cannot build anything that requires I2C
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindIPOPT
.sp
Try to locate the IPOPT library
.sp
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.
.sp
On Windows systems,  just try to find the library using the IPOPT_DIR
environment variable.
.sp
Create the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\(aqs options
IPOPT_LINK_FLAGS   \- Flags to be added to linker\(aqs options
IPOPT_FOUND        \- If false, don\(aqt try to use IPOPT
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindIPP
.sp
Try to find the IPP library.
.SS FindLibdc1394
.sp
Try to find the libdc1394 library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindLibedit
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Environment variables used to locate the Editline library:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
READLINE_DIR \- Libedit root directory
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Cached variables used to locate the NetBSD Editline library:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Libedit_INCLUDE_DIR \- the Libedit include directory
Libedit_LIBRARY_RELEASE \- NetBSD Editline library (release)
Libedit_LIBRARY_DEBUG \- NetBSD Editline library  (debug)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindLibOVR
.sp
Find the LibOVR library in Oculus Rift SDK.
.SS IMPORTED Targets
.sp
This module defines the following \fI\%IMPORTED\fP targets if
LibOVR has been found:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
LibOVR::OVRKernel
LibOVR::OVR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Result Variables
.sp
This module defines the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindLibusb1
.sp
Try to find the libusb\-1 library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindLibv4l2
.sp
Try to find the libv4l2 library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindLibv4lconvert
.sp
Try to find the libv4lconvert library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindNVIDIACg
.sp
Try to find NVIDIACg libraries
.SS FindODE
.sp
Options:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ODE_DOUBLE_PRECISION  \-use double precision ode libraries
ODE_STATIC            \-link against static libraries
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
On exit create the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindOpenCV
.sp
Find OpenCV \- variables set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
OpenCV_FOUND
OpenCV_LIBRARIES
OpenCV_INCLUDE_DIRS
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This script is a combination from multiple sources that use
different variable names; the names are reconciled at the end
of the script.
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Check if this module is still needed with recent CMake releases.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Check if the license is correct
.UNINDENT
.UNINDENT
.SS FindOpenGL
.sp
Wrap kitware’s original FindOpenGL. Standardize variables.
.sp
In windows require you set \fBOpenGL_DIR\fP
.sp
Set:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
OpenGL_FOUND
OpenGL_LIBRARIES
OpenGL_INCLUDE_DIRS
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Check if this module is still needed with recent CMake releases.
.UNINDENT
.UNINDENT
.SS FindOpenNI
.sp
Try to find the OpenNI library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindPLXCANAPI
.sp
Created:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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\(aqt try to use esdcan API
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindPortAudio
.sp
Try to find the PortAudio library.
.SS FindqpOASES
.sp
Try to find the qpOASES library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
qpOASES_FOUND         \- System has qpOASES
qpOASES_INCLUDE_DIRS  \- qpOASES include directory
qpOASES_LIBRARIES     \- qpOASES libraries
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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 \fIqpOASES_SOURCE_DIR\fP and
\fIqpOASES_BINARY_DIR\fP will be used to locate the includes and libraries.
.SS FindReadline
.sp
Try to find GNU Readline, a library for easy editing of command lines.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Environment variables used to locate the GNU Readline library:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
READLINE_DIR \- Readline root directory
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Cached variables used to locate the GNU Readline library:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Readline_INCLUDE_DIR \- the Readline include directory
Readline_LIBRARY_RELEASE \- GNU Readline library (release)
Readline_LIBRARY_DEBUG \- GNU Readline library (debug)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindSQLite
.sp
Try to find the SQLite library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindStage
.sp
Try to find Stage, a library for easy editing of command lines.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Environment variables used to locate the Stage library:
Stage_DIR \- Stage root directory
.sp
Cached variables used to locate the Stage library:
Stage_INCLUDE_DIR \- the Stage include directory
Stage_LIBRARY_RELEASE \- Stage library (release)
Stage_LIBRARY_DEBUG \- Stage library (debug)
.SS FindTinyXML
.sp
Try to find the TinyXML library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS FindYamlCpp
.sp
Try to find the YamlCpp library.
Once done this will define the following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SH BUILD PACKAGE MODULES
.SS BuildECM
.sp
ECM \- extra\-cmake\-modules (from KDE project)
.SS BuildEigen3
.sp
Eigen3
.SS BuildGazeboYARPPlugins
.sp
GazeboYARPPlugins
.SS BuildGooCanvas
.sp
GooCanvas
.SS BuildGooCanvasMM
.sp
GooCanvasMM
.SS BuildGtkDatabox
.sp
GtkDatabox
.SS BuildGtkDataboxMM
.sp
GtkDataboxMM
.SS BuildICUB
.sp
ICUB
.SS BuildECM
.sp
qpOASES
.SS BuildTinyXML
.sp
TinyXML
.SS BuildYARP
.sp
YARP
.SH CMAKE PROPOSED MODULES
.sp
These modules are patched versions of the ones included in CMake.
.SS ExternalProject
.SS External Project Definition
.INDENT 0.0
.TP
.B ExternalProject_Add
The \fBExternalProject_Add()\fP function creates a custom target to drive
download, update/patch, configure, build, install and test steps of an
external project:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Add(<name> [<option>...])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.
.INDENT 7.0
.TP
\fBDirectory Options:\fP
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
\fI\%ExternalProject_Get_Property()\fP command to retrieve their values,
thereby allowing the main project to refer to build artifacts of the
external project.
.INDENT 7.0
.TP
.B \fBPREFIX <dir>\fP
Root directory for the external project. Unless otherwise noted below,
all other directories associated with the external project will be
created under here.
.TP
.B \fBTMP_DIR <dir>\fP
Directory in which to store temporary files.
.TP
.B \fBSTAMP_DIR <dir>\fP
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 \fILogging Options\fP below).
.TP
.B \fBLOG_DIR <dir>\fP
Directory in which to store the logs of each step.
.TP
.B \fBDOWNLOAD_DIR <dir>\fP
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 \fBSOURCE_DIR\fP directly instead.
.TP
.B \fBSOURCE_DIR <dir>\fP
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.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.TP
.B \fBBINARY_DIR <dir>\fP
Specify the build directory location. This option is ignored if
\fBBUILD_IN_SOURCE\fP is enabled.
.TP
.B \fBINSTALL_DIR <dir>\fP
Installation prefix to be placed in the \fB<INSTALL_DIR>\fP 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 \fB<INSTALL_DIR>\fP\&.
.UNINDENT
.sp
If any of the above \fB\&..._DIR\fP options are not specified, their defaults
are computed as follows. If the \fBPREFIX\fP option is given or the
\fBEP_PREFIX\fP directory property is set, then an external project is built
and installed under the specified prefix:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
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>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Otherwise, if the \fBEP_BASE\fP directory property is set then components
of an external project are stored under the specified base:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
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>
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If no \fBPREFIX\fP, \fBEP_PREFIX\fP, or \fBEP_BASE\fP is specified, then the
default is to set \fBPREFIX\fP to \fB<name>\-prefix\fP\&. Relative paths are
interpreted with respect to \fI\%CMAKE_CURRENT_BINARY_DIR\fP at the
point where \fBExternalProject_Add()\fP is called.
.TP
\fBDownload Step Options:\fP
A download method can be omitted if the \fBSOURCE_DIR\fP 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 \fBDOWNLOAD_COMMAND\fP provided.
.INDENT 7.0
.TP
.B \fBDOWNLOAD_COMMAND <cmd>...\fP
Overrides the command used for the download step
(\fI\%generator expressions\fP are
supported). If this option is specified, all other download options will
be ignored. Providing an empty string for \fB<cmd>\fP effectively disables
the download step.
.TP
.B \fIURL Download\fP
.INDENT 7.0
.TP
.B \fBURL <url1> [<url2>...]\fP
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
\fI\%file(DOWNLOAD)\fP 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
\fBDOWNLOAD_NO_EXTRACT\fP 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.
.TP
.B \fBURL_HASH <algo>=<hashValue>\fP
Hash of the archive file to be downloaded. The argument should be of
the form \fB<algo>=<hashValue>\fP where \fBalgo\fP can be any of the hashing
algorithms supported by the \fI\%file()\fP 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.
.TP
.B \fBURL_MD5 <md5>\fP
Equivalent to \fBURL_HASH MD5=<md5>\fP\&.
.TP
.B \fBDOWNLOAD_NAME <fname>\fP
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 \fBExternalProject\fP module.
.TP
.B \fBDOWNLOAD_NO_EXTRACT <bool>\fP
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 \fB<DOWNLOADED_FILE>\fP in subsequent
steps or as the property \fBDOWNLOADED_FILE\fP with the
\fI\%ExternalProject_Get_Property()\fP command.
.TP
.B \fBDOWNLOAD_NO_PROGRESS <bool>\fP
Can be used to disable logging the download progress. If this option is
not given, download progress messages will be logged.
.TP
.B \fBTIMEOUT <seconds>\fP
Maximum time allowed for file download operations.
.TP
.B \fBHTTP_USERNAME <username>\fP
Username for the download operation if authentication is required.
.TP
.B \fBHTTP_PASSWORD <password>\fP
Password for the download operation if authentication is required.
.TP
.B \fBHTTP_HEADER <header1> [<header2>...]\fP
Provides an arbitrary list of HTTP headers for the download operation.
This can be useful for accessing content in systems like AWS, etc.
.TP
.B \fBTLS_VERIFY <bool>\fP
Specifies whether certificate verification should be performed for
https URLs. If this option is not provided, the default behavior is
determined by the \fBCMAKE_TLS_VERIFY\fP variable (see
\fI\%file(DOWNLOAD)\fP). If that is also not set, certificate
verification will not be performed. In situations where \fBURL_HASH\fP
cannot be provided, this option can be an alternative verification
measure.
.TP
.B \fBTLS_CAINFO <file>\fP
Specify a custom certificate authority file to use if \fBTLS_VERIFY\fP
is enabled. If this option is not specified, the value of the
\fBCMAKE_TLS_CAINFO\fP variable will be used instead (see
\fI\%file(DOWNLOAD)\fP)
.TP
.B \fBNETRC <level>\fP
Specify whether the .netrc file is to be used for operation. If this
option is not specified, the value of the \fBCMAKE_NETRC\fP variable
will be used instead (see \fI\%file(DOWNLOAD)\fP)
Valid levels are:
.INDENT 7.0
.TP
.B \fBIGNORED\fP
The .netrc file is ignored.
This is the default.
.TP
.B \fBOPTIONAL\fP
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.
.TP
.B \fBREQUIRED\fP
The .netrc file is required, and information in the URL is ignored.
.UNINDENT
.TP
.B \fBNETRC_FILE <file>\fP
Specify an alternative .netrc file to the one in your home directory
if the \fBNETRC\fP level is \fBOPTIONAL\fP or \fBREQUIRED\fP\&. If this option
is not specified, the value of the \fBCMAKE_NETRC_FILE\fP variable will
be used instead (see \fI\%file(DOWNLOAD)\fP)
.UNINDENT
.TP
.B \fIGit\fP
NOTE: A git version of 1.6.5 or later is required if this download method
is used.
.INDENT 7.0
.TP
.B \fBGIT_REPOSITORY <url>\fP
URL of the git repository. Any URL understood by the \fBgit\fP command
may be used.
.TP
.B \fBGIT_TAG <tag>\fP
Git branch name, tag or commit hash. Note that branch names and tags
should generally be specified as remote names (i.e. \fBorigin/myBranch\fP
rather than simply \fBmyBranch\fP). 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:
.INDENT 7.0
.IP \(bu 2
If the local clone already has the commit corresponding to the hash,
no \fBgit fetch\fP 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.
.IP \(bu 2
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.
.UNINDENT
.sp
If \fBGIT_SHALLOW\fP is enabled then \fBGIT_TAG\fP works only with
branch names and tags.  A commit hash is not allowed.
.TP
.B \fBGIT_REMOTE_NAME <name>\fP
The optional name of the remote. If this option is not specified, it
defaults to \fBorigin\fP\&.
.TP
.B \fBGIT_SUBMODULES <module>...\fP
Specific git submodules that should also be updated. If this option is
not provided, all git submodules will be updated.
.TP
.B \fBGIT_SHALLOW <bool>\fP
When this option is enabled, the \fBgit clone\fP operation will be given
the \fB\-\-depth 1\fP option. This performs a shallow clone, which avoids
downloading the whole history and instead retrieves just the commit
denoted by the \fBGIT_TAG\fP option.
.TP
.B \fBGIT_PROGRESS <bool>\fP
When enabled, this option instructs the \fBgit clone\fP operation to
report its progress by passing it the \fB\-\-progress\fP 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.
.TP
.B \fBGIT_CONFIG <option1> [<option2>...]\fP
Specify a list of config options to pass to \fBgit clone\fP\&. Each option
listed will be transformed into its own \fB\-\-config <option>\fP on the
\fBgit clone\fP command line, with each option required to be in the
form \fBkey=value\fP\&.
.UNINDENT
.TP
.B \fISubversion\fP
.INDENT 7.0
.TP
.B \fBSVN_REPOSITORY <url>\fP
URL of the Subversion repository.
.TP
.B \fBSVN_REVISION \-r<rev>\fP
Revision to checkout from the Subversion repository.
.TP
.B \fBSVN_USERNAME <username>\fP
Username for the Subversion checkout and update.
.TP
.B \fBSVN_PASSWORD <password>\fP
Password for the Subversion checkout and update.
.TP
.B \fBSVN_TRUST_CERT <bool>\fP
Specifies whether to trust the Subversion server site certificate. If
enabled, the \fB\-\-trust\-server\-cert\fP option is passed to the \fBsvn\fP
checkout and update commands.
.UNINDENT
.TP
.B \fIMercurial\fP
.INDENT 7.0
.TP
.B \fBHG_REPOSITORY <url>\fP
URL of the mercurial repository.
.TP
.B \fBHG_TAG <tag>\fP
Mercurial branch name, tag or commit id.
.UNINDENT
.TP
.B \fICVS\fP
.INDENT 7.0
.TP
.B \fBCVS_REPOSITORY <cvsroot>\fP
CVSROOT of the CVS repository.
.TP
.B \fBCVS_MODULE <mod>\fP
Module to checkout from the CVS repository.
.TP
.B \fBCVS_TAG <tag>\fP
Tag to checkout from the CVS repository.
.UNINDENT
.UNINDENT
.TP
\fBUpdate/Patch Step Options:\fP
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 \fBGIT_TAG\fP does not refer to a specific commit).
.INDENT 7.0
.TP
.B \fBUPDATE_COMMAND <cmd>...\fP
Overrides the download method’s update step with a custom command.
The command may use
\fI\%generator expressions\fP\&.
.TP
.B \fBUPDATE_DISCONNECTED <bool>\fP
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 \fI\%ExternalProject_Add_StepTargets()\fP)
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).
.sp
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
\fBEP_UPDATE_DISCONNECTED\fP directory property. If that is also not
defined, updates are performed as normal. The \fBEP_UPDATE_DISCONNECTED\fP
directory property is intended as a convenience for controlling the
\fBUPDATE_DISCONNECTED\fP 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).
.TP
.B \fBPATCH_COMMAND <cmd>...\fP
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 \fBGIT_TAG\fP will not
discard changes from a previous patch, but the patch command will be
called again after updating to the new tag.
.UNINDENT
.TP
\fBConfigure Step Options:\fP
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.
.INDENT 7.0
.TP
.B \fBCONFIGURE_COMMAND <cmd>...\fP
The default configure command runs CMake with options based on the main
project. For non\-CMake external projects, the \fBCONFIGURE_COMMAND\fP
option must be used to override this behavior
(\fI\%generator expressions\fP are
supported). For projects that require no configure step, specify this
option with an empty string as the command to execute.
.TP
.B \fBCMAKE_COMMAND /.../cmake\fP
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 \fBCONFIGURE_COMMAND\fP\&.
.TP
.B \fBCMAKE_GENERATOR <gen>\fP
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
\fBCONFIGURE_COMMAND\fP option.
.TP
.B \fBCMAKE_GENERATOR_PLATFORM <platform>\fP
Pass a generator\-specific platform name to the CMake command (see
\fBCMAKE_GENERATOR_PLATFORM\fP). It is an error to provide this
option without the \fBCMAKE_GENERATOR\fP option.
.TP
.B \fBCMAKE_GENERATOR_TOOLSET <toolset>\fP
Pass a generator\-specific toolset name to the CMake command (see
\fI\%CMAKE_GENERATOR_TOOLSET\fP). It is an error to provide this
option without the \fBCMAKE_GENERATOR\fP option.
.TP
.B \fBCMAKE_GENERATOR_INSTANCE <instance>\fP
Pass a generator\-specific instance selection to the CMake command (see
\fBCMAKE_GENERATOR_INSTANCE\fP). It is an error to provide this
option without the \fBCMAKE_GENERATOR\fP option.
.TP
.B \fBCMAKE_ARGS <arg>...\fP
The specified arguments are passed to the \fBcmake\fP command line. They
can be any argument the \fBcmake\fP command understands, not just cache
values defined by \fB\-D...\fP arguments (see also
\fI\%CMake Options\fP). In addition, arguments may use
\fI\%generator expressions\fP\&.
.TP
.B \fBCMAKE_CACHE_ARGS <arg>...\fP
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 \fB\-Dvar:STRING=value\fP, which are then transformed into
CMake \fI\%set()\fP commands with the \fBFORCE\fP option used. These
\fBset()\fP commands are written to a pre\-load script which is then applied
using the \fI\%cmake \-C\fP command line option. Arguments
may use \fI\%generator expressions\fP\&.
.TP
.B \fBCMAKE_CACHE_DEFAULT_ARGS <arg>...\fP
This is the same as the \fBCMAKE_CACHE_ARGS\fP option except the \fBset()\fP
commands do not include the \fBFORCE\fP 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.
.TP
.B \fBSOURCE_SUBDIR <dir>\fP
When no \fBCONFIGURE_COMMAND\fP option is specified, the configure step
assumes the external project has a \fBCMakeLists.txt\fP file at the top of
its source tree (i.e. in \fBSOURCE_DIR\fP). The \fBSOURCE_SUBDIR\fP 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
\fBSOURCE_DIR\fP\&.  When \fBBUILD_IN_SOURCE 1\fP is specified, the
\fBBUILD_COMMAND\fP is used to point to an alternative directory within the
source tree.
.UNINDENT
.TP
\fBBuild Step Options:\fP
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 \fBmake\fP with no arguments as the
default build step. This can be overridden with custom build commands if
required.
.INDENT 7.0
.TP
.B \fBBUILD_COMMAND <cmd>...\fP
Overrides the default build command
(\fI\%generator expressions\fP 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 \fBmake\fP for Makefile generators or
\fBcmake \-\-build\fP 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.
.TP
.B \fBBUILD_IN_SOURCE <bool>\fP
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 \fBBINARY_DIR\fP
option should not be specified if building in\-source.
.TP
.B \fBBUILD_ALWAYS <bool>\fP
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. \fBSOURCE_DIR\fP is used without a download method and
developers might modify the sources in \fBSOURCE_DIR\fP).
.TP
.B \fBBUILD_BYPRODUCTS <file>...\fP
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 \fBBYPRODUCTS\fP to the
build step’s own underlying call to \fI\%add_custom_command()\fP\&.
.UNINDENT
.TP
\fBInstall Step Options:\fP
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 \fBmake install\fP as the default build
step. This can be overridden with custom install commands if required.
.INDENT 7.0
.TP
.B \fBINSTALL_COMMAND <cmd>...\fP
The external project’s own install step is invoked as part of the main
project’s \fIbuild\fP\&. It is done after the external project’s build step
and may be before or after the external project’s test step (see the
\fBTEST_BEFORE_INSTALL\fP 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
\fI\%install()\fP commands. The default install step builds the
\fBinstall\fP target of the external project, but this can be overridden
with a custom command using this option
(\fI\%generator expressions\fP are
supported). Passing an empty string as the \fB<cmd>\fP makes the install
step do nothing.
.UNINDENT
.TP
\fBTest Step Options:\fP
The test step is only defined if at least one of the following \fBTEST_...\fP
options are provided.
.INDENT 7.0
.TP
.B \fBTEST_COMMAND <cmd>...\fP
Overrides the default test command
(\fI\%generator expressions\fP are
supported). If this option is not given, the default behavior of the test
step is to build the external project’s own \fBtest\fP target. This option
can be specified with \fB<cmd>\fP 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 \fBTEST_...\fP options if providing an empty string as the test
command, but prefer to omit all \fBTEST_...\fP options altogether if the
test step target is not needed.
.TP
.B \fBTEST_BEFORE_INSTALL <bool>\fP
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.
.TP
.B \fBTEST_AFTER_INSTALL <bool>\fP
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 \fBTEST_BEFORE_INSTALL\fP and
\fBTEST_AFTER_INSTALL\fP are enabled, the latter is silently ignored.
.TP
.B \fBTEST_EXCLUDE_FROM_MAIN <bool>\fP
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.
.UNINDENT
.TP
\fBOutput Logging Options:\fP
Each of the following \fBLOG_...\fP 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 \fBLOG_DIR\fP if supplied or otherwise the \fBSTAMP_DIR\fP
directory with step\-specific file names.
.INDENT 7.0
.TP
.B \fBLOG_DOWNLOAD <bool>\fP
When enabled, the output of the download step is logged to files.
.TP
.B \fBLOG_UPDATE <bool>\fP
When enabled, the output of the update step is logged to files.
.TP
.B \fBLOG_PATCH <bool>\fP
When enabled, the output of the patch step is logged to files.
.TP
.B \fBLOG_CONFIGURE <bool>\fP
When enabled, the output of the configure step is logged to files.
.TP
.B \fBLOG_BUILD <bool>\fP
When enabled, the output of the build step is logged to files.
.TP
.B \fBLOG_INSTALL <bool>\fP
When enabled, the output of the install step is logged to files.
.TP
.B \fBLOG_TEST <bool>\fP
When enabled, the output of the test step is logged to files.
.TP
.B \fBLOG_MERGED_STDOUTERR <bool>\fP
When enabled, stdout and stderr will be merged for any step whose
output is being logged to files.
.TP
.B \fBLOG_OUTPUT_ON_FAILURE <bool>\fP
This option only has an effect if at least one of the other \fBLOG_<step>\fP
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
\fBLOG_OUTPUT_ON_FAILURE\fP 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.
.UNINDENT
.TP
\fBTerminal Access Options:\fP
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 \fI\%Ninja\fP generator, these options place the steps in the
\fBconsole\fP \fI\%job pool\fP\&. Each step can be given access
to the terminal individually via the following options:
.INDENT 7.0
.TP
.B \fBUSES_TERMINAL_DOWNLOAD <bool>\fP
Give the download step access to the terminal.
.TP
.B \fBUSES_TERMINAL_UPDATE <bool>\fP
Give the update step access to the terminal.
.TP
.B \fBUSES_TERMINAL_CONFIGURE <bool>\fP
Give the configure step access to the terminal.
.TP
.B \fBUSES_TERMINAL_BUILD <bool>\fP
Give the build step access to the terminal.
.TP
.B \fBUSES_TERMINAL_INSTALL <bool>\fP
Give the install step access to the terminal.
.TP
.B \fBUSES_TERMINAL_TEST <bool>\fP
Give the test step access to the terminal.
.UNINDENT
.TP
\fBTarget Options:\fP
.INDENT 7.0
.TP
.B \fBDEPENDS <targets>...\fP
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 \fBDEPENDS\fP option is the most
convenient way to ensure all of those steps depend on the other targets.
Simply doing
\fI\%add_dependencies(<name> <targets>)\fP will
not make any of the steps dependent on \fB<targets>\fP\&.
.TP
.B \fBEXCLUDE_FROM_ALL <bool>\fP
When enabled, this option excludes the external project from the default
ALL target of the main build.
.TP
.B \fBSTEP_TARGETS <step\-target>...\fP
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 \fBEP_STEP_TARGETS\fP directory property.
See \fI\%ExternalProject_Add_Step()\fP below for further discussion of
the effects of this option.
.TP
.B \fBINDEPENDENT_STEP_TARGETS <step\-target>...\fP
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
\fBEP_INDEPENDENT_STEP_TARGETS\fP 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
\fI\%ExternalProject_Add_Step()\fP below for further discussion of the
effects of this option.
.UNINDENT
.TP
\fBMiscellaneous Options:\fP
.INDENT 7.0
.TP
.B \fBLIST_SEPARATOR <sep>\fP
For any of the various \fB\&..._COMMAND\fP options, replace \fB;\fP with
\fB<sep>\fP 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 (\fB<sep>\fP would be a single space character
string in this case).
.TP
.B \fBCOMMAND <cmd>...\fP
Any of the other \fB\&..._COMMAND\fP options can have additional commands
appended to them by following them with as many \fBCOMMAND ...\fP options
as needed
(\fI\%generator expressions\fP are
supported). For example:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
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"
)
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
It should also be noted that each build step is created via a call to
\fI\%ExternalProject_Add_Step()\fP\&. See that command’s documentation for the
automatic substitutions that are supported for some options.
.UNINDENT
.SS Obtaining Project Properties
.INDENT 0.0
.TP
.B ExternalProject_Get_Property
The \fBExternalProject_Get_Property()\fP function retrieves external project
target properties:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The function stores property values in variables of the same name. Property
names correspond to the keyword argument names of \fBExternalProject_Add()\fP\&.
For example, the source directory might be retrieved like so:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Get_property(myExtProj SOURCE_DIR)
message("Source dir of myExtProj = ${SOURCE_DIR}")
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.SS Explicit Step Management
.sp
The \fBExternalProject_Add()\fP 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
\fBExternalProject_Add_Step()\fP, \fBExternalProject_Add_StepTargets()\fP and
\fBExternalProject_Add_StepDependencies\fP functions provide the lower level
control needed to implement such step\-level capabilities.
.INDENT 0.0
.TP
.B ExternalProject_Add_Step
The \fBExternalProject_Add_Step()\fP function specifies an additional custom
step for an external project defined by an earlier call to
\fI\%ExternalProject_Add()\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Add_Step(<name> <step> [<option>...])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fB<name>\fP is the same as the name passed to the original call to
\fI\%ExternalProject_Add()\fP\&. The specified \fB<step>\fP must not be one of
the pre\-defined steps (\fBmkdir\fP, \fBdownload\fP, \fBupdate\fP, \fBskip\-update\fP,
\fBpatch\fP, \fBconfigure\fP, \fBbuild\fP, \fBinstall\fP or \fBtest\fP). The supported
options are:
.INDENT 7.0
.TP
.B \fBCOMMAND <cmd>...\fP
The command line to be executed by this custom step
(\fI\%generator expressions\fP are
supported). This option can be repeated multiple times to specify multiple
commands to be executed in order.
.TP
.B \fBCOMMENT "<text>..."\fP
Text to be printed when the custom step executes.
.TP
.B \fBDEPENDEES <step>...\fP
Other steps (custom or pre\-defined) on which this step depends.
.TP
.B \fBDEPENDERS <step>...\fP
Other steps (custom or pre\-defined) that depend on this new custom step.
.TP
.B \fBDEPENDS <file>...\fP
Files on which this custom step depends.
.TP
.B \fBBYPRODUCTS <file>...\fP
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 \fBBYPRODUCTS\fP option to the
\fI\%add_custom_command()\fP used to implement the custom step internally.
.TP
.B \fBALWAYS <bool>\fP
When enabled, this option specifies that the custom step should always be
run (i.e. that it is always considered out of date).
.TP
.B \fBEXCLUDE_FROM_MAIN <bool>\fP
When enabled, this option specifies that the external project’s main target
does not depend on the custom step.
.TP
.B \fBWORKING_DIRECTORY <dir>\fP
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 \fI\%CMAKE_CURRENT_BINARY_DIR\fP at the point where
\fBExternalProject_Add_Step()\fP was called.
.TP
.B \fBLOG <bool>\fP
If set, this causes the output from the custom step to be captured to files
in the external project’s \fBLOG_DIR\fP if supplied or \fBSTAMP_DIR\fP\&.
.TP
.B \fBUSES_TERMINAL <bool>\fP
If enabled, this gives the custom step direct access to the terminal if
possible.
.UNINDENT
.sp
The command line, comment, working directory and byproducts of every
standard and custom step are processed to replace the tokens
\fB<SOURCE_DIR>\fP, \fB<SOURCE_SUBDIR>\fP, \fB<BINARY_DIR>\fP, \fB<INSTALL_DIR>\fP
\fB<TMP_DIR>\fP, \fB<DOWNLOAD_DIR>\fP and \fB<DOWNLOADED_FILE>\fP with their
corresponding property values defined in the original call to
\fI\%ExternalProject_Add()\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B ExternalProject_Add_StepTargets
The \fBExternalProject_Add_StepTargets()\fP function generates targets for the
steps listed. The name of each created target will be of the form
\fB<name>\-<step>\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.
.sp
If the \fBNO_DEPENDS\fP option is specified, the step target will not depend on
the dependencies of the external project (i.e. on any dependencies of the
\fB<name>\fP custom target created by \fI\%ExternalProject_Add()\fP). This is
usually safe for the \fBdownload\fP, \fBupdate\fP and \fBpatch\fP steps, since they
do not typically require that the dependencies are updated and built. Using
\fBNO_DEPENDS\fP for any of the other pre\-defined steps, however, may break
parallel builds. Only use \fBNO_DEPENDS\fP 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.
.sp
Internally, \fI\%ExternalProject_Add()\fP calls
\fI\%ExternalProject_Add_Step()\fP to create each step. If any
\fBSTEP_TARGETS\fP or \fBINDEPENDENT_STEP_TARGETS\fP were specified, then
\fBExternalProject_Add_StepTargets()\fP will also be called after
\fI\%ExternalProject_Add_Step()\fP\&. \fBINDEPENDENT_STEP_TARGETS\fP have the
\fBNO_DEPENDS\fP option set, whereas \fBSTEP_TARGETS\fP do not. Other than that,
the two options result in \fBExternalProject_Add_StepTargets()\fP being called
in the same way. Even if a step is not mentioned in either of those two
options, \fBExternalProject_Add_StepTargets()\fP can still be called later to
manually define a target for the step.
.sp
The \fBSTEP_TARGETS\fP and \fBINDEPENDENT_STEP_TARGETS\fP options for
\fI\%ExternalProject_Add()\fP are generally the easiest way to ensure
targets are created for specific steps of interest. For custom steps,
\fBExternalProject_Add_StepTargets()\fP 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 \fBEP_STEP_TARGETS\fP and
\fBEP_INDEPENDENT_STEP_TARGETS\fP 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.
.UNINDENT
.INDENT 0.0
.TP
.B ExternalProject_Add_StepDependencies
The \fBExternalProject_Add_StepDependencies()\fP 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):
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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
\fI\%add_dependencies()\fP whenever adding a dependency for some of the step
targets generated by the \fBExternalProject\fP module.
.UNINDENT
.SS Examples
.sp
The following example shows how to download and build a hypothetical project
called \fIFooBar\fP from github:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include(ExternalProject)
ExternalProject_Add(foobar
  GIT_REPOSITORY    git@github.com:FooCo/FooBar.git
  GIT_TAG           origin/release/1.2.3
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For the sake of the example, also define a second hypothetical external project
called \fISecretSauce\fP, 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 \fBMakefile\fP project with no
configure step, so some of the default commands are overridden. The build is
only required to build the \fIsauce\fP target:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Suppose the build step of \fBsecretsauce\fP requires that \fBfoobar\fP must already
be built. This could be enforced like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Add_StepDependencies(secretsauce build foobar)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Another alternative would be to create a custom target for \fBfoobar\fP’s build
step and make \fBsecretsauce\fP depend on that rather than the whole \fBfoobar\fP
project. This would mean \fBfoobar\fP only needs to be built, it doesn’t need to
run its install or test steps before \fBsecretsauce\fP can be built. The
dependency can also be defined along with the \fBsecretsauce\fP project:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Instead of calling \fI\%ExternalProject_Add_StepTargets()\fP, the target could
be defined along with the \fBfoobar\fP project itself:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
ExternalProject_Add(foobar
  GIT_REPOSITORY git@github.com:FooCo/FooBar.git
  GIT_TAG        origin/release/1.2.3
  STEP_TARGETS   build
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If many external projects should have the same set of step targets, setting a
directory property may be more convenient. The \fBbuild\fP step target could be
created automatically by setting the \fBEP_STEP_TARGETS\fP directory property
before creating the external projects with \fI\%ExternalProject_Add()\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Lastly, suppose that \fBsecretsauce\fP provides a script called \fBmakedoc\fP 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 \fBsecretsauce\fP source directory. A custom step and a
custom target to trigger the script can be defined like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The custom step could then be triggered from the main build like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake \-\-build . \-\-target secretsauce\-docs
.ft P
.fi
.UNINDENT
.UNINDENT
.SS CMakeParseArguments
.sp
Parse arguments given to a macro or a function.
.sp
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.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake_parse_arguments(<prefix>
                      <options>
                      <one_value_keywords>
                      <multi_value_keywords>
                      [CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY|CMAKE_PARSE_ARGUMENTS_KEEP_EMPTY]
                      args...
                      )
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
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.
.sp
As an example here a my_install() macro, which takes similar arguments
as the real install() command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
function(MY_INSTALL)
  set(options OPTIONAL FAST)
  set(oneValueArgs DESTINATION RENAME)
  set(multiValueArgs TARGETS CONFIGURATIONS)
  cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}" )
  ...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Assume my_install() has been called like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After the cmake_parse_arguments() call the macro will have set the
following variables:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can then continue and process these variables.
.sp
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.
.sp
If the “CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY” option is set,
cmake_parse_argumentswill not consider empty arguments.
Therefore
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
my_install(DESTINATION "" TARGETS foo "" bar)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will set
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
MY_INSTALL_DESTINATION = (unset)
MY_INSTALL_MULTI = "foo;bar"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Using the “CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY” option instead, will set
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
MY_INSTALL_SINGLE = ""
MY_INSTALL_MULTI = "foo;;bar"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is also important to note that:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}" )
cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Will behave differently, because in the latter case empty arguments
are not passed to cmake_parse_arguments.
.SH DEPRECATED MODULES
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
These modules are deprecated and should not be used in new code.
.UNINDENT
.UNINDENT
.SS YCMDefaultDirs
.SH COPYRIGHT
Copyright 2013-2019 Istituto Italiano di Tecnologia (IIT)
.\" Generated by docutils manpage writer.
.