Add more options to run custom scripts at multiple points in the build stages

.gitlab-ci/docker-ros.yml

@@ -12,21 +12,24 @@ variables:
   ADDITIONAL_DEBS_FILE:       docker/additional-debs.txt              # Relative filepath to file containing additional apt deb packages to install
   ADDITIONAL_FILES_DIR:       docker/additional-files                 # Relative path to directory containing additional files to copy into image"
   ADDITIONAL_PIP_FILE:        docker/additional-pip-requirements.txt  # Relative filepath to file containing additional pip packages to install
+  AFTER_DEPENDENCY_INSTALLATION_SCRIPT: docker/custom.sh              # Relative filepath to script containing commands to run after dependency installation
   BASE_IMAGE:                 ''                                      # Base image name:tag (required)
+  BEFORE_DEPENDENCY_IDENTIFICATION_SCRIPT: docker/before_dependency_identification.sh # Relative filepath to script containing commands to run before dependency identification
+  BEFORE_DEPENDENCY_INSTALLATION_SCRIPT: docker/before_dependency_installation.sh     # Relative filepath to script containing commands to run before dependency installation
   BLACKLISTED_PACKAGES_FILE:  docker/blacklisted-packages.txt         # Relative filepath to file containing the blacklisted packages
   BUILD_CONTEXT:              .                                       # Build context of Docker build process
   COMMAND:                    ''                                      # Launch command of run image (required if target=run)
   CMAKE_ARGS:                 '-DCMAKE_BUILD_TYPE=Release'            # CMake arguments to pass to `colcon build`
-  CUSTOM_SCRIPT_FILE:         docker/custom.sh                        # Relative filepath to script containing custom installation commands
   DISABLE_ROS_INSTALLATION:   'false'                                 # Disable automatic installation of `ros-$ROS_DISTRO-ros-core` package, e.g., if ROS is already installed in `base-image` and package is not available for the OS
   DOCKER_ROS_GIT_REF:         main                                    # Git ref of *docker-ros* to run in CI
   ENABLE_INDUSTRIAL_CI:       'false'                                 # Enable industrial_ci
   ENABLE_PUSH_AS_LATEST:      'false'                                 # Push images with tag `latest`/`latest-dev` in addition to the configured image names
-  ENABLE_RECURSIVE_ADDITIONAL_DEBS:  'false'                          # Enable recursive discovery of files named `additional-debs-file`
-  ENABLE_RECURSIVE_ADDITIONAL_PIP:   'false'                          # Enable recursive discovery of files named `additional-pip-file`
-  ENABLE_RECURSIVE_BLACKLISTED_PACKAGES:  'false'                     # Enable recursive discovery of files named `blacklisted-packages-file`
-  ENABLE_RECURSIVE_CUSTOM_SCRIPT:    'false'                          # Enable recursive discovery of files named `custom-script-file`
-  ENABLE_RECURSIVE_VCS_IMPORT:       'true'                           # Enable recursive discovery of files named `*.repos`
+  ENABLE_RECURSIVE_ADDITIONAL_DEBS: 'false'                           # Enable recursive discovery of files named `additional-debs-file`
+  ENABLE_RECURSIVE_ADDITIONAL_PIP: 'false'                            # Enable recursive discovery of files named `additional-pip-file`
+  ENABLE_RECURSIVE_AFTER_DEPENDENCY_INSTALLATION_SCRIPT: 'false'      # Enable recursive discovery of files named `after-dependency-installation-script`
+  ENABLE_RECURSIVE_BEFORE_DEPENDENCY_INSTALLATION_SCRIPT: 'false'     # Enable recursive discovery of files named `before-dependency-installation-script`
+  ENABLE_RECURSIVE_BLACKLISTED_PACKAGES: 'false'                      # Enable recursive discovery of files named `blacklisted-packages-file`
+  ENABLE_RECURSIVE_VCS_IMPORT: 'true'                                 # Enable recursive discovery of files named `*.repos`
   ENABLE_SINGLEARCH_PUSH:     'false'                                 # Enable push of single arch images with [-amd64|-arm64] postfix
   ENABLE_SLIM:                'true'                                  # Enable an extra slimmed run image via slim (only if run stage is targeted)
   GIT_HTTPS_PASSWORD:         ${CI_JOB_TOKEN}                         # Password for cloning private Git repositories via HTTPS
@@ -41,7 +44,6 @@ variables:
   REGISTRY_USER:              ${CI_REGISTRY_USER}                     # Docker registry username
   REGISTRY:                   ${CI_REGISTRY}                          # Docker registry to push images to
   RMW_IMPLEMENTATION:         'rmw_cyclonedds_cpp'                    # RMW implementation to use (only for ROS 2)
-  RMW_ZENOH_GIT_REF:          ''                                      # Git ref of rmw_zenoh repo to build if `RMW_IMPLEMENTATION=rmw_zenoh_cpp`
   ROS_DISTRO:                 ''                                      # ROS Distro (required if ROS is not installed in `base-image`)
   SLIM_BUILD_ARGS:            '--sensor-ipc-mode proxy --continue-after=10 --show-clogs --http-probe=false'  # Arguments to `slim build` (except for `--target` and `--tag`)
   TARGET:                     run                                     # Target stage of Dockerfile (comma-separated list) [dev|run]
@@ -205,10 +207,6 @@ run-arm64:
       fi
     - git clone --branch master --depth 1 https://github.com/ros-industrial/industrial_ci.git .industrial_ci
     - test -f ${BUILD_CONTEXT}/.repos || echo "repositories:" > ${BUILD_CONTEXT}/.repos
-    - |-
-      if [ "$RMW_IMPLEMENTATION" = "rmw_zenoh_cpp" ]; then
-        export UNDERLAY="/opt/ws_rmw_zenoh/install"
-      fi
   script: .industrial_ci/gitlab.sh
 
 Test dev-amd64:

README.md

@@ -33,7 +33,7 @@
   - [Package Blacklist](#package-blacklist)
   - [Extra System Dependencies (*apt*)](#extra-system-dependencies-apt)
   - [Extra System Dependencies (*pip*)](#extra-system-dependencies-pip)
-  - [Custom Installation Script](#custom-installation-script)
+  - [Custom Installation Scripts](#custom-installation-scripts)
   - [Extra Image Files](#extra-image-files)
 - [Additional Information](#additional-information)
   - [User Setup](#user-setup)
@@ -52,13 +52,14 @@ We recommend to use *docker-ros* in combination with our other tools for Docker
 The Dockerfile performs the following steps to build these images:
 1. All dependency repositories that are defined in a `.repos` file anywhere in the repository are cloned using [*vcstool*](https://github.com/dirk-thomas/vcstool).
 2. *(optional)* Packages blacklisted in a special file `blacklisted-packages.txt` are removed from the workspace (see [*Advanced Dependencies*](#package-blacklist)).
-3. The ROS dependencies listed in each package's `package.xml` are installed by [*rosdep*](https://docs.ros.org/en/independent/api/rosdep/html/).
-4. *(optional)* Additional apt dependencies from a special file `additional-debs.txt` are installed, if needed (see [*Advanced Dependencies*](#extra-system-dependencies-apt)).
-5. *(optional)* Additional pip requirements from a special file `additional-pip-requirements.txt` are installed, if needed (see [*Advanced Dependencies*](#extra-system-dependencies-pip)).
-6. *(optional)* A special folder `additional-files/` is copied into the images, if needed (see [*Advanced Dependencies*](#extra-image-files)).
-7. *(optional)* A special script `custom.sh` is executed to perform further arbitrary installation commands, if needed (see [*Advanced Dependencies*](#custom-installation-script)).
-8. *(deployment)* All ROS packages are built using `catkin` (ROS) or `colcon` (ROS2).
-9. *(deployment)* A custom launch command is configured to run on container start.
+3. *(optional)* A special script `before_dependency_installation.sh` is executed to perform arbitrary installation commands, if needed (see [*Advanced Dependencies*](#custom-installation-scripts)).
+4. The ROS dependencies listed in each package's `package.xml` are installed by [*rosdep*](https://docs.ros.org/en/independent/api/rosdep/html/).
+5. *(optional)* Additional apt dependencies from a special file `additional-debs.txt` are installed, if needed (see [*Advanced Dependencies*](#extra-system-dependencies-apt)).
+6. *(optional)* Additional pip requirements from a special file `additional-pip-requirements.txt` are installed, if needed (see [*Advanced Dependencies*](#extra-system-dependencies-pip)).
+7. *(optional)* A special folder `additional-files/` is copied into the images, if needed (see [*Advanced Dependencies*](#extra-image-files)).
+8. *(optional)* A special script `custom.sh` is executed to perform arbitrary installation commands, if needed (see [*Advanced Dependencies*](#custom-installation-scripts)).
+9. *(deployment)* All ROS packages are built using `catkin` (ROS) or `colcon` (ROS2).
+10. *(deployment)* A custom launch command is configured to run on container start.
 
 ### Prerequisites
 
@@ -322,11 +323,14 @@ If your ROS-based repository requires Python dependencies that cannot be install
 
 Create a file `additional-pip-requirements.txt` in your `docker` folder (or configure a different `ADDITIONAL_PIP_FILE`) and list any other Python dependencies that need to be installed via *pip*.
 
-### Custom Installation Script
+### Custom Installation Scripts
 
-If your ROS-based repository requires to execute any other installation or pre-/post-installation steps, you can use a special `custom.sh` script.
+If your ROS-based repository requires to execute any other installation or pre-/post-installation steps, you can specify multiple custom scripts that are executed during the image building process. See the [configuration variable documentation](#configuration-variables) for the following variables.
+- `BEFORE_DEPENDENCY_IDENTIFICATION_SCRIPT`
+- `BEFORE_DEPENDENCY_INSTALLATION_SCRIPT`
+- `AFTER_DEPENDENCY_INSTALLATION_SCRIPT`
 
-Create a script `custom.sh` in your `docker` folder (or configure a different `CUSTOM_SCRIPT_FILE`) that executes arbitrary commands as part of the image building process.
+Create those scripts in your `docker` folder (or configure different filepaths via the specified environment variables).
 
 ### Extra Image Files
 
@@ -366,9 +370,18 @@ The password of the custom user is set to its username (`dockeruser:dockeruser`
 - **`additional-pip-file` | `ADDITIONAL_PIP_FILE`**  
   Relative filepath to file containing additional pip packages to install  
   *default:* `docker/additional-pip-requirements.txt`
+- **`after-dependency-installation-script` | `AFTER_DEPENDENCY_INSTALLATION_SCRIPT`**  
+  Relative filepath to script containing commands to run after dependency installation  
+  *default:* `docker/custom.sh`
 - **`base-image` | `BASE_IMAGE`**  
   Base image `name:tag`  
-  *required*  
+  *required*
+- **`before-dependency-identification-script` | `BEFORE_DEPENDENCY_IDENTIFICATION_SCRIPT`**  
+  Relative filepath to script containing commands to run before dependency identification  
+  *default:* `docker/before_dependency_identification.sh`
+- **`before-dependency-installation-script` | `BEFORE_DEPENDENCY_INSTALLATION_SCRIPT`**  
+  Relative filepath to script containing commands to run before dependency installation  
+  *default:* `docker/before_dependency_installation.sh`
 - **`blacklisted-packages-file` | `BLACKLISTED_PACKAGES_FILE`**  
   Relative filepath to file containing blacklisted packages  
   *default:* `docker/blacklisted-packages.txt`
@@ -381,9 +394,6 @@ The password of the custom user is set to its username (`dockeruser:dockeruser`
 - **`cmake-args` | `CMAKE_ARGS`**  
   CMake arguments to pass to `colcon build`  
   *default:* `"-DCMAKE_BUILD_TYPE=Release"`  
-- **`custom-script-file` | `CUSTOM_SCRIPT_FILE`**  
-  Relative filepath to script containing custom installation commands  
-  *default:* `docker/custom.sh`  
 - **`dev-image-name` | `DEV_IMAGE_NAME`**  
   Image name of dev image  
   *default:* `<IMAGE_NAME>`  
@@ -421,12 +431,15 @@ The password of the custom user is set to its username (`dockeruser:dockeruser`
 - **`enable-recursive-additional-pip` | `ENABLE_RECURSIVE_ADDITIONAL_PIP`**  
   Enable recursive discovery of files named `additional-pip-file`  
   *default:* `false`
+- **`enable-recursive-after-dependency-installation-script` | `ENABLE_RECURSIVE_AFTER_DEPENDENCY_INSTALLATION_SCRIPT`**  
+  Enable recursive discovery of files named `after-dependency-installation-script`  
+  *default:* `false`
+- **`enable-recursive-before-dependency-installation-script` | `ENABLE_RECURSIVE_BEFORE_DEPENDENCY_INSTALLATION_SCRIPT`**  
+  Enable recursive discovery of files named `before-dependency-installation-script`  
+  *default:* `false`
 - **`enable-recursive-blacklisted-packages` | `ENABLE_RECURSIVE_BLACKLISTED_PACKAGES`**  
   Enable recursive discovery of files named `blacklisted-packages-file`  
   *default:* `false`
-- **`enable-recursive-custom-script` | `ENABLE_RECURSIVE_CUSTOM_SCRIPT`**  
-  Enable recursive discovery of files named `custom-script-file`  
-  *default:* `false`
 - **`enable-recursive-vcs-import` | `ENABLE_RECURSIVE_VCS_IMPORT`**  
   Enable recursive discovery of files named `*.repos`  
   *default:* `true`
@@ -469,9 +482,6 @@ The password of the custom user is set to its username (`dockeruser:dockeruser`
   ROS 2 middleware implementation  
   *default:* `rmw_cyclonedds_cpp`  
   *supported values:* `rmw_zenoh_cpp`, `rmw_fastrtps_cpp`, `rmw_cyclonedds_cpp`, `rmw_gurumdds_cpp`, ...  
-- **`rmw-zenoh-git-ref` | `RMW_ZENOH_GIT_REF`**  
-  Git ref of rmw_zenoh repo to build if `RMW_IMPLEMENTATION=rmw_zenoh_cpp`  
-  *default:* `$ROS_DISTRO`  
 - **`ros-distro` | `ROS_DISTRO`**  
   ROS Distro  
   *required if ROS is not installed in `base-image`*