CopperSpice Overview
Building for Raspberry Pi

Building the CopperSpice libraries for the Raspbian operating system will require cloning from github. You can either checkout from the latest commit or sha 18D6E49.

CopperSpice GitHub

What is a Docker Image

There are several advantages of using a Dockerfile over storing a binary image. A Dockerfile allows rebuilding the operating system image and ensuring you have the latest versions of required packages.

A Dockerfile is a text document which contains a list of ordinary shell commands. These commands are used to configure and produce a new Docker image. A Docker image is basically a clean snap shot of an operating system. The shell commands in the Dockerfile are executed inside a temporary Docker Container and result is saved as a new Docker image. The Docker image is read only. When you run the Docker image this will create a Docker container.

  • Dockerfile Docker Image containing the OS
  • Start the Docker Image Docker Container where programs can be run

Programs like CMake and GCC are installed on the Docker Image. If you are installing a binary version of the CopperSpice libraries you may want to put this in the Docker Image. Your application source code is copied to the Docker Container. When you compile your application there is no need to specify what is on the Image versus what is on the Container. Any changes made to your source code are saved as part of the Container.

Creating a Docker Image

To build CopperSpice for Raspbian, the first step is to download the following Dockerfile. This file will be used to create a Debian 11 docker image.


These are the prerequisites for creating a Docker Image.

  • A computer running Linux
  • Install the Docker package
  • Access to a user account with root, sudo privileges, or permissions to run the Docker program

Use the following step to create a Docker image. The name cs-pi-image can be modified based on your preferences. The Dockerfile.pi should be in path-to-your-file with no other files.

docker build -t cs-pi-image -f path-to-your-file/Dockerfile.pi path-to-your-file

Running a Docker Image

Use the following step to start a Docker image and create a new Docker container. The -d runs the container in a detached mode which means it will keep running until manually stopped. The -t is required to allocate a terminal so a shell prompt can be opened in the container.

The name cs-pi-container can be modified based on your preferences. The name cs-pi-image must match the image name used when building the Docker image.

docker run -d -t --name cs-pi-container cs-pi-image

Use the following command to open a shell prompt in the container which is currently running.

docker exec -it cs-pi-container /bin/bash

Building CopperSpice

The shell commands listed below are used to fetch the CopperSpice source code and build the Raspberry Pi binary files in the Debian 11 Docker container. After everything is built there are two options. The first option is to copy the CS files located in ~/cs_pi_lib to the Raspberry PI and build your application on the device, Alternatively, build your application in the Docker container and then deploy your application to the Raspberry PI.

The first line sets the current directory to your Home directory. The second line will clone the CopperSpice repository on github and copy the files to ~/cs_pi_source in the Docker container.

Line 7 is the command to run CMake and configure the project. Lines 8 through 15 are CMake flags which adjust how the project will be set up and built. On line 14 we have turned off building CsWebkit since it is typically not used on embedded devices. For a list of other other CS libraries which can be turned off, refer to Build Options.

Line 15 indicates where the CopperSpice binaries will be installed and line 16 specifies where the project source code is located. Line 18 is required to install the binaries in c ~/cs_pi_lib.

1 cd ~
2 git clone cs_pi_source
4 mkdir cs_pi_build
5 cd cs_pi_build
7 cmake -GNinja \
8  -DCMAKE_CXX_FLAGS='-march=armv7' \
9  -DCMAKE_CXX_COMPILER=arm-linux-gnueabihf-g++-10 \
10  -DCMAKE_C_FLAGS='-march=armv7' \
11  -DCMAKE_C_COMPILER=arm-linux-gnueabihf-gcc-10 \
12  -DPKG_CONFIG_EXECUTABLE='/usr/bin/arm-linux-gnueabihf-pkg-config' \
13  -DCMAKE_BUILD_TYPE=Release \
15  -DCMAKE_INSTALL_PREFIX=~/cs_pi_lib \
16  ../cs_pi_source
18 ninja install

The following commands are used to build and run the CopperSpice Catch tests. Starting with the code from above, replace lines 7 through 18 with the commands shown below. Line 8 will turn on the Catch tests and line 13 will build a limited set of the CS libraries and tools. The call to ctest on line 14 will run the tests.

1 cmake -GNinja \
2  -DCMAKE_CXX_FLAGS='-march=armv7' \
3  -DCMAKE_CXX_COMPILER=arm-linux-gnueabihf-g++-10 \
4  -DCMAKE_C_FLAGS='-march=armv7' \
5  -DCMAKE_C_COMPILER=arm-linux-gnueabihf-gcc-10 \
6  -DPKG_CONFIG_EXECUTABLE='/usr/bin/arm-linux-gnueabihf-pkg-config' \
10  -DCMAKE_INSTALL_PREFIX=~/cs_pi_lib \
11  ../cs_pi_source
13 ninja CsCoreTest
14 ctest