Skip to content

Latest commit

 

History

History
105 lines (86 loc) · 9.67 KB

developers-faqs.md

File metadata and controls

105 lines (86 loc) · 9.67 KB
Raw

Developers' Frequently Asked Questions (FAQs)

How to add a new package

  • Decide in which "profile" of the superbuild the project should be installed
  • If the software package is available on GitHub and can be built with CMake (the most common case), just add a Build<package>.cmake in the cmake directory of the superbuild. You can take inspiration from the Build***.cmake files already available, but if you want to add a package that is called , that dependens on CMake packages <pkgA>, <pkgB> and <pkgC> and is available at https://github.com/robotology/<package-repo-name> and that is part of profile , you can add it based on this template if it is a C++/CMake package:
# Copyright (C) Fondazione Istituto Italiano di Tecnologia
# CopyPolicy: Released under the terms of the LGPLv2.1 or later, see LGPL.TXT

include(YCMEPHelper)
include(FindOrBuildPackage)

find_or_build_package(<pkgA> QUIET)
find_or_build_package(<pkgB> QUIET)
find_or_build_package(<pkgC> QUIET)

ycm_ep_helper(<package> TYPE GIT
              STYLE GITHUB
              REPOSITORY robotology/<package-repo-name>.git
              TAG master
              COMPONENT <profile>
              FOLDER src
              DEPENDS <pkgA>
                      <pkgB>
                      <pkgC>)

or this one if it is a Pure Python package:

# Copyright (C) Fondazione Istituto Italiano di Tecnologia
# CopyPolicy: Released under the terms of the LGPLv2.1 or later, see LGPL.TXT

include(RobSupPurePythonYCMEPHelper)

find_or_build_package(<pkgA> QUIET)
find_or_build_package(<pkgB> QUIET)
find_or_build_package(<pkgC> QUIET)

ycm_ep_helper(<package>
              REPOSITORY robotology/<package-repo-name>.git
              TAG master
              COMPONENT <profile>
              FOLDER src
              DEPENDS <pkgA>
                      <pkgB>
                      <pkgC>)

How to add a new profile

  • Decide a name for the profile and decide who will be the mantainer of the profile
  • Add the profile name in doc/cmake-options.md#profile-cmake-options and the mantainer name in https://github.com/robotology/robotology-superbuild#mantainers .
  • Add the ROBOTOLOGY_ENABLE_<profile> CMake option in the file cmake/RobotologySuperbuildOptions.cmake
  • Add any new package required by the profile to the superbuild, following the instructions in "How to add a new package" FAQ
  • Add a part of code with a find_or_build_package(<pkg1_profile>) in the cmake/RobotologySuperbuildLogic.cmake file, guarded by the if(ROBOTOLOGY_ENABLE_<profile>) clause, something like:
if(ROBOTOLOGY_ENABLE_<profile>)
  find_or_build_package(<pkg1_profile>)
  find_or_build_package(<pkg2_profile>)
endif()

How to bump the version of a subproject

  • The superbuild contains a releases/latest.releases.yaml file that is meant to contain the latest release of each subproject of the superbuild.
  • This file is automatically updated by the update-latest-releases.yml GitHub action, that periodically checks the default branches of the repo (the one used if ROBOTOLOGY_PROJECT_TAGS is set to Stable) and extract the latest tag done on that branch. The action can also be run manually using the workflow_dispatch event.
  • If you have any project for which you want to manually manage the release used in the releases/latest.releases.yaml file, you can disable the automatical update of the tags by adding its CMake name in the projects_to_skip array in the scripts/robotologyUpdateLatestReleases.sh script.

How to do a new release

To do a new release, just run via workflow_dispatch the release GitHub Actions workflow on the master branch.

This action will automatically perform the following steps:

  • It copies the releases/latest.releases.yaml file in releases/yyyy.mm.yaml file, containing the version of package contained in the new release.
  • It creates a releases/yyyy.mm branch from master
  • On the branch releases/yyyy.mm, it modifies the default value of the ROBOTOLOGY_PROJECT_TAGS CMake option to be Custom and of the ROBOTOLOGY_PROJECT_TAGS_CUSTOM_FILE to the point to the yyyy.mm.yaml file.
  • It creates a new tag and release vyyyy.mm on the releases/yyyy.mm branch

How to ensure that binary packages are correctly generated for a new package

  • If the package is already available in conda-forge, then no binary should be created and the conda-forge version should be used. This is done by setting in the Build<pkg>.cmake file the <pkg>_CONDA_PKG_NAME variable to the name of the package in conda-forge, and setting to ON the <pkg>_CONDA_PKG_CONDA_FORGE_OVERRIDE variable. For an example of such package, see Buildosqp.cmake.
  • If instead the package is not part of conda-forge, then it is appropriate to generate a binary package as part of the robotology channel, providing the following CMake options in the Build<pkg>.cmake file:
Variable Meaning Default Value
<pkg>_CONDA_PKG_NAME The name that will be used for the conda package name. The convention is to use lowercase names separated by dashes. The name of the github repo of the package.
<pkg>_CONDA_DEPENDENCIES The list of conda-forge dependencies required by this package. Note that dependencies managed by the robotology-superbuild should not be listed, as those are handled automatically. The default value is empty.
<pkg>_CONDA_RUN_DEPENDENCIES_EXPLICIT The list of conda-forge run dependencies required by this package. Note that most C++ dependencies are not required as they have run_exports to automatically handle this, but this may be required for Python dependencies. The default value is empty.
<pkg>_CONDA_BUILD_DEPENDENCIES_EXPLICIT The list of conda-forge build dependencies required by this package. Note that it is not necessary to explicitly add C/C++ compilers, cmake, ninja, pkg-config and make, as they are added automatically.
<pkg>_CONDA_VERSION The version that will be used for the conda package, by default it is not set as the value from the tag will be extracted. The default value is to use the value of the tag, removing any occurence of the v letter.
<pkg>_CONDA_ENTRY_POINTS This option permits to specify explicitly the entry_points used by a pure_python package (see #1105). Empty.

For any doubt, double check the existing Build<pkg>.cmake files for inspiration.

  • If your package needs to set or modify some environment variables to work correctly, it should provide a pair of multisheller scripts named <condaPkgName>_activate.msh and <condaPkgName>_deactivate.msh in the conda/multisheller directory to describe how the environment should be modified. Refer to the existing scripts for more details.

How often are conda binary packages generated?