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

NAME

       ycm-superbuild - YCM Superbuild User Manual

YCM SUPERBUILD

       A YCM Superbuild is a CMake project whose only goal is to download and build several other
       projects.

       The superbuild will check if a package is available on the system, and, if it is  not,  it
       will download its source code build and install it.

       A YCM superbuild supports out of the box:

       • User mode

       • Developer mode

       • Demos

       • Automatic integration with CDash.

       • Automatic documentation generation using doxygen.

       • Generation of dependency graphs using dot.

       Depending  on  your  reason for using a YCM superbuild, you should skip to the appropriate
       section:

       • If you just want to build the YCM superbuild project with all the sub-projects and start
         using it, read the YCM Superbuild Manual for Basic Users.

       • If  you  want  to  download,  build and modify the source code of one or some of the YCM
         superbuild sub-projects, read YCM Superbuild Manual for Developers.

       • If you want to create a new superbuild  or  to  modify  an  existing  one,  or  you  are
         interested  in  the  internals  of  a  YCM  superbuild  read  YCM  Superbuild Manual for
         Maintainers.

YCM SUPERBUILD MANUAL FOR BASIC USERS

       A YCM superbuild can be built like any other CMake project.

   Linux
       Suppose <YOUR_PROJECT> is the directory in which you downloaded the superbuild project you
       want to build:

          cd <YOUR_PROJECT>

          mkdir build
          cd build
          cmake ..

       Now, if you run

          make

       the superbuild will download and install all the required projects that cannot be found on
       the system.

       After the build, all the subprojects will be installed  inside  the  ${YCM_EP_INSTALL_DIR}
       folder (by default ${CMAKE_BINARY_DIR}/install, i.e. build/install), therefore in order to
       use it you will have to adjust some environment variables

          export PATH=$PATH:${PROJECT_SOURCE_DIR}/build/install/bin/
          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${PROJECT_SOURCE_DIR}/build/install/lib/
          export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:${PROJECT_SOURCE_DIR}/build/install/

       You can add these  lines  (replacing  ${PROJECT_SOURCE_DIR}  with  the  folder  where  you
       downloaded  your project) to your ~/.bashrc file if you don’t want to have to execute them
       manually every time.

       In order to compile just one project (and all the projects on which this project  depends)
       you can just run instead

          make <project>

       In order to update the external projects, you will have to run

          make update-all

       or if you want to update just one project, you can run

          make <project>-update

       After updating some project, you should then rebuild.

          make

   OS X
       On OS X you have the option to generate a GNU Makefile or an Xcode project.  If you choose
       to use the Makefile then you can follow the same steps of the  Linux  installation  guide.
       Only the environmental variables change, as explained later.

       If you choose to generate the Xcode project you have to follow the following steps:

          mkdir build
          cd build
          cmake .. -G Xcode

       Now, if you run

          xcodebuild

       the superbuild will download and install all the required projects that cannot be found on
       the system.  The above command builds the project with the default configuration of Xcode.
       You  can  also  open the project into the Xcode IDE and build it from there, or explicitly
       specify the configuration at command line:

          #Debug
          xcodebuild -configuration Debug
          #Release
          xcodebuild -configuration Release

       After the build, all the subprojects will be installed  inside  the  ${YCM_EP_INSTALL_DIR}
       folder (by default ${CMAKE_BINARY_DIR}/install, i.e. build/install), therefore in order to
       use it you will have to adjust some environment variables

          export PATH=$PATH:${PROJECT_SOURCE_DIR}/build/install/bin/
          export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:${PROJECT_SOURCE_DIR}/build/install/lib/
          export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:${PROJECT_SOURCE_DIR}/build/install/

       You can add these  lines  (replacing  ${PROJECT_SOURCE_DIR}  with  the  folder  where  you
       downloaded  your  project)  to your ~/.bashrc file (or the correct file for your shell) if
       you don’t want to have to execute them manually every time.

       In order to compile just one project (and all the projects on which this project  depends)
       you can just run instead

          xcodebuild -target <project>

       In order to update the external projects, you will have to run

          xcodebuild -target ALL_UPDATE

       or if you want to update just one project, you can run

          xcodebuild -target <project>-update

       After updating some project, you should then rebuild.

          xcodebuild

       If you don’t remember the name of the targets you can type

          xcodebuild -list

       for a list of the targets in the project.

   Todo
       Add Xcode screenshot and instructions for using the GUI

   Windows
   Todo
       Add Windows documentation

YCM SUPERBUILD MANUAL FOR DEVELOPERS

       A  developer  is someone that does not want just to build the superbuild but also wants to
       modify some of the subprojects.

       NOTE:
          If a package should be built with a YCM Superbuild, this should not be available on the
          system. If it is, then the source code will not even be downloaded.  In order to keep 2
          different versions, the superbuild should ignore the system version, and  download  and
          build  it  instead.   This  can be done by setting the USE_SYSTEM_<PACKAGE> variable to
          FALSE or by setting the YCM_DISABLE_SYSTEM_PACKAGES variable to TRUE to do it  for  all
          the packages of the superbuild.

       This  can  be  done  by  running ccmake or cmake-gui and changing the value, or by running
       adding -DUSE_SYSTEM_<PACKAGE>:BOOL=FALSE to the cmake command line.

   Directories
       The superbuild will download each subproject inside the build tree of the project  in  the
       folder:

          ${PROJECT_SOURCE_DIR}/<component>/<project name>

       The  <component>  is  assigned  by  the  maintainer, and has the main purpose to split the
       source code into conceptual units

       The <project name> should be the name that is used in find_package() calls  to  find  that
       package.

       Each project will be configured and built in the folder:

          ${PROJECT_BINARY_DIR}/<component>/<project name>

       ${PROJECT_BINARY_DIR}  is  the  folder  where you are building the YCM superbuild project,
       usually ${PROJECT_SOURCE_DIR}/build/

       The superbuild will run the configure, build and install step for each project.

       Each   project    will    be    installed    in    ${YCM_EP_INSTALL_DIR}    (by    default
       ${PROJECT_BINARY_DIR}/install).   You  should  not change the YCM_EP_INSTALL_DIR variable,
       unless you wish to build the superbuild only once, and discard  the  build  directory.  In
       this case you should change this variable to the final destination of the build since, for
       many projects, the build is not relocatable.  Please also note that, if you change it to a
       folder  that  is  not  writable  by  current user, you will have to run the whole build as
       superuser.

   Developer Mode
       A developer usually works on a limited set of projects.

       For  each  the  superproject  that  the  developer  will  modify,  he  should  enable  the
       YCM_EP_DEVEL_MODE_<PROJECT> CMake cached variable.

       This  can  be  done  by  running ccmake or cmake-gui and changing the value, or by running
       adding -DYCM_EP_DEVEL_MODE_<PACKAGE>:BOOL=FALSE to the cmake command line.

       Note that the update target will be disabled for projects in  YCM_EP_DEVEL_MODE_<PROJECT>,
       and  they  will not be updated unless the user updates them manually.  An automatic update
       in a modified project, would require a manual intervention anyway.  Also when working with
       branches  the  update  performed  by  ExternalProject  could  switch  branch or checkout a
       specific tag or commit, and, even though no work should be lost, the user might  not  know
       how  to  recover  it.  For this reason the update target is disabled for the projects that
       the user will modify, and it  is  enabled  only  if  the  YCM_EP_EXPERT_MODE  variable  is
       enabled.

   Expert Mode
       The  YCM_EP_EXPERT_MODE  variable  will  set  the YCM superbuild in “expert mode”. This is
       disabled by default.  This means that all the projects that are in “developer  mode”  will
       have  all  the targets enabled (including the update step) and that the update and similar
       targets will keep these targets as well.

   Targets
   Global Targets
       These targets influence all the whole YCM superbuild. In  brackets  is  the  name  of  the
       target on IDEs like Visual Studio and Xcode.

   all (ALL)
       Build all sub-projects.

   test (TEST)
       Run tests for all sub-projects (only if tests are enabled, see enable_testing().

   update-all (ALL_UPDATE)
       Update all sub-projects, except for those in YCM_EP_DEVEL_MODE_<PROJECT>.

   fetch-all (ALL_FETCH)
       Runs  git  fetch for all the sub-projects in YCM_EP_DEVEL_MODE_<PROJECT> (git sub-projects
       only).

   status-all (ALL_STATUS)
       Prints the status (using  the  appropriate  SCM  command)  for  all  the  sub-projects  in
       YCM_EP_DEVEL_MODE_<PROJECT>.

   clean-all (ALL_CLEAN)
   Todo
       Missing docs

   print-directories-all (ALL_PRINT_DIRECTORIES)
       Prints    the    source   and   binary   directories   for   all   the   sub-projects   in
       YCM_EP_DEVEL_MODE_<PROJECT>.

   install
   Todo
       Add a proper installation.

       WARNING:
          YCM does not create an install target (yet). In some cases, i.e. if  you  include  some
          CMake module that installs some file, you might find an install target, but it will not
          install the whole superbuild, but just these files.

          One known module that adds the install target is  catkinConfig.cmake  distributed  with
          ROS Hydro, and usually included by running find_package(catkin).

   Component Targets
       These targets influence a specific COMPONENT, for example external

   Todo
       Component targets.

   <COMPONENT>
   Todo
       Missing docs

   <COMPONENT>-update
   Todo
       Missing docs

   Project Targets - Common
       These targets are always available for all the sub-projects:

   <PROJECT>
       Builds a sub-project and all its dependees.

   <PROJECT>-test
       Builds  a  sub-project  and  all  its  dependees and executes its tests (only if tests are
       enabled, see enable_testing().

   Project Targets - Basic Mode
       These  targets   are   available   only   for   the   sub-projects   that   are   not   in
       YCM_EP_DEVEL_MODE_<PROJECT>.

   <PROJECT>-update
       Update a sub-project.

   Project Targets - Development Mode
       These    targets    are    available    only    for   the   sub-projects   that   are   in
       YCM_EP_DEVEL_MODE_<PROJECT>.

   <PROJECT>-configure
       Configure a sub-project.

   <PROJECT>-fetch
       Runs git fetch a sub-project (git sub-projects only).

   <PROJECT>-status
       Prints the status (using the appropriate SCM command) for a sub-project.

   <PROJECT>-clean
   Todo
       Missing docs

   <PROJECT>-edit-cache
       Edit CMake cache for a sub-project (CMake sub-projects only).

   <PROJECT>-open
       Open the project for editing.

       NOTE:
          MSVC and Xcode only

   <PROJECT>-print-directories
       Prints the source and binary directories for a sub-project

   <PROJECT>-dependees
       Builds all the sub-projects required by this sub-project.

   <PROJECT>-dependees-update
       Update all the sub-projects that are  not  in  YCM_EP_DEVEL_MODE_<PROJECT>  and  that  are
       required by this sub-project.

   <PROJECT>-dependers
       Builds all the sub-projects that require this sub-project.

   <PROJECT>-dependers-update
       Update  all  the sub-projects that are not in YCM_EP_DEVEL_MODE_<PROJECT> and that require
       this sub-project.

   Project Targets - Special Components
       Projects in some special components behave in a different way

   documentation Projects
       These projects usually don’t have build, configure, or  install  step.   The  only  target
       enabled is the <PROJECT> target.

       The update step for these projects is always performed with the <PROJECT> target.

       If one of the steps is added manually, this step is performed with the <PROJECT> target.

       These projects are not added to the global targets.

   examples Projects
       These projects are not added to the global targets.

   templates Projects
       These projects are not added to the global targets.

   IDEs
   Todo
       Add documentation about how to use the most common IDEs with YCM.

              • Xcode

              • QtCreator

              • MSVC

              • Maybe more.

YCM SUPERBUILD MANUAL FOR MAINTAINERS

       A YCM superbuild is based on the ExternalProject CMake module.  The ExternalProject module
       included in YCM is basically the same, but includes a few extra  patches  to  improve  its
       functionalities,  and  to  fix  a  few  issues  in  order to be able to work with the code
       downloaded by ExternalProject, without risking to lose work.  The reason why these patches
       are applied here, is because they can be tested and used, before submitting them upstream.
       In the future, the goal is to merge all the required features in the module upstream.

       The CMake modified modules are not included automatically when you include YCM.  In  order
       use  the version supplied with YCM, you have to set the YCM_USE_CMAKE_PROPOSED variable to
       ON before searching for YCM using find_package(YCM) or bootstrapping it.

          # Enable cmake-proposed modules
          set(YCM_USE_CMAKE_PROPOSED ON)

          # Now bootstrap YCM
          include(YCMBootstrap)

       Since the superbuild will download all the  external  project  from  the  net,  using  the
       bootstrap  will consider YCM like any other external project, but with the difference that
       it is downloaded and built at configure time, instead of at compile time. This allows  you
       to use all YCM modules right after the bootstrap.

       The other important modules for making a superbuild

          • YCMEPHelper,  a  helper  for ExternalProject that does some extra setup, and add some
            extra targets

          • FindOrBuildPackage,   that  ensures  that  a  package  is  available  and  eventually
            downloads and builds it.

       SEE ALSO:
          Superbuild Helper Modules

       NOTE:
          A  superbuild  usually  does not contain source code, but just the CMake files to build
          all the subprojects. It can build code, but the target dependencies should  be  handled
          properly.

       WARNING:
          CMake  modules  installed  by  packages  built  by the superbuild will not be available
          during the configure phase of the superbuild, therefore you cannot include them in  the
          CMakeLists.txt  file,  and  you  cannot  use  the functions and macros that these files
          declare. This is often a good reason for not including source code in the superbuild.

   Build Modules
       Each subproject “Project” to be built, should have a BuildProject.cmake file in one of the
       folders  in CMAKE_MODULE_PATH.  YCM has a few of them, see Build Package Modules, that are
       found automatically after YCM was found by find_package(YCM) or bootstrapped.  You can add
       more  Build  modules  in  your  superbuild, by putting them in some folder and adding that
       folder to the CMAKE_MODULE_PATH variable. You can also use this variable to replace one of
       the Build files included in YCM, but in this case your folder must be in CMAKE_MODULE_PATH
       before you search for YCM:

          # Build modules are in cmake folder
          list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

          # Now search (or bootstrap) YCM
          find_package(YCM REQUIRED)
          # or
          # include(YCMBootstrap)

       Each build file should handle properly the dependencies required by the project that  will
       be  built.  By  managing the dependencies for each project, the superbuild can ensure that
       the dependencies are available when the build starts. This is  especially  important  when
       you run parallel builds (i.e. make -j8) because builds

       This  is  a  basic  example  for  a  project “Bar” that depends on project “Foo” that uses
       YCMEPHelper and FindOrBuildPackage to build the code.

          include(YCMEPHelper)
          include(FindOrBuildPackage)

          # Ensures that the superbuild knows about the Foo package
          find_or_build_package(Foo QUIET)

          ycm_ep_helper(Bar TYPE GIT
                            SYLE FOO_STYLE
                            REPOSITORY foo/bar.git
                            TAG master
                            DEPENDS Foo) # Explicitly declare that Bar depends on Foo

       The main CMakeLists.txt will then include

          include(FindOrBuildPackage)

          # Build the Bar package. Foo will be handled automatically
          # You don't need a "find_or_build_package(Foo)" call here if the Foo
          # package is not conceptually part of your superbuild
          find_or_build_package(Bar)

   Non CMake Projects
       Projects written with CMake can be included in  a  superbuild  in  a  few  minutes.  Other
       projects  using  for  example autotools or other build systems, can still be included, but
       they require some more effort to add them to the build system.

       In practice, the configure step is the one that usually requires to be modified.  You  can
       do  it  by  passing  the  CONFIGURE_COMMAND  argument  to the ycm_ep_helper() command.  An
       important thing that should be  configured  is  the  prefix  where  the  package  will  be
       installed,  otherwise  it will be installed on the system default (usually in /usr/local/)
       and that folder might not be writable by the user.

       The following strings (including the < and > characters) can  be  used  to  configure  the
       steps:

          <SOURCE_DIR>   # Source directory
          <BINARY_DIR>   # Binary directory
          <INSTALL_DIR>  # Install directory
          <TMP_DIR>      # Directory for temporary files.

       For example, for an automake project, the ycm_ep_helper() call could be something similar:

          ycm_ep_helper(Foo TYPE GIT
                            STYLE FOO_STYLE
                            REPOSITORY foo/foo.git
                            TAG v1.0
                            CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR>)

   Overriding Parameters
       Each  parameter  of  the ycm_ep_helper() function can be overridden using cmake variables,
       for example to overwrite the TAG tag for project FOO, and the COMPONENT  for  project  BAR
       you can just add somewhere, before the relative ycm_ep_helper() call:

          set(FOO_TAG v1.0)
          set(BAR_COMPONENT important)

       See  YCMEPHelper  module  documentation for other details about the parameters that can be
       modified with a variable.

   Specifying additional CMake arguments for all subprojects
       In some situations, it may be convenient to be able to  specify  some  additional  command
       line arguments that are passed during the cmake invocation of all CMake-based subprojects.
       This is possible thanks to the YCM_EP_ADDITIONAL_CMAKE_ARGS CMake cache variable, that can
       be set as command line argument passed to the superbuild cmake invocation:

       or as a CMake variable set in the CMake code:

          set(YCM_EP_ADDITIONAL_CMAKE_ARGS "-DBOOL_OPTION:BOOL=ON -DLIST_VARIABLE:STRING=foo;bar")

       Note    that    in   the   latter   case,   you   need   to   make   sure   to   set   the
       YCM_EP_ADDITIONAL_CMAKE_ARGS before the first inclusion of the YCMEPHelper module in  your
       project.

   Components
       YCMEPHelper  assigns  to  each sub-project a COMPONENT (the default component is external.
       This is useful to separate your project in conceptual units.

       You can add any other component for your superbuild.

       This will influence the superbuild in some ways:

       1. The superbuild will create targets for each component.

          SEE ALSO:
             Component Targets for details.

       2. The component will influence the folders where the project is downloaded and built.

          SEE ALSO:
             Directories for details.

       3. Some special components are handled in a slightly different way:

             • external component is for packages that the  users  of  the  superbuild  will  not
               modify.

             • documentation  component  contains  only  documentation  and  is not necessary for
               building the superbuild.

             • example and template components are not necessary for building the superbuild.

          SEE ALSO:
             Project Targets - Special Components for details.

   Changing TAG (git repository only)
   Todo
       Perhaps this should be in the YCMEPHelper module documentation?

       ycm_ep_helper() allows you to set a TAG for git repositories.  This TAG  can  be  any  ref
       known by the git repository, i.e. a commit hash, a tag or a branch.

       ExternalProject  handles this tag in different ways depending if this is a head or a fixed
       commit.

       In the first case, git will perform a checkout of the tag the first time, and then it will
       perform a rebase when the update target is executed.

       This  is  the  recommended  mode  to  use when you need to work on one project inside your
       superbuild.

   Todo
       Changing branch issues

       In the latter case, git always performs a checkout of the  specific  commit,  leaving  the
       user in ‘detached HEAD’ state.

       This  is  the recommended mode to use for projects that are just dependencies for projects
       inside your superbuild, and that developers will not modify.

   Todo
       Changing tag issues

   Styles
   Todo
       Perhaps this should be in the YCMEPHelper module documentation?

   Todo
       Missing docs

   CDash Integration
   Todo
       Unit tests are not well integrated yet, see YCM issue #17

   Non Interactive Builds
       For build machines the NON_INTERACTIVE_BUILD variable should be set to true.

       NOTE:
          This should either be set by running cmake -DNON_INTERACTIVE_BUILD:BOOL=TRUE, or  using
          an initial cache file and running cmake -C <file>

   Install Step
       An  important thing to notice is that, if the subprojects are written in a proper way, the
       user  will   have   all   the   files   that   he   needs   to   use   the   projects   in
       ${PROJECT_BINARY_DIR}/install

       This  means  that  it  is  quite important for your subproject to install the files in the
       install step, and that all the files are installed inside the install  prefix.  For  CMake
       projects this usually means that the DESTINATION argument for the install() command should
       be a relative path instead of absoulute

   Maintainer Mode
       If the YCM_EP_MAINTAINER_MODE CMake variable is enabled,  all  the  targets  for  all  the
       projects will be enabled, including the update step.

       This is an useful variable for maintainers, but is not recommended for developers.

   Examples
       This is a list of known projects using YCM.

       • WALK-MAN FP7 EU project ([image: lock] [image]
          WALK-MAN Superbuild Repository)

       • CoDyCo FP7 EU project (CoDyCo Superbuild Repository)

COPYRIGHT

       Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT)