Building the CopperSpice libraries for the Raspbian operating system requires either cloning the github repository or downloading the source code from github or our download website.

CopperSpice GitHub
Download Site

Building Binaries

The CPU on a Raspberry Pi is not adequate to build large applications or libraries. The most effective way to build the binary files for CopperSpice is to use a Docker container running Debian to cross compile for the Raspbian operating system.

Docker Images and Containers

A Dockerfile is used to rebuild the operating system image and ensure you have the latest versions of required packages.

A Dockerfile is a text document which contains a list of shell commands. Executing these commands will configure and then create a new Docker image. The shell commands are actually run inside a temporary Docker container and the result is saved as a new Docker image. A Docker image is a clean installation of some operating system and is read only.

Running or starting a Docker image will create a new Docker container. The OS and all services or daemons listed in the image will be started as part of the container creation process. The container can be used to run programs in the same way as a normal computer.

• Dockerfile ➔ Docker Image

• Start the Docker Image ➔ Docker Container

Creating a Docker Image

Programs like CMake, Ninja, GCC, or clang can be listed in the Dockerfile and will be embedded in the Docker Image. These applications can only be run from within the container.

If you are using a Docker container to build applications which will link with the CopperSpice libraries you should add the binaries to the Docker Image. Your application source code can be copied to the container once it is running. Another option is to mount the source code directory located on your local computer, inside the container. You can then use the container to build, develop, and test your software.

Docker Setup to Build CopperSpice for Raspbian

The build process will require a host computer running Linux. You will need access to a user account with root, sudo privileges, or permissions to run the Docker program. The next step is to install the Docker program which should be available as a package from your Linux vendor.

(1)   To create the Docker Image download the following Dockerfile to the host computer.

Dockerfile.pi

(2)   This command is used to create the Docker image on the host computer. The image name cs-pi-image can be modified based on your preference.

(3)   Now we want to start the Docker image and create a new Docker container.

The -d creates 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 preference. The name cs-pi-image must match the image name used when building the Docker image.

(4)   The container should now be running. To build for Raspbian we need to enable ARM emulation on the host kernel.

(5)   Use the following command to open a shell prompt inside the container.

Building CopperSpice for Raspbian

The shell commands shown below are used to check out the CopperSpice source code and build the Raspberry Pi binary files. The build process will happen inside the Debian 11 Docker container created in the prior steps. After the binary files have been built there are two ways to build your application.

(1) You can copy the CS binary files located in ~/cs_pi_lib to your Raspberry Pi device and then build your application on the device.

(2) Alternatively, you can build your application in the Docker container and then deploy your application to the Raspberry Pi device.

Explanation of the shell commands to build for Raspbian.

• Line 1 sets the current directory to your Home directory.

• Line 2 clones the CopperSpice repository from 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 define various CMake flags which adjust how the project will be configured and built.

• Line 14 disable the CsWebkit library since it is typically not used on embedded devices. For a list of other other 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 ~/cs_pi_lib.

The final set of commands are used to build and run the CopperSpice Unit Tests. Use the code from above but 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 unit tests.