chore(ci): split Dockerfile into dev/builder/runtime stages

Rebuilding the full image on every code change is slow. A reusable dev
stage lets you iterate on build/test/develop without repeating setup.

The project is not supported on Debian Trixie, therefore the dev
container is useful to use Debian Bookworm.

Relate-to: UIC-3673

Author: lmolina

Dockerfile

@@ -1,10 +1,12 @@
 # SPDX-License-Identifier: Zlib
 # SPDX-FileCopyrightText: Silicon Laboratories Inc. https://www.silabs.com
 
-FROM debian:bookworm AS builder
+FROM debian:bookworm AS dev
 
-ARG UNIFYSDK_GIT_REPOSITORY https://github.com/SiliconLabs/UnifySDK
-ARG UNIFYSDK_GIT_TAG main
+ARG UNIFYSDK_GIT_REPOSITORY=https://github.com/SiliconLabs/UnifySDK
+ARG UNIFYSDK_GIT_TAG=main
+ENV UNIFYSDK_GIT_REPOSITORY=${UNIFYSDK_GIT_REPOSITORY} \
+    UNIFYSDK_GIT_TAG=${UNIFYSDK_GIT_TAG}
 
 ENV project z-wave-protocol-controller
 ENV workdir /usr/local/opt/${project}
@@ -13,6 +15,8 @@ ADD . ${workdir}
 ARG HELPER="./helper.mk"
 ARG HELPER_SETUP_RULES=setup
 ARG HELPER_DEFAULT_RULES=default
+ENV HELPER=${HELPER} \
+  HELPER_DEFAULT_RULES=${HELPER_DEFAULT_RULES}
 
 WORKDIR ${workdir}
 
@@ -23,7 +27,10 @@ RUN echo "# log: Setup system" \
   && apt-get install -y --no-install-recommends -- make sudo \
   && ${HELPER} help ${HELPER_SETUP_RULES} \
   && date -u
+ENTRYPOINT [ "/usr/bin/bash" ]
+CMD []
 
+FROM dev AS builder
 RUN echo "# log: Build" \
   && set -x  \
   && ${HELPER} ${HELPER_DEFAULT_RULES} \
@@ -36,7 +43,7 @@ RUN echo "# log: Build" \
   && ${HELPER} distclean \
   && date -u
 
-FROM debian:bookworm
+FROM debian:bookworm AS runtime
 ENV project=z-wave-protocol-controller
 ARG workdir=/usr/local/opt/${project}
 COPY --from=builder ${workdir}/dist/ ${workdir}/dist/

README.md

@@ -23,6 +23,47 @@ Or relevant sources pages, to get started head to:
 
 ## Quickstart
 
+### Docker build
+
+The fastest (less than 20min) way to build z-wave-protocol-controller from scratch
+is to delegate all tasks to docker. The final image will contain the binaries that
+you can use.
+
+```sh
+docker build https://github.com/SiliconLabsSoftware/z-wave-protocol-controller.git#ver_1.7.0
+```
+
+This one-liner will do download latest release, setup environment, build, test, package...
+
+Also a docker-compose file is provided to start ZPC and use it along a MQTT client
+(eg:
+[mosquitto-clients](https://github.com/eclipse-mosquitto/mosquitto/)
+).
+
+### Docker development
+
+The project Dockerfile has three stages: `dev` (setup only, for interactive
+use), `builder` (full build and package), and `runtime` (minimal runnable
+image). To work iteratively in a container with your host source bind-mounted
+(e.g., build and run ctest without rebuilding the image each time):
+
+```sh
+# Build the dev stage
+docker build --target dev -t z-wave-protocol-controller:dev .
+
+# Run a shell with your source mounted
+docker run -it --rm -v "$PWD:/usr/local/opt/z-wave-protocol-controller" -w /usr/local/opt/z-wave-protocol-controller z-wave-protocol-controller:dev
+
+# Inside the container: build and run unit tests
+./helper.mk default
+
+# Run unit tests
+ctest --test-dir build/applications --output-on-failure
+```
+
+Power users might prefer to work in sources tree in a native GNU/Linux
+environment as explained below.
+
 ### Native (Linux) build
 
 The project is CMake based, to prepare the environment,
@@ -136,7 +177,7 @@ You can use this [script](./scripts/wslusb.ps1).
 Start by installing the usbipd service as described at: https://learn.microsoft.com/en-us/windows/wsl/connect-usb
 
 ```sh
-# You can list devices using: 
+# You can list devices using:
 
 (Powershell)$ ./wslusb.ps1 -List
 
@@ -157,26 +198,6 @@ Start by installing the usbipd service as described at: https://learn.microsoft.
 
 Refer to [./doc](doc) for more (using shell, MQTT, WebApp etc).
 
-
-### Docker build
-
-The fastest (less than 20min) way to build z-wave-protocol-controller from scratch
-is to delegate all tasks to docker.
-
-```sh
-docker build https://github.com/SiliconLabsSoftware/z-wave-protocol-controller.git#ver_1.7.0
-```
-
-This one-liner will do download latest release, setup environment, build, test, package...
-
-Also a docker-compose file is provided to start ZPC and use it along a MQTT client
-(eg:
-[mosquitto-clients](https://github.com/eclipse-mosquitto/mosquitto/)
-).
-
-Power users might prefer to work in sources tree in a native GNU/Linux
-environment as explained above.
-
 ## Contributing
 
 - [CONTRIBUTING.md](CONTRIBUTING.md)