propagate new variables throughout entire pipeline

.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_IDENTIFICATION_SCRIPT: docker/after_dependency_identification.sh   # Relative filepath to script containing commands to run after dependency identification
+  AFTER_DEPENDENCY_INSTALLATION_SCRIPT: docker/after_dependency_installation.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_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

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 `after_dependency_installation.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,15 @@ 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`
+- `AFTER_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 +371,21 @@ 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-identification-script` | `AFTER_DEPENDENCY_IDENTIFICATION_SCRIPT`**  
+  Relative filepath to script containing commands to run after dependency identification  
+  *default:* `docker/after_dependency_identification.sh`
+- **`after-dependency-installation-script` | `AFTER_DEPENDENCY_INSTALLATION_SCRIPT`**  
+  Relative filepath to script containing commands to run after dependency installation  
+  *default:* `docker/after_dependency_installation.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 +398,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 +435,12 @@ 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-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`

action.yml

@@ -14,9 +14,21 @@ inputs:
   additional-pip-file:
     description: "Relative filepath to file containing additional pip packages to install"
     default: docker/additional-pip-requirements.txt
+  after-dependency-identification-script:
+    description: "Relative filepath to script containing commands to run after dependency identification"
+    default: docker/after_dependency_identification.sh
+  after-dependency-installation-script:
+    description: "Relative filepath to script containing commands to run after dependency installation"
+    default: docker/after_dependency_installation.sh
   base-image:
     description: "Base image name:tag"
     required: true
+  before-dependency-identification-script:
+    description: "Relative filepath to script containing commands to run before dependency identification"
+    default: docker/before_dependency_identification.sh
+  before-dependency-installation-script:
+    description: "Relative filepath to script containing commands to run before dependency installation"
+    default: docker/before_dependency_installation.sh
   blacklisted-packages-file:
     description: "Relative filepath to file containing blacklisted packages to remove from workspace"
     default: docker/blacklisted-packages.txt
@@ -28,9 +40,6 @@ inputs:
   cmake-args:
     description: "CMake arguments to pass to `colcon build`"
     default: "-DCMAKE_BUILD_TYPE=Release"
-  custom-script-file:
-    description: "Relative filepath to script containing custom installation commands"
-    default: docker/custom.sh
   dev-image-name:
     description: "Image name of dev image"
     default: ghcr.io/${{ github.repository }}
@@ -60,12 +69,12 @@ inputs:
   enable-recursive-additional-pip:
     description: "Enable recursive discovery of files named `additional-pip-file`"
     default: false
+  enable-recursive-after-dependency-installation-script:
+    description: "Enable recursive discovery of files named `after-dependency-installation-script`"
+    default: false
   enable-recursive-blacklisted-packages:
     description: "Enable recursive discovery of files named `blacklisted-packages-file`"
     default: false
-  enable-recursive-custom-script:
-    description: "Enable recursive discovery of files named `custom-script-file`"
-    default: false
   enable-singlearch-push:
     description: "Enable push of single arch images with [-amd64|-arm64] postfix"
     default: false
@@ -188,18 +197,21 @@ runs:
         ADDITIONAL_DEBS_FILE: ${{ inputs.additional-debs-file }}
         ADDITIONAL_FILES_DIR: ${{ inputs.additional-files-dir }}
         ADDITIONAL_PIP_FILE: ${{ inputs.additional-pip-file }}
+        AFTER_DEPENDENCY_IDENTIFICATION_SCRIPT: ${{ inputs.after-dependency-identification-script }}
+        AFTER_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.after-dependency-installation-script }}
         BASE_IMAGE: ${{ inputs.base-image }}
+        BEFORE_DEPENDENCY_IDENTIFICATION_SCRIPT: ${{ inputs.before-dependency-identification-script }}
+        BEFORE_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.before-dependency-installation-script }}
         BLACKLISTED_PACKAGES_FILE: ${{ inputs.blacklisted-packages-file }}
         COMMAND: ${{ inputs.command }}
         CMAKE_ARGS: ${{ inputs.cmake-args }}
-        CUSTOM_SCRIPT_FILE: ${{ inputs.custom-script-file }}
         DEV_IMAGE_NAME: ${{ steps.dev-image-name.outputs.lowercase }}
         DEV_IMAGE_TAG: ${{ inputs.dev-image-tag }}
         DISABLE_ROS_INSTALLATION: ${{ inputs.disable-ros-installation }}
         ENABLE_RECURSIVE_ADDITIONAL_DEBS: ${{ inputs.enable-recursive-additional-debs }}
         ENABLE_RECURSIVE_ADDITIONAL_PIP: ${{ inputs.enable-recursive-additional-pip }}
+        ENABLE_RECURSIVE_AFTER_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.enable-recursive-after-dependency-installation-script }}
         ENABLE_RECURSIVE_BLACKLISTED_PACKAGES: ${{ inputs.enable-recursive-blacklisted-packages }}
-        ENABLE_RECURSIVE_CUSTOM_SCRIPT: ${{ inputs.enable-recursive-custom-script }}
         ENABLE_RECURSIVE_VCS_IMPORT: ${{ inputs.enable-recursive-vcs-import }}
         ENABLE_SLIM: ${{ inputs.enable-slim }}
         GIT_HTTPS_PASSWORD: ${{ inputs.git-https-password }}
@@ -252,18 +264,21 @@ runs:
         ADDITIONAL_DEBS_FILE: ${{ inputs.additional-debs-file }}
         ADDITIONAL_FILES_DIR: ${{ inputs.additional-files-dir }}
         ADDITIONAL_PIP_FILE: ${{ inputs.additional-pip-file }}
+        AFTER_DEPENDENCY_IDENTIFICATION_SCRIPT: ${{ inputs.after-dependency-identification-script }}
+        AFTER_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.after-dependency-installation-script }}
         BASE_IMAGE: ${{ inputs.base-image }}
+        BEFORE_DEPENDENCY_IDENTIFICATION_SCRIPT: ${{ inputs.before-dependency-identification-script }}
+        BEFORE_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.before-dependency-installation-script }}
         BLACKLISTED_PACKAGES_FILE: ${{ inputs.blacklisted-packages-file }}
         COMMAND: ${{ inputs.command }}
         CMAKE_ARGS: ${{ inputs.cmake-args }}
-        CUSTOM_SCRIPT_FILE: ${{ inputs.custom-script-file }}
         DEV_IMAGE_NAME: ${{ steps.dev-image-name.outputs.lowercase }}
         DEV_IMAGE_TAG: ${{ inputs.dev-image-tag }}
         DISABLE_ROS_INSTALLATION: ${{ inputs.disable-ros-installation }}
         ENABLE_RECURSIVE_ADDITIONAL_DEBS: ${{ inputs.enable-recursive-additional-debs }}
         ENABLE_RECURSIVE_ADDITIONAL_PIP: ${{ inputs.enable-recursive-additional-pip }}
+        ENABLE_RECURSIVE_AFTER_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.enable-recursive-after-dependency-installation-script }}
         ENABLE_RECURSIVE_BLACKLISTED_PACKAGES: ${{ inputs.enable-recursive-blacklisted-packages }}
-        ENABLE_RECURSIVE_CUSTOM_SCRIPT: ${{ inputs.enable-recursive-custom-script }}
         ENABLE_RECURSIVE_VCS_IMPORT: ${{ inputs.enable-recursive-vcs-import }}
         ENABLE_SINGLEARCH_PUSH: ${{ inputs.enable-singlearch-push }}
         ENABLE_SLIM: ${{ inputs.enable-slim }}
@@ -295,18 +310,21 @@ runs:
         ADDITIONAL_DEBS_FILE: ${{ inputs.additional-debs-file }}
         ADDITIONAL_FILES_DIR: ${{ inputs.additional-files-dir }}
         ADDITIONAL_PIP_FILE: ${{ inputs.additional-pip-file }}
+        AFTER_DEPENDENCY_IDENTIFICATION_SCRIPT: ${{ inputs.after-dependency-identification-script }}
+        AFTER_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.after-dependency-installation-script }}
         BASE_IMAGE: ${{ inputs.base-image }}
+        BEFORE_DEPENDENCY_IDENTIFICATION_SCRIPT: ${{ inputs.before-dependency-identification-script }}
+        BEFORE_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.before-dependency-installation-script }}
         BLACKLISTED_PACKAGES_FILE: ${{ inputs.blacklisted-packages-file }}
         COMMAND: ${{ inputs.command }}
         CMAKE_ARGS: ${{ inputs.cmake-args }}
-        CUSTOM_SCRIPT_FILE: ${{ inputs.custom-script-file }}
         DEV_IMAGE_NAME: ${{ steps.dev-image-name.outputs.lowercase }}
         DEV_IMAGE_TAG: latest-dev
         DISABLE_ROS_INSTALLATION: ${{ inputs.disable-ros-installation }}
         ENABLE_RECURSIVE_ADDITIONAL_DEBS: ${{ inputs.enable-recursive-additional-debs }}
         ENABLE_RECURSIVE_ADDITIONAL_PIP: ${{ inputs.enable-recursive-additional-pip }}
+        ENABLE_RECURSIVE_AFTER_DEPENDENCY_INSTALLATION_SCRIPT: ${{ inputs.enable-recursive-after-dependency-installation-script }}
         ENABLE_RECURSIVE_BLACKLISTED_PACKAGES: ${{ inputs.enable-recursive-blacklisted-packages }}
-        ENABLE_RECURSIVE_CUSTOM_SCRIPT: ${{ inputs.enable-recursive-custom-script }}
         ENABLE_RECURSIVE_VCS_IMPORT: ${{ inputs.enable-recursive-vcs-import }}
         ENABLE_SINGLEARCH_PUSH: ${{ inputs.enable-singlearch-push }}
         ENABLE_SLIM: ${{ inputs.enable-slim }}