Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Add sdk nrf toolchain docker image #18512

Merged
merged 1 commit into from
Nov 5, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions doc/nrf/links.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions doc/nrf/scripts.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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/*
103 changes: 0 additions & 103 deletions scripts/docker/README.md

This file was deleted.

101 changes: 101 additions & 0 deletions scripts/docker/README.rst
Original file line number Diff line number Diff line change
@@ -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:<TAG> -v /dev:/dev --privileged -e ACCEPT_JLINK_LICENSE=1 bash

.. tip::

You can also add the ``-v <PATH-TO-NCS-PROJECT-ON-DOCKER-HOST>:/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:<TAG> # 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 <container> bash -c west --version`
# It will also install JLink if ACCEPT_JLINK_LICENSE is set to 1
Loading