NAME

       ycm-superbuild-example - YCM Superbuild Example

       This  page  shows  an example of superbuild. The first section shows how you can compile and work with it
       (i.e. the point of view of a user), the second section shows how  the  superbuild  is  implemented  (i.e.
       point of view of a developer).

SUPERBUILD EXAMPLE: USER POINT OF VIEW

       We show how you can download an example project called example which contains two subprojects:

       • TemplatePkg: a package containing the TemplateLib library

       • TemplateExe: an executable that uses the TemplateLib library from the TemplatePkg package

       Notice  that we will not download these subprojects individually. The superbuild will do that for us, all
       we need to do is to get the superbuild sources, for example cloning the git repository:

          git clone git@github.com:robotology/superbuild-example.git

       We will set the SUPERBUILD_ROOT environment variable to the folder that was just created by git. This  is
       not necessary, but if you don’t do it you will have to replace the $SUPERBUILD_ROOT with the actual paths
       when you run the following commands.

          export SUPERBUILD_ROOT=/path/to/the/superbuild/folder

       After the build, all the subprojects will be installed inside  the  build/install  folder,  therefore  in
       order to use use it you will have to adjust some environment variables:

          export PATH=$PATH:$SUPERBUILD_ROOT/build/install/bin/
          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SUPERBUILD_ROOT/build/install/lib/
          export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:$SUPERBUILD_ROOT/build/install/

       You  can  add  these exports (and the export SUPERBUILD_ROOT) to your ~/.bashrc file if you don’t want to
       have to execute them manually every time.

       Now go to the directory where you have downloaded the project example, create a build directory

          mkdir $SUPERBUILD_ROOT/build
          cd $SUPERBUILD_ROOT/build
          cmake ..

       This will download all the repositories of the individual packages and setup the build system.

       Now you can compile the whole project, type:

          make

SUPERBUILD EXAMPLE: DEVELOPER POINT OF VIEW

       Suppose you want to make a superbuild that contains the following packages:

       • TemplatePkg: a package containing the TemplateLib library

       • TemplateExe: an executable that uses the TemplateLib library from the TemplatePkg package

       Create a folder that will contain your superbuild.

          mkdir example-superbuild
          cd example-superbuild

       Create a CMakeLists.txt with this content:

          cmake_minimum_required(VERSION 3.12)

          project(example)

          set(YCM_USE_CMAKE_PROPOSED ON) # Enables unmerged patches to CMake modules, this is required for the superbuild to work

          # makes available local cmake modules
          list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")

          # Choose whether you want YCM to be a soft or a hard dependency and uncomment
          # the appropriate line:
          include(YCMBootstrap) # This will make it a soft dependency
          # find_package(YCM 0.1 REQUIRED) # This will make it a hard dependency

          include(FindOrBuildPackage)
          include(YCMEPHelper)

          find_or_build_package(TemplatePkg)
          find_or_build_package(TemplateExe)

          feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

       Create a cmake folder that will contain all required CMake modules

          mkdir cmake

       If you want YCM as a soft dependency  you  will  need  to  get  the  files  tools/YCMBootstrap.cmake  and
       modules/IncludeUrl.cmake from the YCM sources. If you want to make it a hard dependency you don’t have to
       add these files, but the user will have to install YCM before he can build the superbuild.

       Create the  files   cmake/BuildTemplatePkg.cmake  and  cmake/BuildTemplateExe.cmake  with  the  following
       content:

          # TemplatePkg
          include(YCMEPHelper)

          ycm_ep_helper(TemplatePkg TYPE GIT
                                    STYLE GITLAB_ROBOTOLOGY
                                    REPOSITORY walkman/template-pkg.git
                                    TAG master
                                    COMPONENT superbuild)

          # TemplateExe
          include(YCMEPHelper)
          include(FindOrBuildPackage)

          find_or_build_package(TemplatePkg QUIET)

          ycm_ep_helper(TemplateExe TYPE GIT
                                    STYLE GITLAB_ROBOTOLOGY
                                    REPOSITORY walkman/template-exe.git
                                    TAG master
                                    COMPONENT superbuild
                                    DEPENDS TemplatePkg)

       Now you can compile the superbuild:

          mkdir build
          cd build
          cmake ..
          make

       This  will  download  the  subprojects TemplatePkg and TemplateExe by cloning their repositories. Sources
       will be in the directory superbuild:

          $ cd ..
          $ ls superbuild
          TemplateExe  TemplatePkg
          $ ls superbuild/TemplateExe/
          AUTHORS  CMakeLists.txt  COPYING  doc  README  src
          ...

       Binaries for the two subprojects are insted in build/install. For example you can verify that the library
       form TemplatePkg and the executable in TemplateExe have been correctly compiled:

          $ ls build/install/
          bin  include  lib
          $ ls build/install/lib
          cmake  libtemplate-lib.so  libtemplate-lib.so.0.0.1
          $ ls build/install/bin
          template-exe

CODE

       The code of this superbuild example can be found here:
          git@github.com:robotology/superbuild-example.git

COPYRIGHT

       Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT)