In software the term toolchain refers to the programs or utilities used to create an application or library. For an introduction on toolchain terminology refer to our Journal entry.  Definition of a Toolchain

The CopperSpice libraries are built using the CMake build system.

The CMake program uses the project build files and information about the system you are building on to create Ninja files which are customized for your configuration. There are several configuration options which can be applied when running CMake. Refer to Build Options for a list of supported options.

The Ninja program then reads the files CMake generated and invokes your compiler and linker to produce a binary of the CopperSpice libraries. The same process applies to building user applications.

For a list of the supported platform specific compiler versions refer to the Supported Platforms table.

CMake

CMake version 3.18 or newer is required. For additional information about CMake refer to the CMake website.  CMake

Ninja

The CopperSpice project uses Ninja to build the CopperSpice libraries and our C++ applications. Ninja was selected since it is slightly faster than Make and provides better support on more platforms.

A binary executable of Ninja can be downloaded directly from github.  Ninja Binary Release

For directions about building from source refer to this link on our CopperSpice website.  Build from Source

Directory Separator

This information is extremely important because CopperSpice is used on multiple operating systems. Specifying a file path is not the same on every platform and some developers may even use different terminology.

On Windows the directory or file separator is a backslash and on Unix the file separator is a forward slash.

There are historical reasons which explain why these differences exist. In the early days of Windows the forward slash was used as the "command line switch character". The file system in MS-DOS 2.0 added support for directories which meant they needed a directory separator. The choice was made to use a backslash for the separator since the forward slash already had a defined meaning.

In this documentation we have selected to use the Unix syntax, which is also used on Mac OS X.

When developing on Windows with MinGW, you will need to use Bourne Shell. Instead of a batch file scripts are used and they require the Unix directory separator, namely a forward slash.

For developers using MSVC (Windows) after reading the sections below, refer to Building for Windows (MSVC).

How to Build

The following table is our suggested setup of folder names, there is no requirement to use this exact structure. For consistency the examples in this documentation will use our preferred directory names.

The CopperSpice source code is located in cs_source directory. The CMake and Ninja files will be generated during the build process and saved in the cs_build directory, which you need to create. The cs_lib directory will be created automatically during the Ninja install step.

The build process consists of three steps.

Step 1:   Configure

The following command must be run in the cs_build directory. It will configure CopperSpice for a release version, install CopperSpice in the cs_lib directory, and look for source code in the cs_source directory.

If you need to pass any CFLAGS or CXXFLAGS they can be set in your environment or passed on this command line. There may also be additional options which are required on your system to find various third party libraries. Refer to Build Options for a partial list.

Note

In the previous script /c/cs_source and /c/cs_lib can be changed to an absolute or relative path.

• On Windows with MSVC c:\cs_source may be preferred
• On Unix ~/cs_source syntax may be preferred

Step 2:   Compile

CopperSpice is compiled and linked by running the following command in the cs_build directory.

Step 3:   Install

To install CopperSpice run the following command from the cs_build directory

Using a Script to Build CopperSpice

As an alternative a bash script can be created and store the required commands. This script is run from the cs_build directory. If there are warnings or errors they will be shown in the bash window and CMake will exit if this configuration step fails.