Docker micro:bit Toolchain

Docker image with the micro:bit toolchain.

Useful to be able to compile C/C++ programmes using the DAL or CODAL micro:bit runtime, which includes projects like MicroPython. It can also be used to build the DAPLink project for the micro:bit interface chip.

Also includes a Docker image ready to be used with GitHub Codespaces and build your micro:bit projects on the cloud.

How to use this Docker image to build your micro:bit project

The Docker image is hosted in the GitHub Container Registry and can be fetch with this command:

docker pull ghcr.io/carlosperate/microbit-toolchain:latest

You can find more info about the image here: https://github.com/carlosperate/docker-microbit-toolchain/pkgs/container/microbit-toolchain

You can run this Docker image to build your project with a command like this:

docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest <build_command>

Where:

-v $(pwd):/home flag mounts your PC current working directory as a volume inside the docker container /home path, which is also the container default working directory
--rm flag will clean up the container created for the build
<build_command> should be replaced with whatever build command is needed for your project. For example, for a CODAL project that would be python build.py (info in their README)

Example: DAL (V1 C++ Samples)

The build steps from this example have been obtained from the project README.

# Clone the repository
$ git clone https://github.com/lancaster-university/microbit-samples
$ cd microbit-samples
# Build it using this docker image
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest yotta build

Example: CODAL (V2 C++ Samples)

The build steps from this example have been obtained from the project README.

# Clone the repository
$ git clone https://github.com/lancaster-university/microbit-v2-samples.git
$ cd microbit-v2-samples
# Build it using this docker image
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest python build.py

Example: MicroPython V1

The build steps from this example have been obtained from the project README.

# Clone the repository
$ git clone https://github.com/bbcmicrobit/micropython.git
$ cd micropython
# First prepare the project, this initial docker command only has to be run once
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest yt target bbc-microbit-classic-gcc-nosd@https://github.com/lancaster-university/yotta-target-bbc-microbit-classic-gcc-nosd
# Now we are ready to build it
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest make all

Example: MicroPython V2

The build steps from this example have been obtained from the project README.

# Clone the repository
$ git clone https://github.com/microbit-foundation/micropython-microbit-v2.git
$ cd micropython-microbit-v2
$ git submodule update --init
# First we prepare the project, this initial docker command only has to be run once
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest make -C lib/micropython/mpy-cross
# Now we are ready to build using the Makefile in the src folder
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest make -C src

Example: DAPLink for micro:bit V2

The build steps from this example have been obtained from the project developer's guide.

# Clone the repository
$ git clone https://github.com/mbedmicro/DAPLink
$ cd DAPLink
# Install the Python dependencies in a venv saved in the project directory
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest bash -c "pip install virtualenv && virtualenv venv && source venv/bin/activate && pip install -r requirements.txt"
# Activate the Python virtual environment and run the build script
$ docker run -v $(pwd):/home --rm ghcr.io/carlosperate/microbit-toolchain:latest bash -c "source venv/bin/activate && python tools/progen_compile.py -t make_gcc_arm kl27z_microbit_if"

How to use this Docker Image with GitHub Codespaces

This section of the docs is still a WIP.

Other General Docker Instructions

Build docker image

Build the docker image:

docker build -t "microbit-toolchain" .

Run a bash session

Run a bash session (launches a new container) from an existing docker image:

docker run --name microbit-toolchain-container -it --entrypoint /bin/bash microbit-toolchain

Copy files from docker to host

docker cp microbit-toolchain-container:/home/artefacts .