CopperSpice Overview
Overview of the Build Process

CopperSpice is built using the CMake build system.

The CMake program uses our 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 reads the files CMake generates and invokes your compiler and linker to produce a binary of the CopperSpice libraries.

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


CMake

CMake version 3.16 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.

// Windows
c:\Program Files
// Unix
/usr/bin

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.

Description Directory Name
CopperSpice Source cs_source
CopperSpice Build cs_build
CopperSpice Install cs_lib

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. If you need to pass any CFLAGS or CXXFLAGS they can be set in your environment or passed on this command line.

There are several additional options which may be required on your system to find various third party libraries. Refer to Build Options for a partial list.

cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/c/cs_lib /c/cs_source

 

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.

ninja

Step 3:   Install

To install CopperSpice run the following command from the cs_build directory

ninja install

Using a Script

As an alternative a bash script can be created and store the required commands. You need to run this script from the cs_build directory. Please be aware that this script will print an error message and then exit if the CMake configuration step fails to complete successfully.

1 # add next line to enable building the unit tests
2 # export CMAKE_FLAGS="-DBUILD_TESTS=on -DCMAKE_PREFIX_PATH=/c/Catch2/lib/cmake/Catch2"
3 
4 # add to build this plugin
5 # export PostgreSQL_ROOT="/c/Program Files/PostgreSQL/10"
6 
7 
8 if ! cmake -G "Ninja" $CMAKE_FLAGS \
9  -DCMAKE_BUILD_TYPE=Release \
10  -DCMAKE_INSTALL_PREFIX=/c/cs_lib /c/cs_source ; then
11 echo -e "\n\e[41m Configure CMake FAILED \e[49m\n"
12 exit 1
13 fi
14 
15 ninja
16 ninja install