Development Setup

This section describes how someone wanting to contribute to the libCellML project should set up their working copy for developing libCellML.


The libCellML codebase is hosted on GitHub and therefore Git is used to track changes. Before you begin, you will need to have a few pre-requisites satisfied:

  1. GitHub user account (for the rest of this document we will call our user andre).
  2. Git.
  3. CMake.
  4. Toolchain for building software (dependent on the operating system).
  5. LibXml2.

Some optional tools can also be used to speed up compilation:

  1. Ninja.
  2. clcache (on Windows) / ccache (on Linux and macOS).

Pre-requisite acquisition

In this section, we cover the retrieval and installation of pre-requisites.


Creating a GitHub user account is straightforward and can be done here. Installing a Git client is particular to each operating system and some pointers are offered below:

  • Windows Git is available from a variety of vendors.

We commonly use Git for windows, but other popular Git implementations are:

  • Ubuntu (and other Linux distributions) Git can be installed using the package manager with the command sudo apt install git.
  • macOS Git is pre-installed and available from the command line.


CMake is the cross-platform family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and to generate native makefiles and workspaces that can be used in the compiler environment of your choice.

Again, installation of CMake is particular to each operating system. For Ubuntu (and other Linux distributions), CMake can be installed using the package manager with the command sudo apt install cmake. For Windows and macOS, CMake provides installation binaries. Choose the binary appropriate for your operating system and follow the installation instructions.


The toolchain specifies the compiler that we will use to build libCellML. Toolchains are highly dependent on the operating system. When we test libCellML, we currently use Visual Studio on Windows, GCC on Ubuntu, and Clang on macOS. We recommend using these compilers on these systems, but feel free to use a different toolchain. We sometimes use the Intel C++ compiler to build libCellML, but we do not (at the time of writing) test with it.

The following sub-sections provide guidance on how to install the recommended toolchain on the major operating systems that libCellML supports.


Visual Studio is available to download from here. We currently test with Visual Studio 2015 (version 14), but later versions are known to work. The Community edition is more than sufficient for the needs of libCellML. To minimize the size of the installation, you may install only the C++ compiler. This component (and its requirements) is sufficient for building libCellML.


LibXml2 is already installed on macOS, so no further action is required on that platform. On Windows, we must install LibXml2 using the recommended implementation available from here while on Ubuntu LibXml2 can be installed using sudo apt install libxml2-dev.

Python bindings

Optional Python bindings are provided using SWIG. To compile the bindings, a SWIG installation is required, as well as a Python 2 or Python 3 installation (including the development packages on Linux systems, e.g. python-dev). Creation of Python bindings can be enabled/disabled at configuration time.

Optional tools


Ninja is a replacement for make. It can be downloaded from here. Alternatively, on Ubuntu (and other Linux distributions), it can be installed using the package manager with the command sudo apt install ninja-build. On macOS, it can be installed using Homebrew with the command brew install ninja.

clcache / ccache

clcache (on Windows) and ccache (on Linux and macOS) are compiler caches. They cache compilations, which means that the first time they are used, compilation will be slower than normal. However, subsequent compilations will be significantly faster.

clcache can be downloaded and installed from here. Note that it will only work with paths that do not contain spaces. So, if you installed the recommended implementation of LibXml2, you will need to move it to a location that does not contain spaces and update your PATH accordingly (or uninstall LibXml2 and reinstall it in a PATH that does not contain spaces).

On Ubuntu (and other Linux distributions), ccache can be installed using the package manager with the command sudo apt install ccache. Alternatively, you can get the latest version from here, and build it and install it yourself:

./configure --prefix=/usr
make -j
sudo make install

On macOS, ccache can be installed using Homebrew with the command brew install ccache.

Setting up the codebase

The remainder of this document assumes that the above pre-requisites have been met. It covers setup from the command line. If you are using a GUI like GitHub Desktop then you will need to adjust the commands for the GUI you are using.

The goal here is to get a working copy of source code, tests, and documentation onto your computer so that you can begin development. To make this happen, you will need to fork the prime libCellML repository, make a clone onto your computer, and set up the Git remotes. In fig_devSetup_githubRepos, you can see a pictorial representation of what we are aiming to achieve.

Setup of Git repositories.

Setup of repositories for development.

The four steps to getting set up are detailed below.

Forking your own copy

Login to GitHub using your credentials and go to

Use the fork button to create a libcellml repository under your own account, see fig_devSetup_githubFork for locating this button.

Fork button of libCellML repository.

Fork button for libCellML repository.


You now need to clone the libCellML repository to your computer. You do this by going to your fork (in this example user andre’s fork) at


Do not try and clone this location substitute your GitHub username for andre. In all likelihood, it does not exist.

On the right hand side of the webpage, on your fork of the repository, you can get the link for cloning the repository to your computer, in our example:

Now clone the repository:

cd <somewhere/you/keep/development/code>
git clone

Note: again, do not clone this location substitute your GitHub username for andre.

Set Git remotes

You now need to setup a read-only remote connection to the prime libCellML repository. Given that you are still in the directory where you cloned the libCellML repository from, do the following:

cd libcellml
git remote add prime
git config "You really did not want to do that!"

You have now added a new remote named prime and set origin as the default fetch and push location to point at repositories under your control on GitHub. Here, prime is a reference to the main definitive repository where releases are made from for the libCellML project. You have also set the prime repository as read-only by setting an invalid push URL.


You are all done and ready to start development, read Building on how to build libCellML. Then, read Contribution to get your changes into libCellML’s prime repository.