rubicks/florist repository overview

⁠florist

Release and package stuff from a ROS project.

⁠Q. What is this?

It's a couple of hacks scripts that automate the drudgery of blooming, building, and packaging (for debian) a given ROS project.

⁠Q. What's ROS?

ROS⁠ is the robot operating system. In the ROS world, every package is a little cmake⁠ project (with sundry other bits that are beyond this discussion). To distribute your ROS-flavored thing in a way that pleases the OSRF oligarchy, you need to release, build, and package it with abhorrent special ROS tools.

⁠Q. What tools?

bloom⁠ is the one that figures most prominently.

--- http://bloom.readthedocs.io⁠

Yes, it's designed to make package-building easier but falls far short of that lofty goal. It's finicky, slow, and actively hostile to package maintainers; more on that later.

At any rate, project bloom⁠ provides a bloom-release tool. bloom-release takes an "upstream" and produces a "release". You don't get any of this for free, mind you; there are strict constraints on what can be "bloomed" and doing it for a "fresh" package (one for which the corresponding -release repository does not yet exist) is a lot of preparatory work. The first time⁠ always hurts.

⁠Q. What's this "upstream"?

The thing holding the source code of interest; i.e., the ROS project you want released as a package --- or, more often, several packages. As of this writing, the bloom-release tool can support⁠ an "Upstream URI" in one of four forms:

Upstream VCS Type:
  svn
    URI is a svn repository
  git
    Upstream URI is a git repository
  hg
    Upstream URI is a hg repository
  tar
    Upstream URI is a tarball
  ['git']:

The default, git, works really well --- as long as you don't use git submodule⁠ and/or git lfs⁠. Because non-trivial software projects often rely on submodules and LFS, this document hereafter assumes the Upstream URI references a tarball. By "tarball", what the bloom maintainers specifically mean⁠ is a gzip-compressed tar-archive with a .tar.gz file extension.

--- https://wiki.ros.org/bloom/Tutorials/FirstTimeRelease#Preparing_for_Release⁠

Yep, can't wait for that forthcoming support for tar.bzip and zip. At any rate, to play nice with bloom-release, your upstream needs to come correct vis-a-vis ROS standards. Your CMakeLists.txt and package.xml files have to be tightly disciplined and the whole thing must build and test cleanly --- preferrably with catkin.

⁠Q. What's this "release"?

The release repository is embodiment for every release (thus far) of the upstream repository. It's usually a bare git repository⁠ with an embarrassingly large quantity of branches, each named for:

• packaging methodology (e.g., rpm, debian)
• ROS distribution (e.g., indigo, kinetic, melodic)
• operating system distribution (e.g., trusty, xenial, bionic)
• package name (e.g., ros_comm, sns_ik, orocos_kdl)

Within the given git repository victim destination, bloom-release will produce a branch for each element of the cartesian expansion of the aforementioned attributes.

Worse still, for a given package, every sub-project gets its own branch, too. For example, if you've bloomed sns_ik⁠ for ROS indigo to produce sns_ik-release, then the latter will contain the following branches:

• debian/indigo/trusty/sns_ik
• debian/indigo/trusty/sns_ik_examples
• debian/indigo/trusty/sns_ik_kinematics_plugin
• debian/indigo/trusty/sns_ik_lib

The result is a teeming plague of branches writhing over the git log --all --graph --oneline output, not unlike an infestation of maggots burrowing through a week-old roadkill.

⁠Q. How do I make a release repository?

Use the tarball2bloom script in this project.

$ ./tarball2bloom -h
Usage: ./tarball2bloom [OPTION]... ORIG_TARBALL
Bloom the given ORIG_TARBALL into a local bare git release repository.

Options
    -h                 print this usage and return success
    -C RELEASE_BARE    bloom into RELEASE_BARE (default: ${ORIG_TARBALL%.orig.tar.gz}.git)
    -R ROS_DISTRO      bloom for ROS_DISTRO (default: kinetic)
    -P PACKAGE_NAME    override package name (default: ${ORIG_TARBALL%%_*})
    -V FAKE_VERSION    override fake version (default: $(echo ${ORIG_TARBALL} | grep -Eo '[0-9]+\.[0-9]+\.[0-9]+'))

Examples:

    $ ./tarball2bloom rapidplan_0.1.2-118-gd75c1a7.orig.tar.gz

    $ ./tarball2bloom \
    >      -C rapidplan-release_0.1.2-118-gd75c1a7.git \
    >      rapidplan_0.1.2-118-gd75c1a7.orig.tar.gz

    $ ./tarball2bloom \
    >      -C rapidplan-release_0.1.2-118-gd75c1a7.git \
    >      -R kinetic \
    >      rapidplan_0.1.2-118-gd75c1a7.orig.tar.gz

    $ ./tarball2bloom \
    >      -C rapidplan-release_0.1.2-118-gd75c1a7.git \
    >      -R kinetic \
    >      -V 0.1.2 \
    >      rapidplan_0.1.2-118-gd75c1a7.orig.tar.gz

⁠Q. How do I make debian artifacts?

Use the bloom2deb script in this project.

$ ./bloom2deb -h
Usage: ./bloom2deb [OPTION]... [-- [buildpackage option]...]
Build debian package artifacts from local bloomed RELEASE_DIR.

Options
    -h                print this usage and return success
    -C RELEASE_DIR    run as if started in RELEASE_DIR (default: $PWD)
    -V NEW_VERSION    override the bloom-release version

Notes:

    RELEASE_DIR must be a valid git checkout directory and the current branch
    name must be of the form

        "debian/${ROS_DISTRO}/${DISTRIBUTION}/${PACKAGE_NAME}"

    Examples:

        * debian/kinetic/xenial/ros_comm
        * debian/kinetic/xenial/sns_ik
        * debian/melodic/bionic/orocos_kdl

Example:

    $ ./bloom2deb -C ~/rapidplan-release -V 0.1.0-9-g8eb4b80 -- --source-option=-Dvcs-ref=0.1.0

⁠Q. How do I bloom and package everything at once?

Use the origtar2deb script in this project; it wraps invocations to tarball2bloom and bloom2deb. A word of warning: you may not want some the assumed defaults.

$ ./origtar2deb -h
Usage: ./origtar2deb [OPTION]... ORIGTAR
Bloom, build, and package an orig tarball.

Options
    -h                 print this usage and return success
    -f                 force bloom (overwrite extant release repository)
    -D DISTRIBUTION    override distribution (default: xenial)
    -R ROS_DISTRO      override ros_distro (default: kinetic)

Examples:

    $ ./origtar2deb rapidplan_0.1.2-222-g4a6d3cc.orig.tar

    $ ./origtar2deb -f rapidplan_0.1.2-222-g4a6d3cc.orig.tar

    $ ./origtar2deb -f -D xenial rapidplan_0.1.2-222-g4a6d3cc.orig.tar

    $ ./origtar2deb -f -D xenial -R kinetic rapidplan_0.1.2-222-g4a6d3cc.orig.tar