diff --git a/CODEOWNERS b/CODEOWNERS index b81debe43793..03a0317736cc 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -605,6 +605,7 @@ /scripts/print_toolchain_checksum.sh @nrfconnect/ncs-ci /scripts/sdp/ @nrfconnect/ncs-ll-ursus +/scripts/docker/*.rst @nrfconnect/ncs-doc-leads /scripts/hid_configurator/*.rst @nrfconnect/ncs-si-bluebagel-doc /scripts/memfault/*.rst @nrfconnect/ncs-cia-doc /scripts/nrf_provision/fast_pair/*.rst @nrfconnect/ncs-si-bluebagel-doc diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index 3012feb9dd4c..1433a5561e30 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -45,6 +45,9 @@ .. _`Zephyr pull request #50305`: https://github.com/zephyrproject-rtos/zephyr/pull/50305 .. _`Zephyr issue #69546`: https://github.com/zephyrproject-rtos/zephyr/issues/69546 +.. _`print_toolchain_checksum.sh`: https://github.com/nrfconnect/sdk-nrf/blob/main/scripts/print_toolchain_checksum.sh +.. _`JLink License Agreement`: https://github.com/nrfconnect/sdk-nrf/blob/main/scripts/docker/jlink/license.txt + .. _`sdk-mcuboot`: https://github.com/nrfconnect/sdk-mcuboot .. _`MCUboot design`: https://github.com/mcu-tools/mcuboot/blob/main/docs/design.md .. _`MCUboot repository`: https://github.com/mcu-tools/mcuboot diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 6ec9e4a5d969..7501fefca01a 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -33,7 +33,7 @@ The following sections provide detailed lists of changes by component. IDE, OS, and tool support ========================= -|no_changes_yet_note| +* Added :ref:`nrf_toolchain_docker_image`, a containerized version of the |NCS| toolchain that can be used for development and testing. Board support ============= diff --git a/doc/nrf/scripts.rst b/doc/nrf/scripts.rst index 97634c77be0e..f7b66c709071 100644 --- a/doc/nrf/scripts.rst +++ b/doc/nrf/scripts.rst @@ -15,6 +15,7 @@ Here you can find documentation for these scripts. ../../scripts/shell/*/* ../../scripts/nrf_provision/*/* ../../scripts/hid_configurator/* + ../../scripts/docker/* ../../scripts/partition_manager/* ../../scripts/west_commands/sbom/* ../../scripts/memfault/* diff --git a/scripts/docker/README.md b/scripts/docker/README.md deleted file mode 100644 index 700575534f04..000000000000 --- a/scripts/docker/README.md +++ /dev/null @@ -1,103 +0,0 @@ -# sdk-nrf-toolchain docker image - -## Content - -The image is based on ubuntu:22.04 docker image with additional tools: - -* git -* nrfutil with following commands: - * toolchain-manager - * device -* ncs toolchain-bundle -* JLink (installation requires accepting SEGGER License) - -## Building image - -To build docker image you have to provide `VERSION` argument containing ID of Linux toolchain bundle you want to -install. -You can use [print_toolchain_checksum.sh](../print_toolchain_checksum.sh) to get ID proper for your sdk-nrf revision. - -```shell -TOOLCHAIN_ID=$(../print_toolchain_checksum.sh) -docker build --build-arg VERSION=$TOOLCHAIN_ID . -``` - -## Accepting JLink License - -To install and use JLink software you have to accept [JLink License Agreement](./jlink/license.txt). - -``` -By accessing and using Software and Materials provided by SEGGER as free download, you acknowledge and agree to the following Terms of Use. If you do not agree to these Terms, do not download or use any Software or Material. - -1) You agree that you will not use the Software or Material for any purpose that is unlawful or illegal. -2) You agree to use the Software only in accordance with the license regulations included in the Software. -3) You acknowledge that the Software and Material is provided by SEGGER on "as is" basis without any express or implied warranty of any kind. -4) You confirm that you are not a person, entity or organization designated by the European Community as a terrorist, terror organization or entity pursuant to the applicable European Council Regulations. -5) You confirm that you are not located in a prohibited or embargoed country and confirm that you will not ship, distribute, transfer and/or export our Software or Material to any prohibited or embargoed country as mentioned in any such European Union law or regulation. - -Further information with regard to the listed persons, entities and organizations can be obtained from the official EU website. If there is any doubt if you are on this list it is strongly recommended to review such lists or get in touch with SEGGER prior download of any Software or Material. - -Copyright (c) SEGGER Microcontroller GmbH -``` - -If container is run in interactive mode, you will be asked for accepting license on the start of container. - -You can also start container with `ACCEPT_JLINK_LICENSE=1` environment variable which and JLink will be installed -without prompting. - -During post installation steps, JLink configures `udev` roles. That operation requires running container with -`--privileged` flag to grant container needed permissions. - -## Running container - -Toolchain environment variables are set only in bash session. Outside bash session, these variables are not set and -tools delivered in toolchain bundle cannot be found on path. -`sdk-nrf-toolchain` image uses `bash` command as entrypoint. If entrypoint is not overwritten, you can start your docker -container in both interactive and non-interactive mode. - -### Locally - -To run `sdk-nrf-toolchain` container to build and flash hexes, please run following command. - -```docker run -ti ghcr.io/nrfconnect/sdk-nrf-toolchain: -v /dev:/dev --privileged -e ACCEPT_JLINK_LICENSE=1 bash``` - -> [!TIP] -> You can also add `-v :/ncs` argument to `docker run` command to mount NCS project -> to container. -> In such case, you might encounter issues with repositories ownership and west project configuration. To resolve them, -> please: -> * Run `git config --global --add safe.directory '*'` command to mark mounted git repositories as trusted. -> * Run `west update` to import west commands delivered in NCS project (for example `west build`) -> * Add `--pristine` argument to `west build` command - to avoid path mismatch issues. - -### In CI - -CI systems usually run docker container in detached mode and can override default entrypoint and command. -However, it is still possible to use `sdk-nrf-toolchain` image in pipelines. - -#### GitHub Actions - -GitHub action starts container with overwritten default entrypoint. That means you have to set `bash` as a default shell -to load all required environment variables. - -If container is started with `ACCEPT_JLINK_LICENSE` env variable set to 1, JLink will be installed just before first -bash command is executed. - -Example job configuration: - -```yaml -jobs: - build-in-docker: - runs-on: ubuntu-22.04 - container: - image: ghcr.io/nrfconnect/sdk-nrf-toolchain: # steps in this job are executed inside sdk-nrf-toolchain container - env: - ACCEPT_JLINK_LICENSE: 1 # set if you want to install JLink - defaults: - run: - shell: bash # It is required to set `bash` as default shell - steps: - - name: Run command in NCS toolchain environment - run: "west --version" # This command is executed in bash shell `docker exec bash -c west --version`) - # It will also install JLink if ACCEPT_JLINK_LICENSE is set to 1 -``` diff --git a/scripts/docker/README.rst b/scripts/docker/README.rst new file mode 100644 index 000000000000..1d62a55c931b --- /dev/null +++ b/scripts/docker/README.rst @@ -0,0 +1,101 @@ +.. _nrf_toolchain_docker_image: + +|NCS| toolchain Docker image +############################ + +.. contents:: + :local: + :depth: 2 + +The image is based on Linux - Ubuntu 22.04 Docker image with the following additional tools: + +* Git +* `nRF Util`_ with following commands: + + * ``toolchain-manager`` + * ``device`` + +* |NCS| toolchain bundle +* JLink |jlink_ver| (installation requires accepting SEGGER License) + +Building image +************** + +To build a Docker image, you have to provide a ``VERSION`` argument containing the ID of the Linux toolchain bundle you want to install. +You can use `print_toolchain_checksum.sh`_ to get ID proper for your |NCS| revision. + +.. code-block:: shell + + TOOLCHAIN_ID=$(../print_toolchain_checksum.sh) + docker build --build-arg VERSION=$TOOLCHAIN_ID + +Accepting JLink license +*********************** + +To install and use JLink software you have to accept `JLink License Agreement`_. + +If the container is run in an interactive mode, you will be asked to accept the license at the start of the container. + +You can also start the container with the ``ACCEPT_JLINK_LICENSE=1`` environment variable, and JLink will be installed without prompting. + +During post installation steps, JLink configures ``udev`` roles. +This operation requires running a container with the ``--privileged`` flag to grant permissions needed for the container. + +Running container +***************** + +Toolchain environment variables are set only in Bash sessions. +Outside the Bash session, these variables are not set, and tools delivered in the toolchain bundle cannot be found on the path. +|NCS| toolchain image uses ``bash`` command as entry point. +If the entry point is not overwritten, you can start your Docker container in both interactive and non-interactive mode. + +Locally +======= + +To run the |NCS| toolchain container to build and flash HEX files, run the following command. + +.. code-block:: none + + docker run -ti ghcr.io/nrfconnect/sdk-nrf-toolchain: -v /dev:/dev --privileged -e ACCEPT_JLINK_LICENSE=1 bash + +.. tip:: + + You can also add the ``-v :/ncs`` argument to the ``docker run`` command to mount the |NCS| project to the container. + In such cases, you might encounter issues with repositories, ownership, and west project configuration. + To resolve them, perform the following: + + * Run the ``git config --global --add safe.directory '*'`` command to mark mounted git repositories as trusted. + * Run the ``west update`` command to import west commands delivered in the |NCS| project (for example, ``west build``) + * Add ``--pristine`` argument to ``west build`` command to avoid path mismatch issues. + +In CI +===== + +CI systems usually run the Docker container in detached mode and can override the default entry point and command. +However, it is still possible to use the |NCS| toolchain images in pipelines. + +GitHub Actions +-------------- + +GitHub action starts container with overwritten default entry point. That means you have to set ``bash`` as a default shell to load all required environment variables. + +If the container is started with the ``ACCEPT_JLINK_LICENSE`` env variable set to ``1``, JLink will be installed just before the first bash command is executed. + +Example job configuration: + +.. code-block:: yaml + + jobs: + build-in-docker: + runs-on: ubuntu-22.04 + container: + image: ghcr.io/nrfconnect/sdk-nrf-toolchain: # steps in this job are executed inside sdk-nrf-toolchain container + env: + ACCEPT_JLINK_LICENSE: 1 # set if you want to install JLink + defaults: + run: + shell: bash # It is required to set `bash` as default shell + steps: + - name: Run command in NCS toolchain environment + run: "west --version" # This command is executed in bash shell `docker exec bash -c west --version` + # It will also install JLink if ACCEPT_JLINK_LICENSE is set to 1