ycm-superbuild(7)¶

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.

Windows¶

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¶

IDEs¶

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)

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

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)¶

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.

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.

Styles¶

CDash Integration¶

Non Interactive Builds¶

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

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 ( WALK-MAN Superbuild Repository)

• CoDyCo FP7 EU project (CoDyCo Superbuild Repository)