Installing and Building CopperSpice

February 23, 2020

CopperSpice, • C++

Introduction

The previous post introduced the CopperSpice project. In this post I will explain how to install the prebuilt binaries and also how to build CopperSpice from source. At this point we can build a simple application using two of the CopperSpice libraries.

I primarily use Arch linux and prefer working with an installation built from source. This set-up allows me to easily make changes to the libraries and contribute pull requests. Since I contribute to CopperSpice, this blog will focus more on the process of building CS from source.

Downloading and installing a binary distribution

Let's start with the simplest option, downloading and installing a binary distribution. Download the package for your unix platform and extract it to a location of your choosing.

  mkdir -p projects/cs/install
  cd projects/cs/install
  wget https://download.copperspice.com/copperspice/binary/cs-1.6/copperspice-1.6.2-arch-x64.tar.bz2
  tar -jxf copperspice-1.6.2-arch-x64.tar.bz2

If you are using the prebuilt binaries, I suggest you verify your build environment matches the CopperSpice project. The supported platforms page of the overview documentation shows the exact versions of the toolchains that were used. Feel free to try other versions if you are so inclined and let us know how it goes.

Building from source

For readers that are interested in contributing to CopperSpice, building from source is the right starting point.

We begin with cloning the CS repository and moving to the new directory.

  cd projects/cs/
  git clone https://github.com/copperspice/copperspice.git
  cd copperspice

The next step is to check out the tag for the current release of CopperSpice.

  git checkout cs-1.6.2

It is also possible to download a source distribution of CopperSpice.

CopperSpice is built using CMake. When building a project with CMake the best approach is to use a separate directory. This ensures all build configuration is stored under that directory. It is also possible to have multiple build directories, for example if you want to have both a release and a debug build.

  mkdir build
  cd build

By default CMake will configure the project to build all the CopperSpice libraries and set the installation prefix to /usr/local. When building a project from source it is better to pick a different installation prefix, for example projects/cs/install. Using separate distinct prefixes allows you to install multiple versions. The prefix is specified on the command line by defining -DCMAKE_INSTALL_PREFIX=my/prefix/path.

I am using the ninja generator. If you leave out the -GNinja flag, CMake will generate GNU Makefiles.

Throughout this series we will use several of the CopperSpice libraries, but not all of them. To save some time I have turned off the libraries we won't be using in the command line below. The overview documentation also documents build flags. When building the libraries ensure you have all the required dependencies installed. These are listed on the requirements page in the overview documentation.

  cmake ../ -GNinja      \
    -DWITH_WEBKIT=0      \
    -DWITH_XMLPATTERNS=0 \
    -DWITH_SCRIPT=0      \
    -DWITH_MULTIMEDIA=0  \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=.../path/to/projects/cs/install

The project is now configured and we can invoke ninja or make to build. By typing the command ninja the source will be built and the libraries created, if we type ninja install we build and immediately install the compiled libraries at the configured installation prefix.

Hello from CopperSpice

Our first CopperSpice application will show a MessageBox with the text "Hello from CopperSpice" and a button. When the button is clicked the window closes and the application exits. The purpose of this application is to verify your CopperSpice installation is correct and to show how easy it is to get started. All of the code for these posts can be found on GitHub.

The API documentation contains extensive information on all the classes in CopperSpice. There are also many examples and code snippets, which are a great way to experiment with CopperSpice beyond our small application.

Project set-up

I like to follow the Pitchfork directory layout for C++ projects, so I will stick to that for our application.

  mkdir -p CsHelloWorld/{src,build}
  cd CsHelloWorld
  touch CMakeLists.txt
  touch src/main.cpp

The contents of the CMakeLists.txt file is shown in the following listing. Certain platform specific pieces of functionality are implemented through plugins in CopperSpice. These are loaded by the application when it starts. We install the libraries and plugins required by our application next to the binary so they can be found easily. The overview documentation has documentation on plugins in CopperSpice as well as a list of the available plugins.

The cs_copy_library and cs_copy_plugins functions, respectively copy the library and plugin passed as the argument to the correct location. The overview documentation describes deployment in more detail.

  project(HelloWorldCS)

  cmake_minimum_required(VERSION 3.8)

  set(CMAKE_CXX_STANDARD 17)
  set(CMAKE_CXX_STANDARD_REQUIRED ON)

  find_package(CopperSpice REQUIRED)

  # Setting the rpath to '$ORIGIN' ensures our application looks for the
  # CopperSpice libraries and plugins in its own directory first.
  set(CMAKE_INSTALL_RPATH "\$ORIGIN")

  add_executable(HelloWorldCS src/main.cpp)

  target_link_libraries(
    HelloWorldCS
    CopperSpice::CsCore
    CopperSpice::CsGui
  )

  install(TARGETS HelloWorldCS DESTINATION ${CMAKE_INSTALL_PREFIX})

  # Copy the libraries and plugins necessary for our application to our install path.
  cs_copy_library(CsCore)
  cs_copy_library(CsGui)

  cs_copy_plugins(CsGui)

The following listing is the source code for src/main.cpp.

#include <QApplication>
#include <QMessageBox>

int main(int argc, char** argv)
{
  // All CopperSpice applications must create a QApplication object.
  QApplication app(argc, argv);

  auto dialog = QMessageBox();
  dialog.setText("Hello from CopperSpice");

  // Show our dialog and exit returning the result.
  return dialog.exec();
}

Building the application

To build our application two steps are required. Both can be done through the CMake command line interface. The first step is configuring the project and the second is building and installing the compiled application (including the required plugins and libraries).

cd build/
cmake ../ \
      -DCMAKE_PREFIX_PATH=path/to/projects/cs/install/lib64/cmake \
      -DCMAKE_INSTALL_PREFIX=./install
cmake --build . --target install
cd ./install
./HelloWorldCS

When you run the application it will output diagnostic information on the console. If you followed the described steps you will see a window appear with a welcome message and a button.

Awesome, you are now a GUI programmer!

You just built your first CopperSpice GUI app using C++17 and CMake, congratulations! In the next posts we will look at interactions between widgets using signals and slots, designing your UI, networking and much more.

For more information, be sure to read the overview documentation and the API documentation. Feel free to ask any CopperSpice questions on the support forum.