Build Debian packages of each release

.github/workflows/debs.yaml

@@ -0,0 +1,58 @@
+name: debian packages (humble)
+
+# On a release tag, builds every eplansys package for ROS 2 Humble with bloom
+# and attaches the .debs, with the index apt reads, to that tag's GitHub
+# release. The release is then an apt repository:
+#
+#   echo "deb [trusted=yes] https://github.com/ePlanSys/eplansys/releases/download/v0.3.0 ./" |
+#     sudo tee /etc/apt/sources.list.d/eplansys.list
+#   sudo apt update && sudo apt install ros-humble-eplansys
+#
+# workflow_dispatch builds the same packages and keeps them as a workflow
+# artifact, without a release, for trying a change to the packaging.
+
+on:
+  push:
+    tags: [ 'v*' ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  debs:
+    runs-on: ubuntu-22.04
+    container:
+      image: ros:humble
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: ws/src/eplansys
+
+      - name: Install the packaging tools
+        run: |
+          apt-get update
+          apt-get install -y python3-bloom python3-vcstool fakeroot debhelper dh-python python3-all dpkg-dev apt-utils
+          rosdep update --rosdistro humble
+
+      - name: Import the pinned sources
+        run: vcs import ws/src < ws/src/eplansys/dependency_repos.repos
+
+      - name: Build the packages
+        run: ws/src/eplansys/packaging/build-debs.sh ws debs
+
+      - name: Keep them as an artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: debs-humble
+          path: debs/
+
+      - name: Attach them to the release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            debs/*.deb
+            debs/Packages
+            debs/Packages.gz
+            debs/Release

README.md

@@ -45,6 +45,24 @@ docker run --rm eplansys ros2 launch eplansys_demo survey_sites_launch.py north:
 
 The mission prints its elapsed time and exits when the goal holds.
 
+## Installing
+
+Each release carries Debian packages for ROS 2 Humble on Ubuntu 22.04, and the
+release itself is the apt repository:
+
+```bash
+echo "deb [trusted=yes] https://github.com/ePlanSys/eplansys/releases/download/v0.3.0 ./" |
+  sudo tee /etc/apt/sources.list.d/eplansys.list
+sudo apt update
+sudo apt install ros-humble-eplansys ros-humble-eplansys-demo
+source /opt/ros/humble/setup.bash
+ros2 launch eplansys_demo survey_sites_launch.py
+```
+
+The PlanSys2 packages in it are this repository's fork, released under the
+upstream names at 3.0.0, and replace the upstream 2.0.x packages when both are
+available.
+
 We want to invite you to contribute to this Open Source project!
 
 **Documentation: [eplansys.github.io/eplansys](https://eplansys.github.io/eplansys)**

eplansys_docs/getting_started/installation.rst

@@ -1,12 +1,32 @@
 Installation
 ============
 
-ePlanSys is built as a ROS 2 workspace with ``colcon``. The whole repository,
-including the classical PlanSys2 packages, builds on ROS 2 Rolling; the
-epistemic packages that do not depend on ``plansys2_executor`` also build on
-Humble. Both configurations are the ones exercised in continuous integration
-by ``.github/workflows/rolling.yaml`` and
-``.github/workflows/epistemic-humble.yaml``.
+ePlanSys is built as a ROS 2 workspace with ``colcon``, or installed from the
+Debian packages each release carries for Humble. The whole repository,
+including the classical PlanSys2 packages, builds on Rolling and on Humble.
+Continuous integration builds all of it on Rolling
+(``.github/workflows/rolling.yaml``) and the epistemic chain on Humble
+(``.github/workflows/epistemic-humble.yaml``); the Docker image and the release
+packages are built from the whole repository on Humble.
+
+From the release packages
+-------------------------
+
+On Ubuntu 22.04 with ROS 2 Humble, a release is an apt repository:
+
+.. code-block:: bash
+
+   echo "deb [trusted=yes] https://github.com/ePlanSys/eplansys/releases/download/v0.3.0 ./" |
+     sudo tee /etc/apt/sources.list.d/eplansys.list
+   sudo apt update
+   sudo apt install ros-humble-eplansys ros-humble-eplansys-demo
+
+``ros-humble-eplansys`` brings the epistemic packages, the planner
+(``ros-humble-aletheia``, built from del-planner) and the grounder
+(``ros-humble-plank``) at the commits the release pins. The PlanSys2 packages
+are this repository's fork, released under the upstream names at 3.0.0, and
+replace the upstream 2.0.x packages. ``.github/workflows/debs.yaml`` builds
+them with ``packaging/build-debs.sh`` when a release is tagged.
 
 Supported distributions
 -----------------------
@@ -30,6 +50,10 @@ Supported distributions
        and ``plansys2_tui_cli``. ``plansys2_epistemic_bt_builder`` is absent
        because it is the one epistemic package that depends on
        ``plansys2_executor``.
+   * - Humble
+     - ``debs.yaml``
+     - Every package the release carries, as Debian packages, on a release
+       tag.
 
 Two differences between the distributions are what the list above turns on,
 and both are posed as questions about the API, not about the distribution's

packaging/build-debs.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+#
+# Build Debian packages of eplansys for ROS 2 Humble, and an apt repository of
+# them.
+#
+#   packaging/build-debs.sh <workspace> <output directory>
+#
+# The workspace is one `vcs import src < dependency_repos.repos` produced, with
+# this repository at src/eplansys. Run it in a ros:humble container: it
+# installs every package it builds, since the next one builds against it.
+#
+# The PlanSys2 packages here are a fork, released under the upstream names at
+# version 3.0.0. Upstream Humble ships 2.0.9, so apt prefers these once the
+# repository is added. cascade_lifecycle is built too, from the rolling-devel
+# checkout the repos file pins: plansys2_executor links a target Humble's 1.1.0
+# does not export, and at 2.0.6 it is preferred over it the same way. popf
+# comes from upstream as it is.
+
+set -euo pipefail
+
+WS=$(realpath "$1")
+OUT=$(realpath -m "$2")
+DISTRO=humble
+mkdir -p "$OUT"
+
+# The setup script reads variables it does not define.
+set +u
+# shellcheck disable=SC1091
+source /opt/ros/$DISTRO/setup.bash
+set -u
+export DEBIAN_FRONTEND=noninteractive
+export DEB_BUILD_OPTIONS=nocheck
+
+cd "$WS"
+
+# plank is a plain CMake project, and bloom packages only what has a
+# package.xml. The grounder runs plank without linking it, which is why its
+# package.xml does not name it; an installed grounder needs it all the same.
+cp src/eplansys/packaging/plank.package.xml src/plank/package.xml
+grep -q '<exec_depend>plank</exec_depend>' src/eplansys/plansys2_epddl_grounder/package.xml ||
+  sed -i 's|<depend>plansys2_pddl_parser</depend>|&\n  <exec_depend>plank</exec_depend>|' \
+    src/eplansys/plansys2_epddl_grounder/package.xml
+
+PACKAGES=$(colcon list --topological-order --names-only \
+  --packages-up-to eplansys eplansys_demo plank \
+  --packages-skip popf)
+
+# rosdep resolves what each package depends on. The packages built here have to
+# resolve to the Debian names bloom gives them, and those that upstream also
+# ships already do; aletheia and plank are known to no one else.
+ROSDEP=/etc/ros/rosdep/sources.list.d/00-eplansys.list
+{
+  for name in $PACKAGES; do
+    echo "$name:"
+    echo "  ubuntu: [ros-$DISTRO-${name//_/-}]"
+  done
+} > "$OUT/eplansys-rosdep.yaml"
+echo "yaml file://$OUT/eplansys-rosdep.yaml" > "$ROSDEP"
+rosdep update --rosdistro $DISTRO >/dev/null
+
+for name in $PACKAGES; do
+  path=$(colcon list --packages-select "$name" --paths-only)
+
+  # A package already in the output was built by an earlier run over the same
+  # sources, and is only installed again for what depends on it.
+  built=$(ls "$OUT"/ros-$DISTRO-"${name//_/-}"_*.deb 2>/dev/null | head -1 || true)
+  if [ -n "$built" ]; then
+    echo "=== $name (already built)"
+    apt-get install -y -q "$built" >/dev/null
+    continue
+  fi
+  echo "=== $name ($path)"
+
+  rosdep install --from-paths "$path" --ignore-src -y --rosdistro $DISTRO -q
+
+  (
+    cd "$path"
+    rm -rf debian obj-*
+    bloom-generate rosdebian --ros-distro $DISTRO >/dev/null
+    fakeroot debian/rules binary >/dev/null
+  )
+
+  # apt reads an argument as a file only when it is a path it can tell apart
+  # from a package name, hence the absolute one.
+  deb=$(realpath "$(ls -t "$(dirname "$path")"/ros-$DISTRO-"${name//_/-}"_*.deb | head -1)")
+  apt-get install -y -q "$deb" >/dev/null
+  mv "$deb" "$OUT"/
+  rm -rf "$path/debian" "$path"/obj-* "$(dirname "$path")"/*.ddeb
+done
+
+# A flat repository: the packages and their index side by side, which apt reads
+# from any URL that serves the directory, a GitHub release included.
+cd "$OUT"
+dpkg-scanpackages --multiversion . /dev/null > Packages
+gzip -9kf Packages
+apt-ftparchive release . > Release
+ls -1 ./*.deb | wc -l

packaging/plank.package.xml

@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
+<package format="3">
+  <name>plank</name>
+  <version>1.0.0</version>
+  <description>
+    plank, the DEL-based epistemic planning toolkit by Alessandro Burigana and
+    Francesco Fabiano: the EPDDL parser and grounder plansys2_epddl_grounder runs.
+    Packaged here from the commit dependency_repos.repos pins; plank itself is a
+    plain CMake project.
+  </description>
+  <maintainer email="hanielulises2003@gmail.com">Haniel Ulises Vasquez Morales</maintainer>
+  <license>MIT</license>
+  <author>Alessandro Burigana</author>
+  <author>Francesco Fabiano</author>
+
+  <buildtool_depend>cmake</buildtool_depend>
+  <depend>boost</depend>
+
+  <export>
+    <build_type>cmake</build_type>
+  </export>
+</package>