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