From 3e3a9a26229ad513fa1402622ba93dba3d873e5f Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Wed, 23 Jul 2025 17:29:58 +0200 Subject: [PATCH 1/4] docs: shuffle sections into logical order The first section explains how to clone the repository, the second how to build Infinitime with the docker image, but the details on actually provisioning the image are at the end, despite this step taking place before the build itself. Move the sections into the order in which the steps should be followed. --- doc/buildWithDocker.md | 64 +++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/doc/buildWithDocker.md b/doc/buildWithDocker.md index 670590a645..9d4db707e7 100644 --- a/doc/buildWithDocker.md +++ b/doc/buildWithDocker.md @@ -15,46 +15,37 @@ Based on Ubuntu 22.04 with the following build dependencies: Before building, local repository must be fully initialized. -``` +```sh git clone https://github.com/InfiniTimeOrg/InfiniTime.git cd InfiniTime git submodule update --init ``` -## Run a container to build the project - -The `infinitime-build` image contains all the dependencies you need. -The default `CMD` will compile sources found in `/sources`, so you need only mount your code. - -Before continuing, make sure you first build the image as indicated in the [Build the image](#build-the-image) section, or check the [Using the image from Docker Hub](#using-the-image-from-docker-hub) section if you prefer to use a pre-made image. +## Provision the image -This example will build the firmware, generate the MCUBoot image and generate the DFU file. -For cloning the repo, see [these instructions](../doc/buildAndProgram.md#clone-the-repo). Outputs will be written to **/build/output**: +Before continuing, the build image needs to be either build locally or pulled +from Docker Hub, as described in the two sections below: -```bash -cd # e.g. cd ./work/Pinetime -docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build -``` +### Build the image -By default, the container runs as `root`, which is not convenient as all the files generated by the build will also belong to `root`. -The parameter `--user` overrides that default behavior. -The command above will run as your current user. +You can build the image yourself if you like! -If you only want to build a single CMake target, you can pass it in as the first parameter to the build script. -This means calling the script explicitly as it will override the `CMD`. -Here's an example for `pinetime-app`: +The following commands must be run from the root of the project. This operation +will take some time but, when done, a new image named `infinitime-build` is +available. -```bash -docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build /opt/build.sh pinetime-app +```sh +docker build -t infinitime-build ./docker ``` -## Using the image from Docker Hub +### Pull the image from Docker Hub -The image is available via Docker Hub for both the amd64 and arm64v8 architectures at [infinitime/infinitime-build](https://hub.docker.com/repository/docker/infinitime/infinitime-build). +The image is available via Docker Hub for both the amd64 and arm64v8 architectures at +[infinitime/infinitime-build](https://hub.docker.com/repository/docker/infinitime/infinitime-build). You can run it using the following command: -```bash +```sh docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime/infinitime-build ``` @@ -64,12 +55,27 @@ The default `latest` tag *should* automatically identify the correct image archi - For ARM64v8 (ARM64/aarch64) systems: `docker pull --platform linux/arm64 infinitime/infinitime-build` -## Build the image +## Run a container to build the project -You can build the image yourself if you like! +The `infinitime-build` image contains all the dependencies you need. +The default `CMD` will compile sources found in `/sources`, so you need only mount your code. -The following commands must be run from the root of the project. This operation will take some time but, when done, a new image named *infinitime-build* is available. +This example will build the firmware, generate the MCUBoot image and generate the DFU file. +For cloning the repo, see [these instructions](../doc/buildAndProgram.md#clone-the-repo). Outputs will be written to **/build/output**: -```bash -docker build -t infinitime-build ./docker +```sh +cd # e.g. cd ./work/Pinetime +docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build +``` + +By default, the container runs as `root`, which is not convenient as all the files generated by the build will also belong to `root`. +The parameter `--user` overrides that default behavior. +The command above will run as your current user. + +If you only want to build a single CMake target, you can pass it in as the first parameter to the build script. +This means calling the script explicitly as it will override the `CMD`. +Here's an example for `pinetime-app`: + +```sh +docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build /opt/build.sh pinetime-app ``` From 5cc1a5d458e2b0e64906edca230a38762ee63560 Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Wed, 23 Jul 2025 17:31:45 +0200 Subject: [PATCH 2/4] docker: update deprecated syntax `docker build` warns of deprecated syntax: 1 warning found (use docker --debug to expand): - LegacyKeyValueFormat: "ENV key=value" should be used instead of legacy "ENV key value" format (line 71) Update Dockerfile, removing the deprecated syntax usage. --- docker/Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker/Dockerfile b/docker/Dockerfile index bd940900c9..b862f25669 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -68,5 +68,5 @@ RUN adduser infinitime # Configure Git to accept the /sources directory as safe RUN git config --global --add safe.directory /sources -ENV SOURCES_DIR /sources +ENV SOURCES_DIR=/sources CMD ["/opt/build.sh"] From f0c40497014c050c4f76b260575a2e469e2c2b87 Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Wed, 23 Jul 2025 17:35:23 +0200 Subject: [PATCH 3/4] docs: remove superfluous link The docker build section points to another page with instructions on how to clone the repository, but this same page already contains these same instructions in the previous section. --- doc/buildWithDocker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/buildWithDocker.md b/doc/buildWithDocker.md index 9d4db707e7..04787b264d 100644 --- a/doc/buildWithDocker.md +++ b/doc/buildWithDocker.md @@ -61,7 +61,7 @@ The `infinitime-build` image contains all the dependencies you need. The default `CMD` will compile sources found in `/sources`, so you need only mount your code. This example will build the firmware, generate the MCUBoot image and generate the DFU file. -For cloning the repo, see [these instructions](../doc/buildAndProgram.md#clone-the-repo). Outputs will be written to **/build/output**: +Outputs will be written to **/build/output**: ```sh cd # e.g. cd ./work/Pinetime From f008b27bbb8999414d60900c4a9817fa7a04a324 Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Wed, 23 Jul 2025 17:38:06 +0200 Subject: [PATCH 4/4] docs: --user is only required when docker run as root The --user argument attempts to map the uid of the user inside the container to the user in the host. This works if docker is running as root, but is docker is running as the current user, then the uid in the container is mapped to a surrogate uid on the host, and this surrogate user does not have permissions to complete the build process. Clarify that the --user flag is only required when running docker as root. It is also likely not required by users using podman as a docker drop-in replacement, since podman always runs in rootless mode. --- doc/buildWithDocker.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/buildWithDocker.md b/doc/buildWithDocker.md index 04787b264d..db9bfcfc98 100644 --- a/doc/buildWithDocker.md +++ b/doc/buildWithDocker.md @@ -65,12 +65,20 @@ Outputs will be written to **/build/output**: ```sh cd # e.g. cd ./work/Pinetime -docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build +docker run --rm -it -v ${PWD}:/sources infinitime-build ``` -By default, the container runs as `root`, which is not convenient as all the files generated by the build will also belong to `root`. -The parameter `--user` overrides that default behavior. -The command above will run as your current user. +If the docker service is running as `root`, the build process inside the +container also runs as `root`, which is not convenient as all the files +generated by the build will also belong to `root`. The parameter `--user` +overrides this behaviour. The command below ensures that all files are created +as your current user: + + +```sh +cd # e.g. cd ./work/Pinetime +docker run --rm -it -v ${PWD}:/sources --user $(id -u):$(id -g) infinitime-build +``` If you only want to build a single CMake target, you can pass it in as the first parameter to the build script. This means calling the script explicitly as it will override the `CMD`.