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)