Building Cloe¶

Note

Before you follow any of the steps described below, please make sure that you complete all steps described on the Installation page. Please also read the sections on Understanding Cloe Packages first.

Suppose you intend to modify the content of one of Cloe’s multiple Conan packages. Below you can find some hints on how to build and test your package of interest without exporting it to the Conan local cache every time.

Build System¶

If you are developing Cloe itself, it is necessary to understand how the build system is composed. In essence, we are using GNU Make as a wrapper for Conan, and Conan as a wrapper for CMake. The following files are present in the root directory of every Cloe package (e.g. in plugins/basic/):

Makefile

Contains a set of targets that can be run in this directory. For most packages, the Makefile.package from the top-level directory is included to provide Make targets for the most common Conan commands. Refer to the output of make help in the respective package directory for a list of the available targets (here: make -C ./models help):

make: Entering directory '/home/docs/checkouts/readthedocs.org/user_builds/cloe/checkouts/v0.24.0/models'
Usage: make [34mtarget[0m

The following targets define common operations with this package in
editable (local in-source) and uneditable (in the Conan cache) modes.

Available targets:
  [34mhelp                 [0m show this help                                [2m[0m
  [34mstatus               [0m show status of package                        [2m[0m
  [34minfo                 [0m show detailed package info                    [2m[0m
  [34msmoketest-deps       [0m build smoketest dependencies for package      [2m[0m
  [34msmoketest            [0m run smoketests for package (requires built packages) [2m[0m

  [34mexport               [0m export recipe and sources                     [2m[conan-cache][0m
  [34mdownload             [0m download or create package                    [2m[conan-cache][0m
  [34mpackage              [0m create package with build policy              [2m[conan-cache][0m
  [34mpackage-all          [0m create package and dependencies               [2m[conan-cache][0m
  [34mpackage-outdated     [0m create package if outdated                    [2m[conan-cache][0m
  [34mlist                 [0m list installed package files                  [2m[conan-cache][0m
  [34mpurge                [0m remove package from cache                     [2m[conan-cache][0m

  [34meditable             [0m instruct Conan to use in-source build         [2m[0m
  [34muneditable           [0m instruct Conan to use local cache             [2m[0m

  [34mall                  [0m build the package                             [2m[in-source][0m
  [34mconfigure            [0m install dependencies and configure package    [2m[in-source][0m
  [34mtest                 [0m run CMake tests if they are available         [2m[in-source][0m
  [34mexport-pkg           [0m export build artifacts to Conan cache         [2m[in-source][0m
  [34mclean                [0m remove build directory                        [2m[in-source][0m

  Configuration:
    [32mLOCKFILE_SOURCE [0m=[2m [0m
    [32mSOURCE_DIR      [0m=[2m .[0m
    [32mBUILD_DIR       [0m=[2m build[0m
    [32mBUILD_POLICY    [0m=[2m outdated[0m
    [32mBUILD_TYPE      [0m=[2m [0m
    [32mCONAN_OPTIONS   [0m=[2m [0m

  Package information:
    [32mPACKAGE_NAME    [0m=[2m cloe-models[0m
    [32mPACKAGE_VERSION [0m=[2m 0.24.0-dirty[0m
    [32mPACKAGE_CHANNEL [0m=[2m cloe/develop[0m
    [32mPACKAGE_FQN     [0m=[2m cloe-models/0.24.0-dirty@cloe/develop[0m
    [32mPACKAGE_EDITABLE[0m=[2m not-editable[0m
    [32mPACKAGE_ID      [0m=[2m [0m
    [32mPACKAGE_DIR     [0m=[2m [0m
    [32mPACKAGE_DATE    [0m=[2m [0m
    [32mGIT_COMMIT_HASH [0m=[2m 1f4d608[0m

make: Leaving directory '/home/docs/checkouts/readthedocs.org/user_builds/cloe/checkouts/v0.24.0/models'

conanfile.py

Conan package recipe. To gain a thorough understanding of the Conan methods and tools used therein, the Conan CMake integration and Conan recipe reference documentation is probably a good starting point.

CMakeLists.txt

Contains cross-platform instructions for how to build, test, and install the package. The configuration is done via Conan. You may come across CMake Cloe-specific CMake functions such as cloe_add_plugin, which are defined in runtime/cmake/CloePluginSetup.cmake in the top-level directory. Conan-specific declarations are contained in conanbuildinfo.cmake, which will be generated after conan install is invoked.

In-Source Builds¶

Suppose you are making changes to the basic controller plugin and you would like to build your modified package in your local working directory. To do this, you may build Conan packages in editable mode. Try it out:

cd plugins/basic/
make editable

Verify that the cloe-plugin-basic package is currently in editable mode:

make status

Note

Positive-Example:

editable : cloe-plugin-basic/0.18.0-rc5-3-g53c80db@cloe/develop

Negative-Example:

ok       : cloe-plugin-basic/0.18.0-rc5-3-g53c80db@cloe/develop

Now, you can build the package binaries in your local working directory:

make clean all

Since the package is in editable mode, the binaries will be created in the ./build/ directory in your package sub-directory.

When you finalize work on your package, remember to remove the editable mode:

make uneditable

Verify the package status:

make status

If you execute the latter command from the top-level directory, you will see the status of all Cloe packages.