.\" Man page generated from reStructuredText. . .TH "YCM-SUPERBUILD-EXAMPLE" "7" "Jan 15, 2021" "0.12." "YCM" .SH NAME ycm-superbuild-example \- YCM Superbuild Example . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .sp 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). .SH SUPERBUILD EXAMPLE: USER POINT OF VIEW .sp We show how you can download an example project called \fBexample\fP which contains two subprojects: .INDENT 0.0 .IP \(bu 2 \fI\%TemplatePkg\fP: a package containing the \fBTemplateLib\fP library .IP \(bu 2 \fI\%TemplateExe\fP: an executable that uses the \fBTemplateLib\fP library from the \fBTemplatePkg\fP package .UNINDENT .sp Notice that we will \fInot\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone git@github.com:robotology/superbuild\-example.git .ft P .fi .UNINDENT .UNINDENT .sp We will set the \fBSUPERBUILD_ROOT\fP 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 \fB$SUPERBUILD_ROOT\fP with the actual paths when you run the following commands. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C export SUPERBUILD_ROOT=/path/to/the/superbuild/folder .ft P .fi .UNINDENT .UNINDENT .sp After the build, all the subprojects will be installed inside the \fBbuild/install\fP folder, therefore in order to use use it you will have to adjust some environment variables: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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/ .ft P .fi .UNINDENT .UNINDENT .sp You can add these exports (and the \fBexport SUPERBUILD_ROOT\fP) to your \fB~/.bashrc\fP file if you don’t want to have to execute them manually every time. .sp Now go to the directory where you have downloaded the project \fBexample\fP, create a build directory .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir $SUPERBUILD_ROOT/build cd $SUPERBUILD_ROOT/build cmake .. .ft P .fi .UNINDENT .UNINDENT .sp This will download all the repositories of the individual packages and setup the build system. .sp Now you can compile the whole project, type: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make .ft P .fi .UNINDENT .UNINDENT .SH SUPERBUILD EXAMPLE: DEVELOPER POINT OF VIEW .sp Suppose you want to make a superbuild that contains the following packages: .INDENT 0.0 .IP \(bu 2 \fI\%TemplatePkg\fP: a package containing the \fBTemplateLib\fP library .IP \(bu 2 \fI\%TemplateExe\fP: an executable that uses the \fBTemplateLib\fP library from the \fBTemplatePkg\fP package .UNINDENT .sp Create a folder that will contain your superbuild. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir example\-superbuild cd example\-superbuild .ft P .fi .UNINDENT .UNINDENT .sp Create a \fBCMakeLists.txt\fP with this content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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) .ft P .fi .UNINDENT .UNINDENT .sp Create a \fBcmake\fP folder that will contain all required CMake modules .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir cmake .ft P .fi .UNINDENT .UNINDENT .sp If you want YCM as a soft dependency you will need to get the files \fBtools/YCMBootstrap.cmake\fP and \fBmodules/IncludeUrl.cmake\fP 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. .sp Create the files \fBcmake/BuildTemplatePkg.cmake\fP and \fBcmake/BuildTemplateExe.cmake\fP with the following content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # TemplatePkg include(YCMEPHelper) ycm_ep_helper(TemplatePkg TYPE GIT STYLE GITLAB_ROBOTOLOGY REPOSITORY walkman/template\-pkg.git TAG master COMPONENT superbuild) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # 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) .ft P .fi .UNINDENT .UNINDENT .sp Now you can compile the superbuild: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir build cd build cmake .. make .ft P .fi .UNINDENT .UNINDENT .sp This will download the subprojects \fBTemplatePkg\fP and \fBTemplateExe\fP by cloning their repositories. Sources will be in the directory \fBsuperbuild\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ cd .. $ ls superbuild TemplateExe TemplatePkg $ ls superbuild/TemplateExe/ AUTHORS CMakeLists.txt COPYING doc README src \&... .ft P .fi .UNINDENT .UNINDENT .sp Binaries for the two subprojects are insted in \fBbuild/install\fP\&. For example you can verify that the library form \fBTemplatePkg\fP and the executable in \fBTemplateExe\fP have been correctly compiled: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ 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 .ft P .fi .UNINDENT .UNINDENT .SH CODE .sp The code of this superbuild example can be found here: .INDENT 0.0 .INDENT 3.5 \fI\%git@github.com\fP:robotology/superbuild\-example.git .UNINDENT .UNINDENT .SH COPYRIGHT Copyright 2013-2019 Istituto Italiano di Tecnologia (IIT) .\" Generated by docutils manpage writer. .