Provided by: ycm-cmake-modules_0.13.0-3_all bug

NAME

       ycm-modules - YCM Modules Reference

GENERIC MODULES

   ExtractVersion
       Extracts version numbers from a version string:

          extract_version (<name> [REVERSE_NAME])

       Tries  to  extract  the following variables (the second version is used if REVERSE_NAME is
       set as argument):

          <name>_MAJOR_VERSION or <name>_VERSION_MAJOR - <name> major version
          <name>_MINOR_VERSION or <name>_VERSION_MINOR - <name> minor version
          <name>_PATCH_VERSION or <name>_VERSION_PATCH - <name> patch version
          <name>_TWEAK_VERSION or <name>_VERSION_TWEAK - <name> tweak version
          <name>_VERSION_COUNT - number of version components, 0 to 4

   GetAllCMakeProperties
       Return a list containing the names of all known CMake Properties.

       Only properties returned by cmake --help-property-list  are  returned,  custom  properties
       will not be on the returned list.

       Properties containing <CONFIG> or <LANG> are expanded to the correct property name.

   GitInfo
       Extract information from a git repository.

       git_commit_info
              Extract information about one commit from one git repository in SOURCE DIR:

                 git_commit_info([SOURCE DIR <dir>]
                                 [PREFIX <prefix>]
                                 [REVISION <rev>]
                                 [FATAL])

              If  SOURCE_DIR  is  a  git  repository,  it  checks the given REVISION and sets the
              following variables:

              <PREFIX>_GIT_COMMIT_DESCRIBE
                     The output of git describe <ref>.

              <PREFIX>_GIT_COMMIT_DESCRIBE_CONTAINS
                     The output of git describe --contains <ref>.

              <PREFIX>_GIT_COMMIT_TAG
                     The most recent tag that is reachable from a commit.

              <PREFIX>_GIT_COMMIT_REVISION
                     The number of commits since the beginning of the git history.

              <PREFIX>_GIT_COMMIT_TAG_REVISION
                     The number of commits since the last tag.

              <PREFIX>_GIT_COMMIT_DATE_REVISION
                     The number of commits since the beginning of the day.

              <PREFIX>_GIT_COMMIT_AUTHOR_DATE
                     The commit author date.

              <PREFIX>_GIT_COMMIT_AUTHOR_TIME
                     The commit author time.

              <PREFIX>_GIT_COMMIT_AUTHOR_TZ
                     The commit author time zone.

              <PREFIX>_GIT_COMMIT_AUTHOR_NAME
                     The commit author name.

              <PREFIX>_GIT_COMMIT_AUTHOR_EMAIL
                     The commit author e-mail.

              <PREFIX>_GIT_COMMIT_COMMITTER_DATE
                     The commit committer date.

              <PREFIX>_GIT_COMMIT_COMMITTER_TIME
                     The commit author time.

              <PREFIX>_GIT_COMMIT_COMMITTER_TZ
                     The commit author time zone.

              <PREFIX>_GIT_COMMIT_COMMITTER_NAME
                     The commit committer name.

              <PREFIX>_GIT_COMMIT_COMMITTER_EMAIL
                     The commit committer email.

              <PREFIX>_GIT_COMMIT_HASH
                     The commit hash.

              <PREFIX>_GIT_COMMIT_HASH_SHORT
                     The abbreviated commit hash.

              <PREFIX>_GIT_COMMIT_SUBJECT
                     The commit log message subject line.

              <PREFIX>_GIT_COMMIT_BODY
                     The commit log message body.

              If SOURCE_DIR is not set, then the PROJECT_SOURCE_DIR cmake variable is used.

              If PREFIX is not set, then the PROJECT_NAME cmake variable is used.

              REVISION can be a commit hash, a tag, a branch, or anything that git can parse as a
              revision. If REVISION` is not set, then ``HEAD is used.

              If  FATAL  is  set,  a  fatal  error  is  emitted  when the source dir is not a git
              repository, or when git was not  found.  This  is  disabled  by  default  to  allow
              downloads  from  non-git  sources (archives, wrappers, etc.), but can be enabled if
              required.

       git_wt_info
              Extract information about current working tree from one git  repository  in  SOURCE
              DIR:

                 git_wt_info([SOURCE DIR <dir>]
                             [PREFIX <prefix>]
                             [FATAL])

              If  SOURCE_DIR  is  a  git  repository,  it  checks  current  revision and sets the
              following variables:

              <PREFIX>_GIT_WT_DESCRIBE
                     The output of git describe HEAD.

              <PREFIX>_GIT_WT_DESCRIBE_CONTAINS
                     The output of git describe --contains HEAD.

              <PREFIX>_GIT_WT_TAG
                     The most recent tag that is reachable from current commit.

              <PREFIX>_GIT_WT_REVISION
                     The number of commits since the beginning of the git history.

              <PREFIX>_GIT_WT_TAG_REVISION
                     The number of commits since the last tag.

              <PREFIX>_GIT_WT_DATE_REVISION
                     The number of commits since the beginning of the day.

              <PREFIX>_GIT_WT_AUTHOR_DATE
                     The current commit author date.

              <PREFIX>_GIT_WT_AUTHOR_TIME
                     The current commit author time.

              <PREFIX>_GIT_WT_AUTHOR_TZ
                     The current commit author time zone.

              <PREFIX>_GIT_WT_AUTHOR_NAME
                     The current commit author name.

              <PREFIX>_GIT_WT_AUTHOR_EMAIL
                     The current commit author e-mail.

              <PREFIX>_GIT_WT_COMMITTER_DATE
                     The current commit committer date.

              <PREFIX>_GIT_WT_COMMITTER_TIME
                     The current commit author time.

              <PREFIX>_GIT_WT_COMMITTER_TZ
                     The current commit author time zone.

              <PREFIX>_GIT_WT_COMMITTER_NAME
                     The current commit committer name.

              <PREFIX>_GIT_WT_COMMITTER_EMAIL
                     The current commit committer email.

              <PREFIX>_GIT_WT_HASH
                     The current commit hash.

              <PREFIX>_GIT_WT_HASH_SHORT
                     The abbreviated commit hash.

              <PREFIX>_GIT_WT_SUBJECT
                     The current commit log message subject line.

              <PREFIX>_GIT_WT_BODY
                     The current commit log message body.

              <PREFIX>_GIT_WT_DIRTY
                     Whether the current working tree is clean or not.

              If SOURCE_DIR is not set, then the PROJECT_SOURCE_DIR cmake variable is used.

              If PREFIX is not set, then the PROJECT_NAME cmake variable is used.

              If FATAL is set, a fatal error is  emitted  when  the  source  dir  is  not  a  git
              repository,  or  when  git  was  not  found.  This  is disabled by default to allow
              downloads from non-git sources (archives, wrappers, etc.), but can  be  enabled  if
              required.

   IncludeUrl
       Adds  the  include_url()  command  that useful to download and include other CMake modules
       from a given url.

       include_url

       Downloads a file from given url and includes it:

          include_url(<url>                 # Url to be downloaded
             [DESTINATION <destination>]    # Where the file will be saved
             [EXPECTED_HASH <ALGO=value>]   # Verify downloaded file's hash
             [EXPECTED_MD5 <sum>]           # Short-hand for "EXPECTED_HASH MD5=sum"
             [DOWNLOAD_ONCE]                # Download the file only once
             [DOWNLOAD_ALWAYS]              # Download the file every time
             [OPTIONAL]                     # Do not fail file cannot be included
             [RESULT_VARIABLE <variable>]   # The local path for the file included
             [RETRIES <retries>]            # Try download <retries> times (default 3)
             [QUIET]                        # Don't print anything
            #--Download arguments-----------
             [INACTIVITY_TIMEOUT <timeout>] # Timeout after <timeout> seconds of inactivity
             [TIMEOUT <timeout>]            # Timeout after <timeout> seconds
             [STATUS <status>]              # Download status variable
             [LOG <log>]                    # Download log variable
             [SHOW_PROGRESS]                # Show download progress
             [TLS_VERIFY <on|off>]          # Check certificates
             [TLS_CAINFO <file>]            # Custom Certificate Authority file
            #--Include arguments------------
             [NO_POLICY_SCOPE]              # Do not manage a new policy entry
             )

       The include_url macro downloads a file from given url and includes it.  It works  both  in
       -P script mode and when configuring a CMakeLists.txt file.

       If  DESTINATION  is  specified,  the file is saved at the given location with the original
       file name, if <destination> is a directory, or with the given file  name, if <destination>
       is a file name.

       The arguments EXPECTED_HASH, EXPECTED_MD5 are used to ensure that the file included is the
       one expected. If the <url> is a local file (i.e.  starts with file://) the hash  check  is
       performed  also  on  the  file  converted  to  the  non-native end-of-line style.  See the
       documentation of the file() command for further information about these arguments.

       If the DOWNLOAD_ONCE option is specified, the file is not downloaded if the  file  already
       exists  and  the hash is correct.  If the DOWNLOAD_ALWAYS option is specified, the file is
       downloaded at every CMake execution, and an error is raised on failure.  If none of  these
       two  option  is  specifies,  the default behaviour is to try to download the file at every
       CMake execution, but no error is raised if the download fails if a  version  of  the  file
       already  exists.  This  is  useful  when CMake should try to update the file to the latest
       version, before including it.

       If the OPTIONAL option is specified, no error will be caused if for any  reason  the  file
       cannot  be  downloaded or included.  If RESULT_VARIABLE is given, the variable will be set
       to the full filename which has been downloaded and included or NOTFOUND if it failed.  See
       the documentation of the file() command for further information about these arguments.

       If  the  RETRIES  option  is  specified, the download will be tried If the QUIET option is
       specified, the command will emit no output.

       The arguments INACTIVITY_TIMEOUT, TIMEOUT, STATUS,  LOG,  SHOW_PROGRESS,  TLS_VERIFY,  and
       TLS_CAINFO  are passed to the file(DOWNLOAD) command.  See the documentation of the file()
       command for a detailed description of these arguments.

       The arguments NO_POLICY_SCOPE is passed to the include() command.  See  the  documentation
       of the include() and cmake_policy() commands for a detailed description of this argument.

   ReplaceImportedTargets
       Adds  the  replace_imported_targets()  command  that useful to replace paths with imported
       targets in link variables (like <FOO>_LIBRARIES) and targets.

       replace_imported_targets

       Replace imported targets in a list of and targets and paths:

          replace_imported_targets(<var> [target [target [...]]])

       Each path in  var  corrisponding  to  one  of  the  targets  will  be  replaced  with  the
       corrisponding target, taking care to remove the relative optimized and debug keywords.

       For  each  existing  target in var, the following properties will be searched for imported
       locations of targets, and, if set, will be replaced in the same way:

          IMPORTED_LINK_DEPENDENT_LIBRARIES
          IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
          IMPORTED_LINK_INTERFACE_LIBRARIES
          IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
          INTERFACE_LINK_LIBRARIES
          LINK_INTERFACE_LIBRARIES
          LINK_INTERFACE_LIBRARIES_<CONFIG>
          LINK_LIBRARIES

   StandardFindModule
       Try to find a package using a cmake config file, or pkgconfig:

          standard_find_module(<name>
                               <pkgconfig name>
                               [NOT_REQUIRED]
                               [QUIET]
                               [SKIP_CMAKE_CONFIG]
                               [SKIP_PKG_CONFIG]
                               [TARGET <target>]
                               [REPLACE_TARGETS <target> [...]]
          )

       If the package is found, the following variables (where possible) are created:

          <name>_FOUND         - System has <name>
          <name>_INCLUDE_DIRS  - <name> include directory
          <name>_LIBRARIES     - <name> libraries
          <name>_DEFINITIONS   - Additional compiler flags for <name>
          <name>_VERSION       - <name> version
          <name>_MAJOR_VERSION - <name> major version
          <name>_MINOR_VERSION - <name> minor version
          <name>_PATCH_VERSION - <name> patch version
          <name>_TWEAK_VERSION - <name> tweak version
          <name>_VERSION_COUNT - Number of version components, 0 to 4

       For each library that requires to be linked (i.e. -llib) it creates:

          <name>_<LIB>_LIBRARY_RELEASE (cached, advanced)
          <name>_<LIB>_LIBRARY_DEBUG (cached, advanced, and empty by default)
          <name>_<LIB>_LIBRARY
          <name>_<LIB>_LIBRARY_FOUND

       In a FindXXX.cmake module, this macro can be used at the beginning.  The NOT_REQUIRED  can
       be  added to avoid failing if the package was not found, but pkg-config is installed.  The
       QUIET argument can be used to hide the output from find_package_handle_standard_args.   If
       <name>_FOUND is FALSE at the end, more “custom” searches can be used (for windows, etc.)

       If SKIP_CMAKE_CONFIG or SKIP_PKG_CONFIG are set, the relative step is skipped

       If  TARGET  is specified, in pkg-config mode, an imported target will be created using the
       first library returned by pkg-config as imported location.

       The REPLACE_TARGETS can be used to pass a list of imported targets that will  be  detected
       in variables and target properties, and replaced with the corresponding target.

       If        one        of        the       STANDARD_FIND_MODULE_USE_IMPORTED_TARGET       or
       STANDARD_FIND_MODULE_USE_IMPORTED_TARGET_<name> are enabled, and a  TARGET  is  specified,
       the <name>_LIBRARIES variable content is replaced with the imported target.

       If one of the variables STANDARD_FIND_MODULE_DEBUG or STANDARD_FIND_MODULE_DEBUG_<name> is
       enabled, prints more useful debug output

PACKAGING HELPER MODULES

   InstallBasicPackageFiles
       A helper module to make your package easier to be found by other projects.

       install_basic_package_files

       Create and install a basic version of cmake config files for your project:

          install_basic_package_files(<Name>
                                      COMPATIBILITY <compatibility>
                                      [VERSION <version>]
                                      [ARCH_INDEPENDENT]
                                      [NO_EXPORT | EXPORT <export>] # (default = "EXPORT <Name>")
                                      [NO_SET_AND_CHECK_MACRO]
                                      [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
                                      [VARS_PREFIX <prefix>] # (default = "<Name>")
                                      [EXPORT_DESTINATION <destination>]
                                      [INSTALL_DESTINATION <destination>]
                                      [NAMESPACE <namespace>] # (default = "<Name>::")
                                      [EXTRA_PATH_VARS_SUFFIX path1 [path2 ...]]
                                      [CONFIG_TEMPLATE <file>]
                                      [UPPERCASE_FILENAMES | LOWERCASE_FILENAMES]
                                      [DEPENDENCIES <dependency1> "<dependency2> [...]" ...]
                                      [PRIVATE_DEPENDENCIES <dependency1> "<dependency2> [...]" ...]
                                      [INCLUDE_FILE <file> | INCLUDE_CONTENT <content>]
                                      [COMPONENT <component>] # (default = "<Name>")
                                     )

       Depending on UPPERCASE_FILENAMES and LOWERCASE_FILENAMES, this function generates 3 files:

          • <Name>ConfigVersion.cmake or <name>-config-version.cmake<Name>Config.cmake or <name>-config.cmake<Name>Targets.cmake or <name>-targets.cmake

       If   neither   UPPERCASE_FILENAMES   nor    LOWERCASE_FILENAMES    is    set,    a    file
       <Name>Config.cmake.in  or <name>-config.cmake.in is searched, and the convention is chosed
       according to the file found. If no file was found, the uppercase convention is used.

       The DEPENDENCIES argument can be used to set a list of dependencies that will be  searched
       using   the   find_dependency()   command   from   the   CMakeFindDependencyMacro  module.
       Dependencies can be followed by any of the possible find_dependency() argument.   In  this
       case,  all the arguments must be specified within double quotes (e.g.  "<dependency> 1.0.0
       EXACT", or "<dependency>  CONFIG").   The  PRIVATE_DEPENDENCIES  argument  is  similar  to
       DEPENDENCIES,  but these dependencies are included only when BUILD_SHARED_LIBS is OFF.  If
       a libraries is declared STATIC, OBJECT or INTERFACE, and they  link  to  some  dependency,
       these  should  be  added  using  the DEPENDENCIES argument, since the PRIVATE_DEPENDENCIES
       argument would work only when BUILD_SHARED_LIBS is disabled.

       When using a custom template file, the @PACKAGE_DEPENDENCIES@ string is replaced with  the
       code checking for the dependencies specified by these two argument.

       If  the  ARCH_INDEPENDENT  option  is  enabled,  the  installed  package  version  will be
       considered compatible even if it was built for a different architecture than the requested
       architecture.

       Each  file  is  generated  twice, one for the build directory and one for the installation
       directory.  The INSTALL_DESTINATION argument can be passed  to  install  the  files  in  a
       location  different  from  the  default one (${CMAKE_INSTALL_DATADIR}/cmake/${Name} if the
       ARCH_INDEPENDENT option is enabled, ${CMAKE_INSTALL_LIBDIR}/cmake/${Name} otherwise).  The
       EXPORT_DESTINATION  argument  can  be  passed to generate the files in the build tree in a
       location different from the default one (CMAKE_BINARY_DIR).  If this is a  relative  path,
       it is considered relative to the CMAKE_CURRENT_BINARY_DIR directory.

       The  build  directory  is  exported to the CMake user package registry if the build option
       CMAKE_EXPORT_PACKAGE_REGISTRY is set.

       The <Name>ConfigVersion.cmake file is generated using  write_basic_package_version_file().
       The VERSION, COMPATIBILITY, and
       ``
       ARCH_INDEPENDENT``arguments are passed to this function.

       VERSION  shall  be  in  the form <major>[.<minor>[.<patch>[.<tweak>]]]].  If no VERSION is
       given, the PROJECT_VERSION variable is used.  If this hasn’t been set, it errors out.  The
       VERSION argument is also used to replace the @PACKAGE_VERSION@ string in the configuration
       file.

       COMPATIBILITY    shall    be    any     of     the     options     accepted     by     the
       write_basic_package_version_file()     command     (AnyNewerVersion,     SameMajorVersion,
       SameMinorVersion  [CMake  3.11],  or  ExactVersion).   These  options  are  explained   in
       write_basic_package_version_file()  command  documentation.   If  your  project  has  more
       elaborate  version  matching  rules,  you   will   need   to   write   your   own   custom
       ConfigVersion.cmake file instead of using this macro.

       The  <Name>Config.cmake  file  is  generated  using  configure_package_config_file().  The
       NO_SET_AND_CHECK_MACRO, NO_CHECK_REQUIRED_COMPONENTS_MACRO, and arguments  are  passed  to
       this function.

       By   default   install_basic_package_files()   also   generates   the  two  helper  macros
       set_and_check()  and  check_required_components()  into   the   <Name>Config.cmake   file.
       set_and_check() should be used instead of the normal set() command for setting directories
       and file locations.  Additionally  to  setting  the  variable  it  also  checks  that  the
       referenced file or directory actually exists and fails with a FATAL_ERROR otherwise.  This
       makes sure that the created <Name>Config.cmake file does  not  contain  wrong  references.
       When   using   the   NO_SET_AND_CHECK_MACRO,   this   macro  is  not  generated  into  the
       ``<Name>Config.cmake file.

       By      default,      install_basic_package_files()      append      a       call       to
       check_required_components(<Name>)  in  <Name>Config.cmake  file  if  the  package supports
       components. This macro checks whether all requested,  non-optional  components  have  been
       found,  and  if this is not the case, sets the <Name>_FOUND variable to FALSE, so that the
       package   is   considered   to   be   not   found.   It   does   that   by   testing   the
       <Name>_<Component>_FOUND  variables  for all requested required components. When using the
       NO_CHECK_REQUIRED_COMPONENTS_MACRO  option,  this  macro  is  not   generated   into   the
       <Name>Config.cmake file.

       Finally, the files in the build and install directory are exactly the same.

       See  the  documentation  of  CMakePackageConfigHelpers  module for further information and
       references therein.

       If the CONFIG_TEMPLATE argument is passed, the specified file  is  used  as  template  for
       generating   the   configuration   file,   otherwise   this   module  expects  to  find  a
       <Name>Config.cmake.in or <name>-config.cmake.in file either in current  source  directory.
       If the file does not exist, a very basic file is created.

       A set of variables are checked and passed to configure_package_config_file() as PATH_VARS.
       For each of the SUFFIX considered, if one of the variables:

          <VARS_PREFIX>_(BUILD|INSTALL)_<SUFFIX>
          (BUILD|INSTALL)_<VARS_PREFIX>_<SUFFIX>

       is defined, the <VARS_PREFIX>_<SUFFIX> variable will be  defined  before  configuring  the
       package.  In order to use that variable in the config file, you have to add a line:

          set_and_check(<VARS_PREFIX>_<SUFFIX> \"@PACKAGE_<VARS_PREFIX>_<SUFFIX>@\")

       if the path must exist or just:

          set(<VARS_PREFIX>_<SUFFIX> \"@PACKAGE_<VARS_PREFIX>_<SUFFIX>@\")

       if the path could be missing.

       These variable will have different values whether you are using the package from the build
       tree or from the install directory.  Also these files will contain  only  relative  paths,
       meaning that you can move the whole installation and the CMake files will still work.

       Default PATH_VARS suffixes are:

          BINDIR          BIN_DIR
          SBINDIR         SBIN_DIR
          LIBEXECDIR      LIBEXEC_DIR
          SYSCONFDIR      SYSCONF_DIR
          SHAREDSTATEDIR  SHAREDSTATE_DIR
          LOCALSTATEDIR   LOCALSTATE_DIR
          LIBDIR          LIB_DIR
          INCLUDEDIR      INCLUDE_DIR
          OLDINCLUDEDIR   OLDINCLUDE_DIR
          DATAROOTDIR     DATAROOT_DIR
          DATADIR         DATA_DIR
          INFODIR         INFO_DIR
          LOCALEDIR       LOCALE_DIR
          MANDIR          MAN_DIR
          DOCDIR          DOC_DIR

       more suffixes can be added using the EXTRA_PATH_VARS_SUFFIX argument.

       The   <Name>Targets.cmake  is  generated  using  export(EXPORT)  in  the  build  tree  and
       install(EXPORT) in the installation directory. The targets are exported  using  the  value
       for  the  NAMESPACE  argument  as  namespace.   The  export can be passed using the EXPORT
       argument. If no export is used (e.g. for a CMake script library), pass NO_EXPORT.

       If the INCLUDE_FILE argument is passed, the content of the  specified  file  (which  might
       contain  @variables@)  is  appended  to  the  generated  <Name>Config.cmake  file.  If the
       INCLUDE_CONTENT  argument  is  passed,  the  specified  content   (which   might   contain
       @variables@) is appended to the generated <Name>Config.cmake file.  When a CONFIG_TEMPLATE
       is passed, or a <Name>ConfigVersion.cmake.in or a <name>-config-version.cmake.in  file  is
       available,  these  2 arguments are used to replace the ``@INCLUDED_CONTENT@ string in this
       file.  This allows one to inject custom code to this file, useful e.g. to  set  additional
       variables which are loaded by downstream projects.

       Note  that  content specified with INCLUDE_FILE or INCLUDE_CONTENT cannot reference any of
       the PATH_VARS because this content is not expanded by configure_package_config_file().

       If the COMPONENT argument is passed, it is forwarded to the install() commands,  otherwise
       <Name> is used.

   AddUninstallTarget
       Add the “uninstall” target for your project:

          include(AddUninstallTarget)

       will  create  a  file cmake_uninstall.cmake in the build directory and add a custom target
       uninstall (or UNINSTALL on Visual Studio and Xcode) that will remove the  files  installed
       by       your       package       (using       install_manifest.txt).        See      also
       https://gitlab.kitware.com/cmake/community/wikis/FAQ#can-i-do-make-uninstall-with-cmake

       The AddUninstallTarget module must be included in your main CMakeLists.txt. If included in
       a  subdirectory  it  does  nothing.   This  allows  you  to  use  it  safely  in your main
       CMakeLists.txt and include your project using add_subdirectory (for example when using  it
       with FetchContent).

       If the uninstall target already exists, the module does nothing.

   AddInstallRPATHSupport
       Add support to RPATH during installation to the project and the targets

       add_install_rpath_support
              Add support to RPATH during installation to the project:

       target_append_install_rpath
              Add extra paths to RPATH for a specific target:

            target_append_install_rpath(<target>
                                        <INSTALL_DESTINATION destination>
                                        [LIB_DIRS dir [dir]]
                                        [DEPENDS condition [condition]])

          Arguments:
           - ``INSTALL_DESTINATION`` path where the target will be installed.
           - ``LIB_DIRS`` list of directories to be added to the RPATH. These
             directories will be added "relative" w.r.t. the ``INSTALL_DESTINATION``.
           - ``DEPENDS`` list of conditions that should be ``TRUE`` to enable
             RPATH, for example ``FOO; NOT BAR``.

SUPERBUILD HELPER MODULES

   FindOrBuildPackage
       Searches for a package and builds it if it cannot be found.

       find_or_build_package

       Searches for a package and builds it if it cannot be found:

          find_or_build_package(<PackageName> <find_package_args>)

       This  module  tries  to  locate  a package using find_package().  If the package cannot be
       found it tries to build it, by including Build<package>.  This  file  should  contain  the
       instructions to download and build the package (for example using ExternalProject)

       The arguments passed to the function, are passed to the find_package() command.

       FIXME Figure out how to handle the REQUIRED and QUIET arguments

       If  the package was found, the USE_SYSTEM_<PackageName> cached variable can be disabled in
       order to force CMake to build the package instead of using the one found on the system. To
       automatically  force  CMake  to build all the packages that are also found  on the system,
       the YCM_DISABLE_SYSTEM_PACKAGES cache variable can be enabled.

       This function sets these variables:

          HAVE_SYSTEM_<PackageName> # The package was found on the system
          HAVE_<PackageName> # The package is available

       The user should use the latest, to check if a package is available,  instead  of  checking
       using <PackageName>_FOUND. For example

       FIXME Check uppercase (${_PKG}) and lowercase (${_pkg}) variables

              find_or_build_package(Foo)
              if(HAVE_Foo)
                ...
              endif()

       CMAKE_DISABLE_BUILD_PACKAGE_<PackageName>

       Using this variable, building a package is explicitly forbidden.  therefore if the package
       cannot be found on the system, the HAVE_<PackageName> will be set to false.

   YCMEPHelper
       A helper for ExternalProject:

          ycm_ep_helper(<name>
            [DOCS]
            [TYPE <type>]
            [STYLE <style>]
            [COMPONENT <component>] (default = "external")
            [FOLDER <folder> (default = "<component>")
            [REPOSITORY <repo>]
            [EXCLUDE_FROM_ALL <0|1>]
           #--Git and Hg only arguments-----------
            [TAG <tag>]
           #--Svn only arguments-----------
            [REVISION <revision>]
            [USERNAME <username>]
            [PASSWORD <password>]
            [TRUST_CERT <0|1>]
           #--CMake arguments---------
            [CMAKE_ARGS]
            [CMAKE_CACHE_ARGS]
            [CMAKE_CACHE_DEFAULT_ARGS]
            [DEPENDS]
            [DOWNLOAD_COMMAND]
            [UPDATE_COMMAND]
            [PATCH_COMMAND]
            [CONFIGURE_COMMAND]
            [BUILD_COMMAND]
            [INSTALL_COMMAND]
            [TEST_COMMAND]
            [CLEAN_COMMAND] (not in ExternalProject)
            [TEST_AFTER_INSTALL]
            [TEST_BEFORE_INSTALL]
            [TEST_EXCLUDE_FROM_MAIN]
            )

          YCM_BOOTSTRAP()

       NON_INTERACTIVE_BUILD

       YCM_BOOTSTRAP_BASE_ADDRESS

       YCM_SKIP_HASH_CHECK

       YCM_BOOTSTRAP_VERBOSE

       YCM_EP_INSTALL_DIR

       YCM_EP_ADDITIONAL_CMAKE_ARGS

       YCM_<COMPONENT>_COLOR

       YCM_<COMPONENT>_BGCOLOR

       YCM_<COMPONENT>_NODECOLOR

       TODO Add variable YCM_INSTALL_PREFIX

   StyleBITBUCKET
   StyleGITHUB
   StyleGITLAB_ROBOTOLOGY
   StyleGNOME
   StyleKDE
   StyleLOCAL
   StyleNONE
   StyleSOURCEFORGE

FIND PACKAGE MODULES

   Findassimp
       Find the Open Asset Importer Library (assimp)

   Input variables
       The following variables may be set to influence this module’s behavior:

       ASSIMP_VERBOSE
              to output a detailed log of this module.

   Imported Targets
       This module defines the IMPORTED target assimp::assimp for the library assimp.

   Result Variables
       This module defines the following variables:

       assimp_FOUND
              true if assimp has been found and can be used

       ASSIMP_ROOT_DIR
              the root directory where the installation can be found

       ASSIMP_INCLUDE_DIRS
              include directories for assimp

       ASSIMP_LIBRARIES
              libraries to link against assimp

       ASSIMP_LIBRARY_DIRS
              link directories

       ASSIMP_VERSION
              ASSIMP version

       ASSIMP_VERSION_MAJOR
              ASSIMP major version

       ASSIMP_VERSION_MINOR
              ASSIMP minor version

       ASSIMP_VERSION_REVISION
              ASSIMP revision version

   FindACE
       Try to find the ACE library

       Targets set:

          ACE::ACE (links the ACE library)
          ACE::ACE_INLINE (INTERFACE library for ACE inlines only)

       Variables set:

          ACE_FOUND           - System has ACE library
          ACE_LIBRARIES       - ACE link libraries
          ACE_INCLUDE_DIRS    - ACE library include directories
          ACE_DEFINITIONS     - Additional compiler flags for ACE library
          ACE_VERSION         - ACE library version
          ACE_MAJOR_VERSION   - ACE major version
          ACE_MINOR_VERSION   - ACE minor version
          ACE_BETA_VERSION    - ACE beta version

       Options variables:

          ACE_INLINE (default ON)
            The ACE::ACE target passes __ACE_INLINE__ by default, this can be
            changed by setting ACE_INLINE = OFF.
            The ACE_DEFINITIONS variable is also influenced by the same option.

   FindAtlas
       Find the Atlas (and Lapack) libraries

   FindCFW2CANAPI
       Created:

          CFW2CANAPI_INC_DIRS   - Directories to include to use esdcan api
          CFW2CANAPI_LIB        - Default library to link against to use the esdcan API
          CFF2CANAPI_FOUND      - If false, don't try to use esdcan API

   FindDRAGONFLYAPI
       Created:

          DRAGONFLYAPI_INC_DIRS   - Directories to include to use dragonfly API
          DRAGONFLYAPI_LIB        - Default library to link against to use the dragonfly API
          DRAGONFLYAPI_FOUND      - If false, don't try to use dragonfly API

   FindESDCANAPI
       Created:

          ESDCANAPI_INC_DIRS   - Directories to include to use esdcan api
          ESDCANAPI_LIB        - Default library to link against to use the esdcan API
          ESDCANAPI_FOUND      - If false, don't try to use esdcan API

   FindFreenect
       Try to find the Freenect library.  Once done this will define the following variables:

          Freenect_FOUND         - System has Freenect
          Freenect_INCLUDE_DIRS  - Freenect include directory
          Freenect_LIBRARIES     - Freenect libraries
          Freenect_DEFINITIONS   - Additional compiler flags for Freenect
          Freenect_VERSION       - Freenect version
          Freenect_MAJOR_VERSION - Freenect major version
          Freenect_MINOR_VERSION - Freenect minor version
          Freenect_PATCH_VERSION - Freenect patch version

   FindFTDI
       Try to find ftdi.  Once done this will define:

          FTDI_FOUND - system has ftdi
          FTDI_INCLUDE_DIR - ~ the ftdi include directory
          FTDI_LIBRARY - Link these to use ftdi

   FindFuse
       Try to find the Fuse library.  Once done this will define the following variables:

          Fuse_FOUND         - System has Fuse
          Fuse_INCLUDE_DIRS  - Fuse include directory
          Fuse_LIBRARIES     - Fuse libraries
          Fuse_DEFINITIONS   - Additional compiler flags for Fuse
          Fuse_VERSION       - Fuse version
          Fuse_MAJOR_VERSION - Fuse major version
          Fuse_MINOR_VERSION - Fuse minor version
          Fuse_PATCH_VERSION - Fuse patch version
          Fuse_TWEAK_VERSION - Fuse tweak version

   FindGLFW3
       Find the GLFW3 framework.

   IMPORTED Targets
       This module defines the IMPORTED target GLFW3::GLFW3, if GLFW3 has been found.

   Result Variables
       This module defines the following variables:

          GLFW3_INCLUDE_DIRS - include directories for GLFW3
          GLFW3_LIBRARIES - libraries to link against GLFW3
          GLFW3_FOUND - true if GLFW3 has been found and can be used

   Environment Variables
       If the library is not found on system paths, the GLFW3_ROOT environment  variable  can  be
       used to locate the lbrary.

   FindGLM
       Find the OpenGL Mathematics (glm)

   Input variables
       The following variables may be set to influence this module’s behavior:

       GLM_VERBOSE
              to output a detailed log of this module.

   Imported Targets
       This module defines the IMPORTED target glm for the library glm.

   Result Variables
       This module defines the following variables:

       GLM_FOUND
              true if assimp has been found and can be used

       GLM_INCLUDE_DIRS
              include directories for assimp

       GLM_VERSION
              GLM version

       GLM_VERSION_MAJOR
              GLM major version

       GLM_VERSION_MINOR
              GLM minor version

       GLM_VERSION_PATCH
              GLM patch version

   FindGooCanvas
       Try to find the GooCanvas library.  Once done this will define the following variables:

          GooCanvas_FOUND         - System has GooCanvas
          GooCanvas_INCLUDE_DIRS  - GooCanvas include directory
          GooCanvas_LIBRARIES     - GooCanvas libraries
          GooCanvas_DEFINITIONS   - Additional compiler flags for GooCanvas
          GooCanvas_VERSION       - GooCanvas version
          GooCanvas_MAJOR_VERSION - GooCanvas major version
          GooCanvas_MINOR_VERSION - GooCanvas minor version
          GooCanvas_PATCH_VERSION - GooCanvas patch version
          GooCanvas_TWEAK_VERSION - GooCanvas tweak version

       If the library is found, the imported target GooCanvas::goocanvas is created.

   FindGooCanvasMM
       Try to find the GooCanvasMM library.  Once done this will define the following variables:

          GooCanvasMM_FOUND         - System has GooCanvasMM
          GooCanvasMM_INCLUDE_DIRS  - GooCanvasMM include directory
          GooCanvasMM_LIBRARIES     - GooCanvasMM libraries
          GooCanvasMM_DEFINITIONS   - Additional compiler flags for GooCanvasMM
          GooCanvasMM_VERSION       - GooCanvasMM version
          GooCanvasMM_MAJOR_VERSION - GooCanvasMM major version
          GooCanvasMM_MINOR_VERSION - GooCanvasMM minor version
          GooCanvasMM_PATCH_VERSION - GooCanvasMM patch version
          GooCanvasMM_TWEAK_VERSION - GooCanvasMM tweak version

       If the library is found, the imported target GooCanvasMM::goocanvasmm is created.

   FindGSL
       Try to find GSL library Once run this will define:

          GSL_FOUND
          GSL_INCLUDE_DIR
          GSL_INCLUDE_DIRS
          GSL_LIBRARIES
          GSL_LINK_DIRECTORIES
          GSLCBLAS_LIBRARY
          GSL_LIBRARY

   FindGtkDatabox
       Try to find the GtkDatabox library.  Once done this will define the following variables:

          GtkDatabox_FOUND         - System has GtkDatabox
          GtkDatabox_INCLUDE_DIRS  - GtkDatabox include directory
          GtkDatabox_LIBRARIES     - GtkDatabox libraries
          GtkDatabox_DEFINITIONS   - Additional compiler flags for GtkDatabox
          GtkDatabox_VERSION       - GtkDatabox version
          GtkDatabox_MAJOR_VERSION - GtkDatabox major version
          GtkDatabox_MINOR_VERSION - GtkDatabox minor version
          GtkDatabox_PATCH_VERSION - GtkDatabox patch version
          GtkDatabox_TWEAK_VERSION - GtkDatabox tweak version

       If the library is found, the imported target GtkDatabox::gtkdatabox is created.

   FindGtkDataboxMM
       Try to find the GtkDataboxMM library.  Once done this will define the following variables:

          GtkDataboxMM_FOUND         - System has GtkDataboxMM
          GtkDataboxMM_INCLUDE_DIRS  - GtkDataboxMM include directory
          GtkDataboxMM_LIBRARIES     - GtkDataboxMM libraries
          GtkDataboxMM_DEFINITIONS   - Additional compiler flags for GtkDataboxMM
          GtkDataboxMM_VERSION       - GtkDataboxMM version
          GtkDataboxMM_MAJOR_VERSION - GtkDataboxMM major version
          GtkDataboxMM_MINOR_VERSION - GtkDataboxMM minor version
          GtkDataboxMM_PATCH_VERSION - GtkDataboxMM patch version
          GtkDataboxMM_TWEAK_VERSION - GtkDataboxMM tweak version

       If the library is found, the imported target GtkDataboxMM::gtkdataboxmm is created.

   FindI2C
       Find the I2C device library.

       Once done this will define the following variables:

          I2C_INCLUDE_DIRS    - I2C include directory
          I2C_LIBRARIES       - I2C libraries
          I2C_FOUND           - if false, you cannot build anything that requires I2C

   FindIPOPT
       Try to locate the IPOPT library

       On  non  Windows  systems, use pkg-config to try to locate the library, if this fails then
       try to locate the library in the directory pointed by the IPOPT_DIR environment variable.

       On Windows systems,  just  try  to  find  the  library  using  the  IPOPT_DIR  environment
       variable.

       Create the following variables:

          IPOPT_INCLUDE_DIRS - Directories to include to use IPOPT
          IPOPT_LIBRARIES    - Default library to link against to use IPOPT
          IPOPT_DEFINITIONS  - Flags to be added to linker's options
          IPOPT_LINK_FLAGS   - Flags to be added to linker's options
          IPOPT_FOUND        - If false, don't try to use IPOPT

   FindIPP
       Try to find the IPP library.

   FindLibdc1394
       Try to find the libdc1394 library.  Once done this will define the following variables:

          Libdc1394_FOUND         - System has libdc1394
          Libdc1394_INCLUDE_DIRS  - libdc1394 include directory
          Libdc1394_LIBRARIES     - libdc1394 libraries
          Libdc1394_DEFINITIONS   - Additional compiler flags for libdc1394
          Libdc1394_VERSION       - libdc1394 version
          Libdc1394_MAJOR_VERSION - libdc1394 major version
          Libdc1394_MINOR_VERSION - libdc1394 minor version
          Libdc1394_PATCH_VERSION - libdc1394 patch version

   FindLibedit
       Try  to  find  NetBSD  Editline  library (libedit), a Berkeley-style licensed command line
       editor library provides generic line editing, history, and tokenization functions, similar
       to those found in GNU Readline.  Once done this will define the following variables:

          Libedit_FOUND         - System has Editline library
          Libedit_INCLUDE_DIRS  - Editline library include directory
          Libedit_LIBRARIES     - Editline library libraries
          Libedit_DEFINITIONS   - Additional compiler flags for Editline library
          Libedit_VERSION       - Editline library version
          Libedit_MAJOR_VERSION - Editline library major version
          Libedit_MINOR_VERSION - Editline library minor version

       Environment variables used to locate the Editline library:

          READLINE_DIR - Libedit root directory

       Cached variables used to locate the NetBSD Editline library:

          Libedit_INCLUDE_DIR - the Libedit include directory
          Libedit_LIBRARY_RELEASE - NetBSD Editline library (release)
          Libedit_LIBRARY_DEBUG - NetBSD Editline library  (debug)

   FindLibOVR
       Find the LibOVR library in Oculus Rift SDK.

   IMPORTED Targets
       This module defines the following IMPORTED targets if LibOVR has been found:

          LibOVR::OVRKernel
          LibOVR::OVR

   Result Variables
       This module defines the following variables:

          LibOVR_FOUND                   - System has LibOVR
          LibOVR_VERSION                 - LibOVR version
          LibOVR_VERSION_PRODUCT         - LibOVR product version
          LibOVR_VERSION_MAJOR           - LibOVR major version
          LibOVR_VERSION_MINOR           - LibOVR minor version
          LibOVR_VERSION_PATCH           - LibOVR patch version
          LibOVR_VERSION_BUILD           - LibOVR build number
          LibOVR_VERSION_STRING          - LibOVR version
          LibOVR_VERSION_DETAILED_STRING - LibOVR version (including build number)
          LibOVR_INCLUDE_DIRS            - Include directories for LibOVR
          LibOVR_LIBRARIES               - libraries to link against LibOVR

   FindLibusb1
       Try to find the libusb-1 library.  Once done this will define the following variables:

          Libusb1_FOUND         - System has libusb-1
          Libusb1_INCLUDE_DIRS  - libusb-1 include directory
          Libusb1_LIBRARIES     - libusb-1 libraries
          Libusb1_DEFINITIONS   - Additional compiler flags for libusb-1
          Libusb1_VERSION       - libusb-1 version
          Libusb1_MAJOR_VERSION - libusb-1 major version
          Libusb1_MINOR_VERSION - libusb-1 minor version
          Libusb1_PATCH_VERSION - libusb-1 patch version

   FindLibv4l2
       Try to find the libv4l2 library.  Once done this will define the following variables:

          Libv4l2_FOUND         - System has libv4l2
          Libv4l2_INCLUDE_DIRS  - libv4l2 include directory
          Libv4l2_LIBRARIES     - libv4l2 libraries
          Libv4l2_DEFINITIONS   - Additional compiler flags for libv4l2
          Libv4l2_VERSION       - libv4l2 version
          Libv4l2_MAJOR_VERSION - libv4l2 major version
          Libv4l2_MINOR_VERSION - libv4l2 minor version
          Libv4l2_PATCH_VERSION - libv4l2 patch version
          Libv4l2_TWEAK_VERSION - libv4l2 tweak version

   FindLibv4lconvert
       Try  to  find  the  libv4lconvert  library.   Once  done  this  will  define the following
       variables:

          Libv4lconvert_FOUND         - System has libv4lconvert
          Libv4lconvert_INCLUDE_DIRS  - libv4lconvert include directory
          Libv4lconvert_LIBRARIES     - libv4lconvert libraries
          Libv4lconvert_DEFINITIONS   - Additional compiler flags for libv4lconvert
          Libv4lconvert_VERSION       - libv4lconvert version
          Libv4lconvert_MAJOR_VERSION - libv4lconvert major version
          Libv4lconvert_MINOR_VERSION - libv4lconvert minor version
          Libv4lconvert_PATCH_VERSION - libv4lconvert patch version
          Libv4lconvert_TWEAK_VERSION - libv4lconvert tweak version

   FindNVIDIACg
       Try to find NVIDIACg libraries

   FindODE
       Options:

          ODE_DOUBLE_PRECISION  -use double precision ode libraries
          ODE_STATIC            -link against static libraries

       On exit create the following variables:

          ODE_INCLUDE_DIRS  - Directories to include to use ODE
          ODE_LIBRARIES     - Default library to link against to use ODE
          ODE_FOUND         - If false, library not found

   FindOpenCV
       Find OpenCV - variables set:

          OpenCV_FOUND
          OpenCV_LIBRARIES
          OpenCV_INCLUDE_DIRS

       This script is a combination from multiple sources that use different variable names;  the
       names are reconciled at the end of the script.

   Todo
       Check if this module is still needed with recent CMake releases.

   Todo
       Check if the license is correct

   FindOpenGL
       Wrap kitware’s original FindOpenGL. Standardize variables.

       In windows require you set OpenGL_DIR

       Set:

          OpenGL_FOUND
          OpenGL_LIBRARIES
          OpenGL_INCLUDE_DIRS

   Todo
       Check if this module is still needed with recent CMake releases.

   FindOpenNI
       Try to find the OpenNI library.  Once done this will define the following variables:

          OpenNI_FOUND         - System has OpenNI
          OpenNI_INCLUDE_DIRS  - OpenNI include directory
          OpenNI_LIBRARIES     - OpenNI libraries
          OpenNI_DEFINITIONS   - Additional compiler flags for OpenNI
          OpenNI_VERSION       - OpenNI version
          OpenNI_MAJOR_VERSION - OpenNI major version
          OpenNI_MINOR_VERSION - OpenNI minor version
          OpenNI_PATCH_VERSION - OpenNI patch version

   FindPLXCANAPI
       Created:

          PLXCANAPI_INC_DIRS   - Directories to include to use esdcan api
          PLXCANAPI_LIB        - Default library to link against to use the esdcan API
          PLXCANAPI_FOUND      - If false, don't try to use esdcan API

   FindPortAudio
       Try to find the PortAudio library.

   FindqpOASES
       Try to find the qpOASES library.  Once done this will define the following variables:

          qpOASES_FOUND         - System has qpOASES
          qpOASES_INCLUDE_DIRS  - qpOASES include directory
          qpOASES_LIBRARIES     - qpOASES libraries

       qpOASES  does  not  have an “install” step, and the includes are in the source tree, while
       the libraries are in the build  tree.   Therefore  the  environment  and  cmake  variables
       qpOASES_SOURCE_DIR  and  qpOASES_BINARY_DIR  will  be  used  to  locate  the  includes and
       libraries.

   FindReadline
       Try to find GNU Readline, a library for easy editing of command  lines.   Once  done  this
       will define the following variables:

          Readline_FOUND         - System has GNU Readline
          Readline_INCLUDE_DIRS  - GNU Readline include directory
          Readline_LIBRARIES     - GNU Readline libraries
          Readline_DEFINITIONS   - Additional compiler flags for GNU Readline
          Readline_VERSION       - GNU Readline version
          Readline_MAJOR_VERSION - GNU Readline major version
          Readline_MINOR_VERSION - GNU Readline minor version

       Environment variables used to locate the GNU Readline library:

          READLINE_DIR - Readline root directory

       Cached variables used to locate the GNU Readline library:

          Readline_INCLUDE_DIR - the Readline include directory
          Readline_LIBRARY_RELEASE - GNU Readline library (release)
          Readline_LIBRARY_DEBUG - GNU Readline library (debug)

   FindSQLite
       Try to find the SQLite library.  Once done this will define the following variables:

          SQLite_FOUND         - System has SQLite
          SQLite_INCLUDE_DIRS  - SQLite include directory
          SQLite_LIBRARIES     - SQLite libraries
          SQLite_DEFINITIONS   - Additional compiler flags for SQLite
          SQLite_VERSION       - SQLite version
          SQLite_MAJOR_VERSION - SQLite major version
          SQLite_MINOR_VERSION - SQLite minor version
          SQLite_PATCH_VERSION - SQLite patch version
          SQLite_TWEAK_VERSION - SQLite tweak version

   FindStage
       Try  to  find  Stage,  a  library  for easy editing of command lines.  Once done this will
       define the following variables:

          Stage_FOUND         - System has Stage
          Stage_INCLUDE_DIRS  - Stage include directory
          Stage_LIBRARIES     - Stage libraries
          Stage_DEFINITIONS   - Additional compiler flags for Stage
          Stage_VERSION       - Stage version
          Stage_MAJOR_VERSION - Stage major version
          Stage_MINOR_VERSION - Stage minor version

   FindTinyXML
       Try to find the TinyXML library.  Once done this will define the following variables:

          TinyXML_FOUND         - System has TinyXML
          TinyXML_INCLUDE_DIRS  - TinyXML include directory
          TinyXML_LIBRARIES     - TinyXML libraries
          TinyXML_DEFINITIONS   - Additional compiler flags for TinyXML
          TinyXML_VERSION       - TinyXML version
          TinyXML_MAJOR_VERSION - TinyXML major version
          TinyXML_MINOR_VERSION - TinyXML minor version
          TinyXML_PATCH_VERSION - TinyXML patch version

   FindYamlCpp
       Try to find the YamlCpp library.  Once done this will define the following variables:

          YamlCpp_FOUND         - System has YamlCpp
          YamlCpp_INCLUDE_DIRS  - YamlCpp include directory
          YamlCpp_LIBRARIES     - YamlCpp libraries
          YamlCpp_DEFINITIONS   - Additional compiler flags for YamlCpp
          YamlCpp_VERSION       - YamlCpp version
          YamlCpp_MAJOR_VERSION - YamlCpp major version
          YamlCpp_MINOR_VERSION - YamlCpp minor version
          YamlCpp_PATCH_VERSION - YamlCpp patch version
          YamlCpp_TWEAK_VERSION - YamlCpp tweak version

BUILD PACKAGE MODULES

   BuildECM
       ECM - extra-cmake-modules (from KDE project)

   BuildEigen3
       Eigen3

   BuildGazeboYARPPlugins
       GazeboYARPPlugins

   BuildGooCanvas
       GooCanvas

   BuildGooCanvasMM
       GooCanvasMM

   BuildGtkDatabox
       GtkDatabox

   BuildGtkDataboxMM
       GtkDataboxMM

   BuildICUB
       ICUB

   BuildqpOASES
       qpOASES

   BuildTinyXML
       TinyXML

   BuildYARP
       YARP

CMAKE PROPOSED MODULES

       These modules are patched versions of the ones included in CMake.

   ExternalProject
   External Project Definition
       ExternalProject_Add
              The ExternalProject_Add() function creates  a  custom  target  to  drive  download,
              update/patch, configure, build, install and test steps of an external project:

                 ExternalProject_Add(<name> [<option>...])

              The  individual  steps  within  the process can be driven independently if required
              (e.g. for CDash submission) and extra custom steps can be defined, along  with  the
              ability  to  control  the  step  dependencies. The directory structure used for the
              management of the external project can also be customized. The function supports  a
              large number of options which can be used to tailor the external project behavior.

              Directory Options:
                     Most  of the time, the default directory layout is sufficient. It is largely
                     an implementation detail that the  main  project  usually  doesn’t  need  to
                     change.  In  some  circumstances, however, control over the directory layout
                     can be useful or necessary.  The  directory  options  are  potentially  more
                     useful   from   the   point  of  view  that  the  main  build  can  use  the
                     ExternalProject_Get_Property() command to  retrieve  their  values,  thereby
                     allowing  the  main  project  to  refer  to  build artifacts of the external
                     project.

                     PREFIX <dir>
                            Root directory for  the  external  project.  Unless  otherwise  noted
                            below,  all  other  directories  associated with the external project
                            will be created under here.

                     TMP_DIR <dir>
                            Directory in which to store temporary files.

                     STAMP_DIR <dir>
                            Directory in which to store the timestamps of each  step.  Log  files
                            from  individual  steps  are also created in here unless overriden by
                            LOG_DIR (see Logging Options below).

                     LOG_DIR <dir>
                            Directory in which to store the logs of each step.

                     DOWNLOAD_DIR <dir>
                            Directory in which to store downloaded files before  unpacking  them.
                            This  directory  is  only  used by the URL download method, all other
                            download methods use SOURCE_DIR directly instead.

                     SOURCE_DIR <dir>
                            Source directory into which downloaded contents will be unpacked,  or
                            for  non-URL  download methods, the directory in which the repository
                            should be  checked  out,  cloned,  etc.  If  no  download  method  is
                            specified,  this  must  point  to  an  existing  directory  where the
                            external project has already been unpacked or cloned/checked out.

                            NOTE:
                               If a download method is specified, any existing  contents  of  the
                               source  directory  may  be  deleted.  Only the URL download method
                               checks whether this directory is either missing  or  empty  before
                               initiating  the  download,  stopping  with  an  error if it is not
                               empty. All other download methods silently  discard  any  previous
                               contents of the source directory.

                     BINARY_DIR <dir>
                            Specify  the  build  directory  location.  This  option is ignored if
                            BUILD_IN_SOURCE is enabled.

                     INSTALL_DIR <dir>
                            Installation prefix to be placed in  the  <INSTALL_DIR>  placeholder.
                            This  does  not actually configure the external project to install to
                            the given prefix. That must be done by passing appropriate  arguments
                            to the external project configuration step, e.g. using <INSTALL_DIR>.

                     If  any  of  the above ..._DIR options are not specified, their defaults are
                     computed as follows.  If  the  PREFIX  option  is  given  or  the  EP_PREFIX
                     directory  property  is set, then an external project is built and installed
                     under the specified prefix:

                        TMP_DIR      = <prefix>/tmp
                        STAMP_DIR    = <prefix>/src/<name>-stamp
                        DOWNLOAD_DIR = <prefix>/src
                        SOURCE_DIR   = <prefix>/src/<name>
                        BINARY_DIR   = <prefix>/src/<name>-build
                        INSTALL_DIR  = <prefix>
                        LOG_DIR      = <STAMP_DIR>

                     Otherwise, if the EP_BASE directory property is set then  components  of  an
                     external project are stored under the specified base:

                        TMP_DIR      = <base>/tmp/<name>
                        STAMP_DIR    = <base>/Stamp/<name>
                        DOWNLOAD_DIR = <base>/Download/<name>
                        SOURCE_DIR   = <base>/Source/<name>
                        BINARY_DIR   = <base>/Build/<name>
                        INSTALL_DIR  = <base>/Install/<name>
                        LOG_DIR      = <STAMP_DIR>

                     If no PREFIX, EP_PREFIX, or EP_BASE is specified, then the default is to set
                     PREFIX to <name>-prefix. Relative paths  are  interpreted  with  respect  to
                     CMAKE_CURRENT_BINARY_DIR at the point where ExternalProject_Add() is called.

              Download Step Options:
                     A  download  method can be omitted if the SOURCE_DIR option is used to point
                     to an existing non-empty directory. Otherwise, one of the  download  methods
                     below must be specified (multiple download methods should not be given) or a
                     custom DOWNLOAD_COMMAND provided.

                     DOWNLOAD_COMMAND <cmd>...
                            Overrides  the  command  used  for  the  download   step   (generator
                            expressions  are  supported).  If this option is specified, all other
                            download options will be ignored. Providing an empty string for <cmd>
                            effectively disables the download step.

                     URL Download

                            URL <url1> [<url2>...]
                                   List  of paths and/or URL(s) of the external project’s source.
                                   When more than one URL is given, they are tried in turn  until
                                   one  succeeds. A URL may be an ordinary path in the local file
                                   system (in which case it must be the only URL provided) or any
                                   downloadable  URL  supported  by the file(DOWNLOAD) command. A
                                   local  filesystem  path  may  refer  to  either  an   existing
                                   directory  or to an archive file, whereas a URL is expected to
                                   point to a file which can be treated as an  archive.  When  an
                                   archive  is used, it will be unpacked automatically unless the
                                   DOWNLOAD_NO_EXTRACT option is set to prevent it.  The  archive
                                   type  is  determined  by  inspecting the actual content rather
                                   than using logic based on the file extension.

                            URL_HASH <algo>=<hashValue>
                                   Hash of the archive file to be downloaded. The argument should
                                   be of the form <algo>=<hashValue> where algo can be any of the
                                   hashing algorithms supported by the file() command. Specifying
                                   this  option  is strongly recommended for URL downloads, as it
                                   ensures the integrity of the downloaded content.  It  is  also
                                   used  as  a  check  for a previously downloaded file, allowing
                                   connection to the remote location to be avoided altogether  if
                                   the  local  directory  already  has  a  file  from  an earlier
                                   download that matches the specified hash.

                            URL_MD5 <md5>
                                   Equivalent to URL_HASH MD5=<md5>.

                            DOWNLOAD_NAME <fname>
                                   File name to use for the downloaded file. If  not  given,  the
                                   end of the URL is used to determine the file name. This option
                                   is rarely needed, the default name is generally  suitable  and
                                   is   not  normally  used  outside  of  code  internal  to  the
                                   ExternalProject module.

                            DOWNLOAD_NO_EXTRACT <bool>
                                   Allows the extraction part of the download step to be disabled
                                   by  passing  a  boolean  true  value  for this option. If this
                                   option is not given, the downloaded contents will be  unpacked
                                   automatically  if  required.  If extraction has been disabled,
                                   the  full  path  to  the  downloaded  file  is  available   as
                                   <DOWNLOADED_FILE>  in  subsequent  steps  or  as  the property
                                   DOWNLOADED_FILE   with   the    ExternalProject_Get_Property()
                                   command.

                            DOWNLOAD_NO_PROGRESS <bool>
                                   Can  be used to disable logging the download progress. If this
                                   option is  not  given,  download  progress  messages  will  be
                                   logged.

                            TIMEOUT <seconds>
                                   Maximum time allowed for file download operations.

                            HTTP_USERNAME <username>
                                   Username  for  the  download  operation  if  authentication is
                                   required.

                            HTTP_PASSWORD <password>
                                   Password for  the  download  operation  if  authentication  is
                                   required.

                            HTTP_HEADER <header1> [<header2>...]
                                   Provides  an  arbitrary  list of HTTP headers for the download
                                   operation.  This  can  be  useful  for  accessing  content  in
                                   systems like AWS, etc.

                            TLS_VERIFY <bool>
                                   Specifies whether certificate verification should be performed
                                   for https URLs. If this option is not  provided,  the  default
                                   behavior  is  determined by the CMAKE_TLS_VERIFY variable (see
                                   file(DOWNLOAD)).  If  that  is  also  not   set,   certificate
                                   verification  will  not  be  performed.  In  situations  where
                                   URL_HASH cannot be provided, this option can be an alternative
                                   verification measure.

                            TLS_CAINFO <file>
                                   Specify   a  custom  certificate  authority  file  to  use  if
                                   TLS_VERIFY is enabled. If this option is  not  specified,  the
                                   value  of  the  CMAKE_TLS_CAINFO variable will be used instead
                                   (see file(DOWNLOAD))

                            NETRC <level>
                                   Specify whether the .netrc file is to be used  for  operation.
                                   If  this option is not specified, the value of the CMAKE_NETRC
                                   variable will  be  used  instead  (see  file(DOWNLOAD))  Valid
                                   levels are:

                                   IGNORED
                                          The .netrc file is ignored.  This is the default.

                                   OPTIONAL
                                          The .netrc file is optional, and information in the URL
                                          is preferred.  The file will be scanned to  find  which
                                          ever information is not specified in the URL.

                                   REQUIRED
                                          The .netrc file is required, and information in the URL
                                          is ignored.

                            NETRC_FILE <file>
                                   Specify an alternative .netrc file to the  one  in  your  home
                                   directory  if the NETRC level is OPTIONAL or REQUIRED. If this
                                   option is not specified, the  value  of  the  CMAKE_NETRC_FILE
                                   variable will be used instead (see file(DOWNLOAD))

                     Git    NOTE:  A  git  version of 1.6.5 or later is required if this download
                            method is used.

                            GIT_REPOSITORY <url>
                                   URL of the git repository.  Any  URL  understood  by  the  git
                                   command may be used.

                            GIT_TAG <tag>
                                   Git  branch  name,  tag or commit hash. Note that branch names
                                   and tags should generally be specified as remote  names  (i.e.
                                   origin/myBranch  rather  than  simply  myBranch). This ensures
                                   that if the remote end has its tag moved or branch rebased  or
                                   history  rewritten,  the  local  clone  will  still be updated
                                   correctly. In  general,  however,  specifying  a  commit  hash
                                   should be preferred for a number of reasons:

                                   • If  the  local clone already has the commit corresponding to
                                     the hash, no git fetch needs to be performed  to  check  for
                                     changes  each  time  CMake  is  re-run. This can result in a
                                     significant speed up if many  external  projects  are  being
                                     used.

                                   • Using  a  specific  git hash ensures that the main project’s
                                     own history is fully traceable to a specific  point  in  the
                                     external  project’s  evolution.  If  a branch or tag name is
                                     used instead, then checking out a  specific  commit  of  the
                                     main  project  doesn’t  necessarily pin the whole build to a
                                     specific point in the life of  the  external  project.   The
                                     lack  of  such deterministic behavior makes the main project
                                     lose traceability and repeatability.

                                   If GIT_SHALLOW is enabled then GIT_TAG works only with  branch
                                   names and tags.  A commit hash is not allowed.

                            GIT_REMOTE_NAME <name>
                                   The  optional  name  of  the  remote.  If  this  option is not
                                   specified, it defaults to origin.

                            GIT_SUBMODULES <module>...
                                   Specific git submodules that should also be updated.  If  this
                                   option is not provided, all git submodules will be updated.

                            GIT_SHALLOW <bool>
                                   When  this  option is enabled, the git clone operation will be
                                   given the --depth 1 option. This  performs  a  shallow  clone,
                                   which   avoids  downloading  the  whole  history  and  instead
                                   retrieves just the commit denoted by the GIT_TAG option.

                            GIT_PROGRESS <bool>
                                   When enabled, this option instructs the git clone operation to
                                   report  its  progress  by  passing  it  the --progress option.
                                   Without this option, the clone step  for  large  projects  may
                                   appear  to  make the build stall, since nothing will be logged
                                   until the clone operation finishes. While this option  can  be
                                   used  to  provide  progress  to  prevent the appearance of the
                                   build having stalled, it may also make the build overly  noisy
                                   if lots of external projects are used.

                            GIT_CONFIG <option1> [<option2>...]
                                   Specify  a  list  of config options to pass to git clone. Each
                                   option listed  will  be  transformed  into  its  own  --config
                                   <option>  on  the  git  clone  command  line, with each option
                                   required to be in the form key=value.

                     Subversion

                            SVN_REPOSITORY <url>
                                   URL of the Subversion repository.

                            SVN_REVISION -r<rev>
                                   Revision to checkout from the Subversion repository.

                            SVN_USERNAME <username>
                                   Username for the Subversion checkout and update.

                            SVN_PASSWORD <password>
                                   Password for the Subversion checkout and update.

                            SVN_TRUST_CERT <bool>
                                   Specifies  whether  to  trust  the  Subversion   server   site
                                   certificate.  If  enabled,  the  --trust-server-cert option is
                                   passed to the svn checkout and update commands.

                     Mercurial

                            HG_REPOSITORY <url>
                                   URL of the mercurial repository.

                            HG_TAG <tag>
                                   Mercurial branch name, tag or commit id.

                     CVS

                            CVS_REPOSITORY <cvsroot>
                                   CVSROOT of the CVS repository.

                            CVS_MODULE <mod>
                                   Module to checkout from the CVS repository.

                            CVS_TAG <tag>
                                   Tag to checkout from the CVS repository.

              Update/Patch Step Options:
                     Whenever CMake is re-run, by default the external project’s sources will  be
                     updated if the download method supports updates (e.g. a git repository would
                     be checked if the GIT_TAG does not refer to a specific commit).

                     UPDATE_COMMAND <cmd>...
                            Overrides the download method’s update step with  a  custom  command.
                            The command may use generator expressions.

                     UPDATE_DISCONNECTED <bool>
                            When  enabled,  this  option causes the update step to be skipped. It
                            does not, however, prevent the download step.  The  update  step  can
                            still      be      added      as      a      step     target     (see
                            ExternalProject_Add_StepTargets())  and  called  manually.  This   is
                            useful  if  you  want  to  allow developers to build the project when
                            disconnected from the network (the network may still  be  needed  for
                            the download step though).

                            When  this  option  is present, it is generally advisable to make the
                            value a cache variable under  the  developer’s  control  rather  than
                            hard-coding  it.  If this option is not present, the default value is
                            taken from the EP_UPDATE_DISCONNECTED directory property. If that  is
                            also   not   defined,   updates   are   performed   as   normal.  The
                            EP_UPDATE_DISCONNECTED  directory   property   is   intended   as   a
                            convenience  for  controlling the UPDATE_DISCONNECTED behavior for an
                            entire section of a project’s directory hierarchy and may be  a  more
                            convenient method of giving developers control over whether or not to
                            perform updates (assuming the project also provides a cache  variable
                            or some other convenient method for setting the directory property).

                     PATCH_COMMAND <cmd>...
                            Specifies  a  custom command to patch the sources after an update. By
                            default, no patch command is defined.  Note  that  it  can  be  quite
                            difficult  to  define  an  appropriate  patch  command  that performs
                            robustly, especially for download methods such as git where  changing
                            the  GIT_TAG  will not discard changes from a previous patch, but the
                            patch command will be called again after updating to the new tag.

              Configure Step Options:
                     The configure step is run after the download and update steps.  By  default,
                     the  external  project  is  assumed  to  be a CMake project, but this can be
                     overridden if required.

                     CONFIGURE_COMMAND <cmd>...
                            The default configure command runs CMake with options  based  on  the
                            main  project. For non-CMake external projects, the CONFIGURE_COMMAND
                            option must be used to override this behavior (generator  expressions
                            are  supported). For projects that require no configure step, specify
                            this option with an empty string as the command to execute.

                     CMAKE_COMMAND /.../cmake
                            Specify an alternative cmake executable for the configure  step  (use
                            an  absolute  path).  This  is generally not recommended, since it is
                            usually desirable to use the same CMake version throughout the  whole
                            build.  This option is ignored if a custom configure command has been
                            specified with CONFIGURE_COMMAND.

                     CMAKE_GENERATOR <gen>
                            Override the CMake generator used for  the  configure  step.  Without
                            this  option, the same generator as the main build will be used. This
                            option is ignored if a custom configure command  has  been  specified
                            with the CONFIGURE_COMMAND option.

                     CMAKE_GENERATOR_PLATFORM <platform>
                            Pass  a  generator-specific  platform  name to the CMake command (see
                            CMAKE_GENERATOR_PLATFORM). It is an  error  to  provide  this  option
                            without the CMAKE_GENERATOR option.

                     CMAKE_GENERATOR_TOOLSET <toolset>
                            Pass  a  generator-specific  toolset  name  to the CMake command (see
                            CMAKE_GENERATOR_TOOLSET). It is  an  error  to  provide  this  option
                            without the CMAKE_GENERATOR option.

                     CMAKE_GENERATOR_INSTANCE <instance>
                            Pass  a  generator-specific  instance  selection to the CMake command
                            (see CMAKE_GENERATOR_INSTANCE). It is an error to provide this option
                            without the CMAKE_GENERATOR option.

                     CMAKE_ARGS <arg>...
                            The  specified  arguments  are passed to the cmake command line. They
                            can be any argument the cmake command  understands,  not  just  cache
                            values  defined  by  -D...  arguments  (see  also  CMake Options). In
                            addition, arguments may use generator expressions.

                     CMAKE_CACHE_ARGS <arg>...
                            This is an alternate way of specifying cache variables where  command
                            line  length  issues may become a problem. The arguments are expected
                            to be in the form -Dvar:STRING=value, which are then transformed into
                            CMake set() commands with the FORCE option used. These set() commands
                            are written to a pre-load script which  is  then  applied  using  the
                            cmake   -C   command   line   option.  Arguments  may  use  generator
                            expressions.

                     CMAKE_CACHE_DEFAULT_ARGS <arg>...
                            This is the same as the  CMAKE_CACHE_ARGS  option  except  the  set()
                            commands  do not include the FORCE keyword. This means the values act
                            as initial defaults only and will not override any variables  already
                            set from a previous run. Use this option with care, as it can lead to
                            different behavior depending on whether the build starts from a fresh
                            build directory or re-uses previous build contents.

                     SOURCE_SUBDIR <dir>
                            When  no  CONFIGURE_COMMAND  option  is specified, the configure step
                            assumes the external project has a CMakeLists.txt file at the top  of
                            its source tree (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can be
                            used to point to an alternative directory within the source  tree  to
                            use  as  the  top  of  the  CMake source tree instead. This must be a
                            relative path and  it  will  be  interpreted  as  being  relative  to
                            SOURCE_DIR.   When  BUILD_IN_SOURCE 1 is specified, the BUILD_COMMAND
                            is used to point to an alternative directory within the source tree.

              Build Step Options:
                     If the configure step assumed the external project uses CMake as  its  build
                     system,  the  build  step will also. Otherwise, the build step will assume a
                     Makefile-based build and simply run make with no arguments  as  the  default
                     build step. This can be overridden with custom build commands if required.

                     BUILD_COMMAND <cmd>...
                            Overrides  the  default  build  command  (generator  expressions  are
                            supported). If this option is not given, the  default  build  command
                            will  be  chosen  to  integrate  with  the  main  build  in  the most
                            appropriate way (e.g. using recursive make for Makefile generators or
                            cmake  --build if the project uses a CMake build). This option can be
                            specified with an empty string as the command to make the build  step
                            do nothing.

                     BUILD_IN_SOURCE <bool>
                            When  this  option is enabled, the build will be done directly within
                            the external project’s source tree. This should generally be avoided,
                            the  use  of  a separate build directory is usually preferred, but it
                            can be useful when the external project assumes an  in-source  build.
                            The BINARY_DIR option should not be specified if building in-source.

                     BUILD_ALWAYS <bool>
                            Enabling this option forces the build step to always be run. This can
                            be the easiest way to robustly ensure that the external project’s own
                            build  dependencies  are evaluated rather than relying on the default
                            success timestamp-based method. This option is  not  normally  needed
                            unless  developers  are  expected  to  modify  something the external
                            project’s build depends on in a way that is not  detectable  via  the
                            step  target dependencies (e.g. SOURCE_DIR is used without a download
                            method and developers might modify the sources in SOURCE_DIR).

                     BUILD_BYPRODUCTS <file>...
                            Specifies files that will be generated by the build command but which
                            might or might not have their modification time updated by subsequent
                            builds. These ultimately get passed  through  as  BYPRODUCTS  to  the
                            build step’s own underlying call to add_custom_command().

              Install Step Options:
                     If  the  configure step assumed the external project uses CMake as its build
                     system, the install step will also. Otherwise, the install step will  assume
                     a  Makefile-based  build  and  simply  run make install as the default build
                     step. This can be overridden with custom install commands if required.

                     INSTALL_COMMAND <cmd>...
                            The external project’s own install step is invoked  as  part  of  the
                            main  project’s  build. It is done after the external project’s build
                            step and may be before or after the external project’s test step (see
                            the TEST_BEFORE_INSTALL option below). The external project’s install
                            rules are not part  of  the  main  project’s  install  rules,  so  if
                            anything from the external project should be installed as part of the
                            main build,  these  need  to  be  specified  in  the  main  build  as
                            additional  install()  commands.  The default install step builds the
                            install target of the external project, but this  can  be  overridden
                            with  a  custom  command using this option (generator expressions are
                            supported). Passing an empty string as the <cmd>  makes  the  install
                            step do nothing.

              Test Step Options:
                     The  test  step  is  only  defined if at least one of the following TEST_...
                     options are provided.

                     TEST_COMMAND <cmd>...
                            Overrides  the  default  test  command  (generator  expressions   are
                            supported).  If this option is not given, the default behavior of the
                            test step is to build the external project’s own  test  target.  This
                            option  can  be specified with <cmd> as an empty string, which allows
                            the test step to still be defined, but it will  do  nothing.  Do  not
                            specify  any  of  the  other  TEST_...  options if providing an empty
                            string as the test command, but prefer to omit all  TEST_...  options
                            altogether if the test step target is not needed.

                     TEST_BEFORE_INSTALL <bool>
                            When  this  option  is enabled, the test step will be executed before
                            the install step. The default behavior is for the test  step  to  run
                            after the install step.

                     TEST_AFTER_INSTALL <bool>
                            This  option is mainly useful as a way to indicate that the test step
                            is desired but all default behavior is  sufficient.  Specifying  this
                            option with a boolean true value ensures the test step is defined and
                            that it comes after the install step. If both TEST_BEFORE_INSTALL and
                            TEST_AFTER_INSTALL are enabled, the latter is silently ignored.

                     TEST_EXCLUDE_FROM_MAIN <bool>
                            If  enabled,  the  main build’s default ALL target will not depend on
                            the test step. This can be a useful way of ensuring the test step  is
                            defined but only gets invoked when manually requested.

              Output Logging Options:
                     Each  of the following LOG_... options can be used to wrap the relevant step
                     in a script to capture its output to files. The log files will be created in
                     LOG_DIR  if supplied or otherwise the STAMP_DIR directory with step-specific
                     file names.

                     LOG_DOWNLOAD <bool>
                            When enabled, the output of the download step is logged to files.

                     LOG_UPDATE <bool>
                            When enabled, the output of the update step is logged to files.

                     LOG_PATCH <bool>
                            When enabled, the output of the patch step is logged to files.

                     LOG_CONFIGURE <bool>
                            When enabled, the output of the configure step is logged to files.

                     LOG_BUILD <bool>
                            When enabled, the output of the build step is logged to files.

                     LOG_INSTALL <bool>
                            When enabled, the output of the install step is logged to files.

                     LOG_TEST <bool>
                            When enabled, the output of the test step is logged to files.

                     LOG_MERGED_STDOUTERR <bool>
                            When enabled, stdout and stderr will be merged  for  any  step  whose
                            output is being logged to files.

                     LOG_OUTPUT_ON_FAILURE <bool>
                            This  option  only  has  an  effect  if  at  least  one  of the other
                            LOG_<step> options is enabled.  If an error occurs for a  step  which
                            has  logging  to  file enabled, that step’s output will be printed to
                            the console if LOG_OUTPUT_ON_FAILURE is set to true.  For cases where
                            a large amount of output is recorded, just the end of that output may
                            be printed to the console.

              Terminal Access Options:
                     Steps can be given direct access to the terminal in  some  cases.  Giving  a
                     step  access  to  the  terminal  may  allow  it to receive terminal input if
                     required, such as for authentication details not provided by other  options.
                     With  the  Ninja generator, these options place the steps in the console job
                     pool. Each step can be given access to the  terminal  individually  via  the
                     following options:

                     USES_TERMINAL_DOWNLOAD <bool>
                            Give the download step access to the terminal.

                     USES_TERMINAL_UPDATE <bool>
                            Give the update step access to the terminal.

                     USES_TERMINAL_CONFIGURE <bool>
                            Give the configure step access to the terminal.

                     USES_TERMINAL_BUILD <bool>
                            Give the build step access to the terminal.

                     USES_TERMINAL_INSTALL <bool>
                            Give the install step access to the terminal.

                     USES_TERMINAL_TEST <bool>
                            Give the test step access to the terminal.

              Target Options:

                     DEPENDS <targets>...
                            Specify  other  targets  on  which  the external project depends. The
                            other targets will be brought up to date before any of  the  external
                            project’s  steps  are  executed.  Because  the  external project uses
                            additional custom targets  internally  for  each  step,  the  DEPENDS
                            option is the most convenient way to ensure all of those steps depend
                            on  the  other   targets.    Simply   doing   add_dependencies(<name>
                            <targets>) will not make any of the steps dependent on <targets>.

                     EXCLUDE_FROM_ALL <bool>
                            When  enabled,  this  option  excludes  the external project from the
                            default ALL target of the main build.

                     STEP_TARGETS <step-target>...
                            Generate custom targets for the specified steps. This is required  if
                            the steps need to be triggered manually or if they need to be used as
                            dependencies of other targets. If this option is not  specified,  the
                            default  value  is taken from the EP_STEP_TARGETS directory property.
                            See ExternalProject_Add_Step() below for further  discussion  of  the
                            effects of this option.

                     INDEPENDENT_STEP_TARGETS <step-target>...
                            Generate  custom  targets  for  the specified steps and prevent these
                            targets from having the usual dependencies applied to them.  If  this
                            option  is  not  specified,  the  default  value  is  taken  from the
                            EP_INDEPENDENT_STEP_TARGETS directory property. This option is mostly
                            useful for allowing individual steps to be driven independently, such
                            as for a CDash setup where each step should be initiated and reported
                            individually    rather    than    as    one    whole    build.    See
                            ExternalProject_Add_Step()  below  for  further  discussion  of   the
                            effects of this option.

              Miscellaneous Options:

                     LIST_SEPARATOR <sep>
                            For  any  of the various ..._COMMAND options, replace ; with <sep> in
                            the specified command lines. This can be useful where list  variables
                            may  be given in commands where they should end up as space-separated
                            arguments (<sep> would be a single space  character  string  in  this
                            case).

                     COMMAND <cmd>...
                            Any  of  the  other  ..._COMMAND options can have additional commands
                            appended to them by following them with as many COMMAND  ...  options
                            as needed (generator expressions are supported). For example:

                               ExternalProject_Add(example
                                 ... # Download options, etc.
                                 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
                                 COMMAND       ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
                                 COMMAND       ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
                               )

              It  should  also  be  noted  that  each  build  step  is  created  via  a  call  to
              ExternalProject_Add_Step(). See that  command’s  documentation  for  the  automatic
              substitutions that are supported for some options.

   Obtaining Project Properties
       ExternalProject_Get_Property
              The  ExternalProject_Get_Property()  function  retrieves  external  project  target
              properties:

                 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])

              The function stores property values in variables of the same name.  Property  names
              correspond  to  the  keyword argument names of ExternalProject_Add().  For example,
              the source directory might be retrieved like so:

                 ExternalProject_Get_property(myExtProj SOURCE_DIR)
                 message("Source dir of myExtProj = ${SOURCE_DIR}")

   Explicit Step Management
       The ExternalProject_Add() function on its own is often  sufficient  for  incorporating  an
       external  project  into  the  main  build.  Certain  scenarios  require additional work to
       implement desired behavior, such as adding in a custom step or making steps  available  as
       manually         triggerable        targets.        The        ExternalProject_Add_Step(),
       ExternalProject_Add_StepTargets()   and   ExternalProject_Add_StepDependencies   functions
       provide the lower level control needed to implement such step-level capabilities.

       ExternalProject_Add_Step
              The  ExternalProject_Add_Step() function specifies an additional custom step for an
              external project defined by an earlier call to ExternalProject_Add():

                 ExternalProject_Add_Step(<name> <step> [<option>...])

              <name>  is  the   same   as   the   name   passed   to   the   original   call   to
              ExternalProject_Add().  The  specified  <step>  must  not be one of the pre-defined
              steps (mkdir, download, update, skip-update, patch, configure,  build,  install  or
              test). The supported options are:

              COMMAND <cmd>...
                     The  command  line to be executed by this custom step (generator expressions
                     are supported). This option  can  be  repeated  multiple  times  to  specify
                     multiple commands to be executed in order.

              COMMENT "<text>..."
                     Text to be printed when the custom step executes.

              DEPENDEES <step>...
                     Other steps (custom or pre-defined) on which this step depends.

              DEPENDERS <step>...
                     Other steps (custom or pre-defined) that depend on this new custom step.

              DEPENDS <file>...
                     Files on which this custom step depends.

              BYPRODUCTS <file>...
                     Files  that  will  be generated by this custom step but which might or might
                     not have their modification time updated by subsequent builds. This list  of
                     files  will  ultimately  be  passed  through as the BYPRODUCTS option to the
                     add_custom_command() used to implement the custom step internally.

              ALWAYS <bool>
                     When enabled, this option specifies that the custom step  should  always  be
                     run (i.e. that it is always considered out of date).

              EXCLUDE_FROM_MAIN <bool>
                     When  enabled, this option specifies that the external project’s main target
                     does not depend on the custom step.

              WORKING_DIRECTORY <dir>
                     Specifies the working directory to set  before  running  the  custom  step’s
                     command. If this option is not specified, the directory will be the value of
                     the CMAKE_CURRENT_BINARY_DIR at the point  where  ExternalProject_Add_Step()
                     was called.

              LOG <bool>
                     If  set, this causes the output from the custom step to be captured to files
                     in the external project’s LOG_DIR if supplied or STAMP_DIR.

              USES_TERMINAL <bool>
                     If enabled, this gives the custom step direct  access  to  the  terminal  if
                     possible.

              The  command  line, comment, working directory and byproducts of every standard and
              custom step are processed to  replace  the  tokens  <SOURCE_DIR>,  <SOURCE_SUBDIR>,
              <BINARY_DIR>,  <INSTALL_DIR>  <TMP_DIR>,  <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with
              their  corresponding  property   values   defined   in   the   original   call   to
              ExternalProject_Add().

       ExternalProject_Add_StepTargets
              The  ExternalProject_Add_StepTargets()  function  generates  targets  for the steps
              listed. The name of each created target will be of the form <name>-<step>:

                 ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] <step1> [<step2>...])

              Creating a target for a step allows it to be used as a dependency of another target
              or  to be triggered manually. Having targets for specific steps also allows them to
              be driven independently of each other by specifying targets on build command lines.
              For  example, you may be submitting to a sub-project based dashboard where you want
              to drive the configure portion of the build, then submit to the dashboard, followed
              by the build portion, followed by tests. If you invoke a custom target that depends
              on a step halfway through the step dependency chain, then all  the  previous  steps
              will also run to ensure everything is up to date.

              If  the  NO_DEPENDS  option  is  specified,  the step target will not depend on the
              dependencies of the external project (i.e. on any dependencies of the <name> custom
              target  created  by  ExternalProject_Add()). This is usually safe for the download,
              update and patch steps, since they do not typically require that  the  dependencies
              are  updated  and  built.  Using NO_DEPENDS for any of the other pre-defined steps,
              however, may break parallel builds. Only use NO_DEPENDS where it  is  certain  that
              the  named  steps  genuinely  do  not have dependencies. For custom steps, consider
              whether or not the custom commands require the dependencies to be configured, built
              and installed.

              Internally,  ExternalProject_Add()  calls ExternalProject_Add_Step() to create each
              step.  If  any  STEP_TARGETS  or  INDEPENDENT_STEP_TARGETS  were  specified,   then
              ExternalProject_Add_StepTargets()      will      also      be      called     after
              ExternalProject_Add_Step(). INDEPENDENT_STEP_TARGETS  have  the  NO_DEPENDS  option
              set,  whereas  STEP_TARGETS  do  not.  Other  than  that, the two options result in
              ExternalProject_Add_StepTargets() being called in the same way. Even if a  step  is
              not mentioned in either of those two options, ExternalProject_Add_StepTargets() can
              still be called later to manually define a target for the step.

              The STEP_TARGETS and INDEPENDENT_STEP_TARGETS options for ExternalProject_Add() are
              generally  the  easiest  way  to  ensure  targets are created for specific steps of
              interest.  For  custom  steps,  ExternalProject_Add_StepTargets()  must  be  called
              explicitly  if a target should also be created for that custom step. An alternative
              to   these   two   options    is    to    populate    the    EP_STEP_TARGETS    and
              EP_INDEPENDENT_STEP_TARGETS  directory  properties.  These  act as defaults for the
              step target options and can save having to repeatedly specify the same set of  step
              targets when multiple external projects are being defined.

       ExternalProject_Add_StepDependencies
              The ExternalProject_Add_StepDependencies() function can be used to add dependencies
              to a step. The dependencies added must be targets CMake already knows about  (these
              can  be ordinary executable or library targets, custom targets or even step targets
              of another external project):

                 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])

              This function takes care to set both target and file level  dependencies  and  will
              ensure  that  parallel  builds  will  not  break.  It  should  be  used  instead of
              add_dependencies() whenever adding a  dependency  for  some  of  the  step  targets
              generated by the ExternalProject module.

   Examples
       The following example shows how to download and build a hypothetical project called FooBar
       from github:

          include(ExternalProject)
          ExternalProject_Add(foobar
            GIT_REPOSITORY    git@github.com:FooCo/FooBar.git
            GIT_TAG           origin/release/1.2.3
          )

       For the sake of the example, also define a second  hypothetical  external  project  called
       SecretSauce,  which  is downloaded from a web server. Two URLs are given to take advantage
       of a faster internal network if available, with a fallback to a  slower  external  server.
       The  project  is a typical Makefile project with no configure step, so some of the default
       commands are overridden. The build is only required to build the sauce target:

          find_program(MAKE_EXE NAMES gmake nmake make)
          ExternalProject_Add(secretsauce
            URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                              https://www.somecompany.com/downloads/sauce-2.7.zip
            URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
            CONFIGURE_COMMAND ""
            BUILD_COMMAND     ${MAKE_EXE} sauce
          )

       Suppose the build step of secretsauce requires that foobar must  already  be  built.  This
       could be enforced like so:

          ExternalProject_Add_StepDependencies(secretsauce build foobar)

       Another  alternative  would  be to create a custom target for foobar’s build step and make
       secretsauce depend on that rather than the whole foobar project. This  would  mean  foobar
       only  needs  to  be  built,  it  doesn’t  need  to  run  its  install or test steps before
       secretsauce can be built. The dependency can also be defined along  with  the  secretsauce
       project:

          ExternalProject_Add_StepTargets(foobar build)
          ExternalProject_Add(secretsauce
            URL               http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
                              https://www.somecompany.com/downloads/sauce-2.7.zip
            URL_HASH          MD5=d41d8cd98f00b204e9800998ecf8427e
            CONFIGURE_COMMAND ""
            BUILD_COMMAND     ${MAKE_EXE} sauce
            DEPENDS           foobar-build
          )

       Instead  of  calling  ExternalProject_Add_StepTargets(), the target could be defined along
       with the foobar project itself:

          ExternalProject_Add(foobar
            GIT_REPOSITORY git@github.com:FooCo/FooBar.git
            GIT_TAG        origin/release/1.2.3
            STEP_TARGETS   build
          )

       If many external projects should have the same set of step targets,  setting  a  directory
       property  may  be more convenient. The build step target could be created automatically by
       setting the EP_STEP_TARGETS directory property before creating the external projects  with
       ExternalProject_Add():

          set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)

       Lastly,  suppose  that  secretsauce  provides a script called makedoc which can be used to
       generate its own documentation.  Further  suppose  that  the  script  expects  the  output
       directory  to  be  provided  as  the  only  parameter  and  that it should be run from the
       secretsauce source directory. A custom step and a custom target to trigger the script  can
       be defined like so:

          ExternalProject_Add_Step(secretsauce docs
            COMMAND           <SOURCE_DIR>/makedoc <BINARY_DIR>
            WORKING_DIRECTORY <SOURCE_DIR>
            COMMENT           "Building secretsauce docs"
            ALWAYS            TRUE
            EXCLUDE_FROM_MAIN TRUE
          )
          ExternalProject_Add_StepTargets(secretsauce docs)

       The custom step could then be triggered from the main build like so:

          cmake --build . --target secretsauce-docs

   CMakeParseArguments
       Parse arguments given to a macro or a function.

       cmake_parse_arguments()  is  intended  to  be  used in macros or functions for parsing the
       arguments given to that macro or function.  It processes the arguments and defines  a  set
       of variables which hold the values of the respective options.

          cmake_parse_arguments(<prefix>
                                <options>
                                <one_value_keywords>
                                <multi_value_keywords>
                                [CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY|CMAKE_PARSE_ARGUMENTS_KEEP_EMPTY]
                                args...
                                )

       The <options> argument contains all options for the respective macro, i.e.  keywords which
       can be used when calling the macro without any value following, like  e.g.   the  OPTIONAL
       keyword of the install() command.

       The  <one_value_keywords> argument contains all keywords for this macro which are followed
       by one value, like e.g.  DESTINATION keyword of the install() command.

       The <multi_value_keywords> argument contains all keywords for  this  macro  which  can  be
       followed by more than one value, like e.g.  the TARGETS or FILES keywords of the install()
       command.

       When done, cmake_parse_arguments() will have defined for each of the  keywords  listed  in
       <options>,  <one_value_keywords>  and  <multi_value_keywords>  a  variable composed of the
       given <prefix> followed by “_” and the name of the respective  keyword.   These  variables
       will  then  hold  the respective value from the argument list.  For the <options> keywords
       this will be TRUE or FALSE.

       All remaining arguments are collected in a variable <prefix>_UNPARSED_ARGUMENTS, this  can
       be checked afterwards to see whether your macro was called with unrecognized parameters.

       The       cmake       CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY       (old      behaviour)      and
       CMAKE_PARSE_ARGUMENTS_KEEP_EMPTY options decide how empty arguments should be handled.  If
       none     of     these    options    is    set,    for    backwards    compatibility,    if
       CMAKE_MINIMUM_REQUIRED_VERSION < 3.0.0, the default behaviour is to skip empty  arguments,
       otherwise     the     default     behaviour     is     to    keep    them.    Using    the
       CMAKE_PARSE_ARGUMENTS_DEFAULT_SKIP_EMPTY variable the user can explicitly set the  default
       behaviour in current scope.

       As  an  example  here  a  my_install()  macro,  which  takes similar arguments as the real
       install() command:

          function(MY_INSTALL)
            set(options OPTIONAL FAST)
            set(oneValueArgs DESTINATION RENAME)
            set(multiValueArgs TARGETS CONFIGURATIONS)
            cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}" )
            ...

       Assume my_install() has been called like this:

          my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)

       After the cmake_parse_arguments() call the macro will have set the following variables:

          MY_INSTALL_OPTIONAL = TRUE
          MY_INSTALL_FAST = FALSE (this option was not used when calling my_install()
          MY_INSTALL_DESTINATION = "bin"
          MY_INSTALL_RENAME = "" (was not used)
          MY_INSTALL_TARGETS = "foo;bar"
          MY_INSTALL_CONFIGURATIONS = "" (was not used)
          MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (no value expected after "OPTIONAL"

       You can then continue and process these variables.

       Keywords terminate lists of values, e.g.  if directly after  a  one_value_keyword  another
       recognized  keyword follows, this is interpreted as the beginning of the new option.  E.g.
       my_install(TARGETS foo DESTINATION OPTIONAL) would result in MY_INSTALL_DESTINATION set to
       “OPTIONAL”, but MY_INSTALL_DESTINATION would be empty and MY_INSTALL_OPTIONAL would be set
       to TRUE therefore.

       If the “CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY” option  is  set,  cmake_parse_argumentswill  not
       consider empty arguments.  Therefore

          my_install(DESTINATION "" TARGETS foo "" bar)

       Will set

          MY_INSTALL_DESTINATION = (unset)
          MY_INSTALL_MULTI = "foo;bar"

       Using the “CMAKE_PARSE_ARGUMENTS_SKIP_EMPTY” option instead, will set

          MY_INSTALL_SINGLE = ""
          MY_INSTALL_MULTI = "foo;;bar"

       It is also important to note that:

          cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" "${ARGN}" )
          cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )

       Will  behave  differently,  because  in  the latter case empty arguments are not passed to
       cmake_parse_arguments.

DEPRECATED MODULES

       WARNING:
          These modules are deprecated and should not be used in new code.

   YCMDefaultDirs

COPYRIGHT

       Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT)