YCM-SUPERBUILD-EXAMPLE(7)

📦
version 0.13.0 · 2 versions
, in ubuntu noble, ubuntu questing

💖 YCM-SUPERBUILD-EXAMPLE(7) 💖

okay bestie, welcome to the manual page for ycm-superbuild-example — aka the YCM Superbuild Example. This is from the YCM crew, and it's literally just a big cozy show-and-tell of what a superbuild looks like. ✨

This page is split into two vibes: the first section is the user point of view (how you compile it and actually live with it), and the second section is the developer point of view (how the superbuild is built, like, behind the curtain 👀). Both matter, both slay.

🌈 SUPERBUILD EXAMPLE: USER POINT OF VIEW 🌈

So picture this: we're downloading an example project called example, and it has two subprojects inside it:

  • TemplatePkg — a package that contains the TemplateLib library 📦
  • TemplateExe — an executable that uses the TemplateLib library from the TemplatePkg package 🏃

Now the cute part: we are not downloading these subprojects one by one like some kind of peasant. The superbuild does all of that for us. All we gotta do is grab the superbuild sources — for example, cloning the git repo:

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

Next up we set the SUPERBUILD_ROOT environment variable to point at the folder git just made for us. Lowkey optional, but if you skip it you'll have to swap out $SUPERBUILD_ROOT for the actual paths every time you run the commands below, and that's giving tedious. 🙈

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

After the build, every single subproject gets installed inside the build/install folder. So to actually use it, you're gonna tweak 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/

Pro tip (the cozy kind): you can add these exports — and the export SUPERBUILD_ROOT one — to your ~/.bashrc file so you don't have to manually run them every single time. Your future self says thank you. 🫶

Okay now go to the directory where you downloaded the project example, and create a build directory:

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

This will download all the repositories of the individual packages and set up the build system. Two birds, one command, iconic. 🐦🐦

And now you compile the whole entire project. Type:

make

That's it. That's the vibe. 💅

🦋 SUPERBUILD EXAMPLE: DEVELOPER POINT OF VIEW 🦋

Now we're in the dev chair, bestie. Suppose you want to make a superbuild that contains these packages:

  • TemplatePkg — a package containing the TemplateLib library 📦
  • TemplateExe — an executable that uses the TemplateLib library from the TemplatePkg package 🏃

Create a folder that's gonna hold 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 the required CMake modules:

mkdir cmake

Now, dependency talk 👑 — if you want YCM as a soft dependency, you'll need to grab the files tools/YCMBootstrap.cmake and modules/IncludeUrl.cmake from the YCM sources. If you want it as a hard dependency, you don't have to add those files, but the user will have to install YCM before they can build the superbuild. Choose your fighter.

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)

And now you can compile the superbuild, periodt:

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 instead in build/install. For example, you can verify that the library from 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

look at those artifacts. absolutely ate. 🔥

⭐ CODE ⭐

The code of this superbuild example can be found here:

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

go get it, bestie 🧚

Copyright 2012-2021 Istituto Italiano di Tecnologia (IIT)

and that's the whole page, no cap. this was YCM's ycm-superbuild-example(7), version 0.13., dated Nov 05, 2023 — thanks for reading, ily, now go build something cute 🌸💜
📦 where this page comes from