Building From Source

This document covers in detail how to build chordcat from source.

Introduction

Chordcat depends on the following libraries:

You will also need CMake and a modern C++ compiler that supports C++20 (gcc, clang, etc.)

CMake will fetch and build some of these dependencies from source while building chordcat. See the next sections for installation of the required dependencies.

In order for CMake to be able to build chordcat, you will need to install these libraries on your system. Libraries which are not commonly available on most systems (like libremidi, ImGui and ImGui-SFML) will be fetched and built by CMake as part of the build process.

Linux

On debian-based systems, the compiler toolchain can be installed with:

sudo apt install cmake build-essential

And the dependencies with:

sudo apt install \
    libsfml-dev \
    fluidsynth \
    libfluidsynth-dev \
    nlohmann-json3-dev

The midi functionality of chordcat is provided by libremidi. libremidi can work with several backends such as ALSA, JACK, PipeWire, Pulse, etc. For libremidi to work with said backends, the development libraries for that particular backend needs to be installed.

JACK

If you use JACK as your audio server and want chordcat to be able to use JACK for midi, you will need to have the jackd2 development package installed. libremidi will automatically detect it and will be built with JACK support.

On debian-based systems, you can install it using the command:

sudo apt install libjack-jackd2-dev

You can also install jack-keyboard if you do not own a midi controller. This can be particularly useful for development.

PipeWire

PipeWire support in libremidi is experimental (as of v4.5.0). We highly recommend that you stick with ALSA or JACK unless you are a hardcore user.

You will need to have the PipeWire development libs installed to build chordcat with PipeWire midi support.

On debian-based systems, you can install it using the command:

sudo apt install libpipewire-0.3-dev # on debian bookworm

ALSA

You will need to have the ALSA development libs installed to build chordcat with ALSA midi support.

To install the ALSA development libraries on debian-based systems:

sudo apt install libasound2-dev

PulseAudio

You will need to have the Pulse development libs installed to build chordcat with PulseAudio midi support.

To install the Pulse development libraries on debian-based systems:

sudo apt install libpulse-dev

Building

Once you have all the dependencies you need for your system, build and run chordcat with:

cd chordcat
mkdir build && cd build
cmake ..
make -j$(nproc)
./chordcat

MacOS

NOTE: This has been tested with arm64 macs only. There might be some linking issues with fluidsynth when used with Intel macs.

You can install git and clang++ (which will be symlinked to /usr/bin/gcc lol) with:

xcode-select --install

You will also need to install Homebrew in order to download dependencies. Check their official page for instructions on how to install brew.

You can then download chordcat's dependencies with:

brew install cmake \
    sfml \
    fluid-synth \
    nlohmann-json

Build and run chordcat with:

mkdir build && cd build
cmake ..
make -j$(nrpoc)
./chordcat

Windows

It is recommended that MSYS2 be used for building chordcat on Windows as it is relatively straightforward to do it this way. While it is also possible to build chordcat with Visual Studio, doing so might involve several complexities and may demand a lot of effort.

Installing MSYS2

If you do not have MSYS2 installed, you can get it using Winget which comes with Windows 11.

winget install MSYS2.MSYS2

Once MSYS2 is installed, you can open the MSYS2 UCRT64 app which will take you into a shell (bash).

You can copy and paste the below commands. On the MSYS2 UCRT64 app, shift+ins might be the paste key combo.

Sync and upgrade your packages using:

pacman -Syu

You can also install git if you wish

pacman -S git

Installing Dependencies

You will need the following dependencies to build chordcat. You can install them on MSYS2 with this command.

pacman -S mingw-w64-ucrt-x86_64-gcc \
    mingw-w64-ucrt-x86_64-cmake \
    mingw-w64-ucrt-x86_64-sfml \
    mingw-w64-ucrt-x86_64-fluidsynth \
    mingw-w64-ucrt-x86_64-nlohmann-json

You can also install mingw-w64-ucrt-x86_64-nsis if you wish to create an installer for windows. As of now, making a working installer will involve copying all the required DLLs from /ucrt64/bin/ into the cmake build folder. Skip this if you do not wish to create an installer and just want to run chordcat.

Building chordcat

Clone or download-zip-and-extract chordcat into the MSYS2 filesystem.

git clone https://github.com/shriramters/chordcat.git
cd chordcat

Configure with CMake:

mkdir build && cd build
cmake ..

CMake should have generated the Ninja files now. Build and run chordcat.exe with:

cmake --build .
./chordcat.exe

You can't run this generated chordcat.exe from Windows Explorer as the required DLLs are all in /ucrt64/bin/. MSYS2 bash knows to look for these DLLs here but Windows doesn't. So, if you don't want to run this from the terminal everytime, you can copy all the required DLLs from /ucrt64/bin/ to the cmake build folder.