[Documentation] [TitleIndex] [WordIndex

API review

Proposer: Tully Foote

Present at review:


This is a review of a proposal to change the naming / migration strategy from rosbuild stacks and packages to something new with catkin.

See this post for some background on this proposal.


Variant and Meta-package can be synonymous, historically the word "variant" was used for large sets, whereas "meta-package" is a name used for small sets like rosbuild packages of one stack.

Rosbuild Approach

  1. Packages are atomic units of build. Packages are folders having a manifest.xml. Packages depend on packages.
  2. Stacks are atomic units of release. Stacks are folders having a stack.xml. Stacks depend on stacks.
  3. Stack contain packages
  4. Unary stacks are packages themselves and do not contain packages REP 109



Catkin-fuerte Proposal

  1. Stacks are atomic units of build
  2. Stacks are also atomic units of release
  3. Stacks have a top-level CMakeLists.txt, a stack.xml and subfolders
  4. Migration transforms rosbuild stacks into catkin stacks, and rosbuild packages into catkin subfolders.

Catkin post-fuerte Proposal

  1. We will release packages individually.

  2. We will have “meta-packages” which are groups of packages that can be installed by named aliases easily, but these will simply be content free packaging decisions, not source controlled content that must agree with the package dependency. Meta-packages membership is to be managed centralized like variants on servers such as Willow Garage servers (as opposed to be managed decentralized by stack folders). Multiple servers can be used together as sources (for corporate user-groups). The variants will be kept in a file distro.yaml in a github project, so that requests for changes can be made as git pull requests,

  3. There will be one xml file per package (the manifest.xml) which will have all the relevant meta data, dependencies, and information such as plugin declarations and possibly interfaces in the future.

  4. Other than catkin-fuerte, there will be no restrictions of how many packages can live in the same repository subtree, to allow for easier migration from rosbuild stacks. Also catkin workspaces will thus not require a flat alyout of projects in the workspace folder anymore.

  5. Variants can have two data fields: description and url (both optional, description recommended)

  6. We will update the PackageHeader wiki macro to list all variants in which that the package is contained. We will create a VariantHeader wiki macro which lists all the packages in the variant, and what it extends.

  7. For migration purposes, we would create a variant for each stack, so that the wiki content on stacks can easily be converted into meta-information on meta-packages / variants.


  1. maintainers no longer need to maintain the dual redundant dependency trees as in rosbuild (stack dependencies having to mirror package dependencies), dependencies in meta-package are reduncancy-free.
  2. things the catkin-fuerte proposal did not offer:
    1. backward compatibility with the wiki
    2. backward compatibility with the package dependencies
    3. multiple packages per repo.
    4. faster build as we can parallelize the individual units (there was already a step in that direction but we now go further in granularity). [TK] please more details
    5. finer granularity for dependencies
  3. packages can easily be moved to what was called a “unary stack” or a different repo (just copy the folder, that’s it)
  4. packages will have their own version number:
    1. there is a direct upgrade path for providing versioned .so files (maybe that will be done in time for Groovy)
    2. finer granularity for releases
    3. version locking of packages (not through an artificial meta-unit) which enables us to release packages at the same time
  5. there is no more worrying about in which stack a package is released and what the neighboring packages bring in as dependencies.
  6. no more stack.yaml/main CMakeLists.txt to maintain
  7. the concept of stack/variant are merged and are still here for the user for a simple install
  8. ROS packages are conceptually the same as Linux packages.
  9. Indexing is easier (only one type of unit to index)
  10. Discovery is easier (all things in the same namespace are the same type)


  1. increase of the number of Linux (and soon Mac/Windows) packages to build and offer the user by an order of magnitude
  2. upgrade requires moving some info from the stack.xml to all the manifest.xml (version number, authors/maintainers) / distro.yaml
  3. we still need to adapt quite a few scripts: bloom, rosrelease, roscreate-pkg, ... (but most of those were not even adapted for the catkin-fuerte solution). E.g. people should be able to release several packages at once just like they can do now with a stack (maybe with an automatic version bump). Those will be discussed individually.

Question / concerns / comments

Enter your thoughts on the API and any questions / concerns you have here. Please sign your name. Anything you want to address in the API review should be marked down here before the start of the meeting.

Thibault Kruse

Also asked in the SIG, maybe respond there, I will update here.



Desired Meta-package Semantics

[JOQ] This is important for developing and maintaining reusable ROS components in a distributed, federated environment.

Fixing FHS Problems

[JOQ] The main issue is that the Linux Filesystem Hierarchy standard does not permit putting binary executables in the share tree. Instead of $PREFIX/share/PACKAGE_NAME, those files should go in $PREFIX/lib/PACKAGE_NAME.

Meeting agenda

To be filled out by proposer based on comments gathered during API review period


Package status change mark change manifest)

2021-07-17 12:30