Building Cahute from source

It is recommended to install Cahute using one of the methods in Installing Cahute. However, if Cahute is not available for your system, or if you wish to build it manually, this guide is for you.

Cahute depends on the following build-only dependencies:

It also depends on the following build and runtime dependencies:

In order to get the current released version of the Cahute source, you have the following options:

  • You can download the latest source package at https://ftp.cahuteproject.org/releases:

    curl -o cahute-0.5.tar.gz https://ftp.cahuteproject.org/releases/cahute-0.5.tar.gz
tar xvaf cahute-0.5.tar.gz

  • You can clone the repository and checkout the tag corresponding to the release:

    git clone https://gitlab.com/cahuteproject/cahute.git cahute-0.5
(cd cahute-0.5 && git checkout -f 0.5)

The project is present in the “cahute-0.5” directory.

Note

Since you will not be using a packaged version of Cahute, the project won’t be automatically updated when updating the rest of the system, which means you will need to do it manually, especially if a security update is made.

You can subscribe to releases by creating a Gitlab.com account, and following the steps in Get notified when a release is created. You can check your notification settings at any time in Notifications.

linux Linux distributions

In order to install the dependencies, it is recommended you use your native package manager. A few examples are the following:

  • On Debian and derivatives:

    sudo apt-get update
sudo apt-get install cmake python3 python3-toml libusb-1.0-0-dev libsdl2-dev

  • On Archlinux and derivatives:

    sudo pacman -Sy cmake python python-toml libusb sdl2

  • On Voidlinux and derivatives:

    xbps-install cmake python3 python3-toml libusb-devel sdl2-devel

In the parent directory to the source, you can now create the build directory aside it, and install from it, by running the following commands:

cmake -B build -S cahute-0.5 -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release
cmake --build build

Note

If you want to install Cahute on your system directly, you can use the following command:

sudo cmake --install build --strip

If, however, you want to install the result into a given directory, you can use the following command:

DESTDIR=./dist cmake --install build --strip

Warning

For communicating with calculators over USB and serial, Cahute library and command-line utilities require access to such devices.

For serial devices, this is traditionally represented by being a member of the uucp group, defined as the group owner on /dev/ttyS* devices; you can check this by running ls -l /dev/ttyS*. However, by default, USB devices don’t have such rules.

CMake automatically installs the udev rules, which means you need to do the following:

  • Reload the udev daemon reload to apply the newly installed rules on the running system without a reboot, with this command as root:

    udevadm control --reload

  • Adding your user to the uucp group, then restarting your session:

    usermod -a -G uucp <your-username>

apple macOS, OS X

In order to install the native dependencies, it is recommended you use Homebrew:

brew install cmake pkg-config python@3.12 libusb sdl2

You must also install the Python dependencies, by going to the parent directory to the source, and creating a virtual environment within build/venv using the following commands:

python3 -m venv build/venv
source build/venv/bin/activate
python -m pip install toml

You can now initialize the build directory by running the following command:

cmake -B build -S cahute-0.5 -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release

Warning

The build initialization command must be run in the same shell as the one where the Python venv was initialized.

If you have created a new shell, you must run the following command beforehand:

source build/venv/bin/activate

Now that the build directory has been initialized, you can build using the following command:

cmake --build build

Note

This can be run in any shell, provided you adapt the path to be absolute or relative to the current directory (e.g. cmake --build . if within the build directory), and the Python venv does not need to be activated beforehand since CMake remembers it must use it.

mingw-w64 Windows XP and above, from Linux distributions

Warning

Both Windows XP and above as a target and this build method are not officially supported yet.

See 10 for more information.

Building Cahute for Windows XP and above from Linux distributions using MinGW-w64 is possible, as described in Cross Compiling With CMake. The instructions depend on the Linux distribution you are building from; these exact instructions are for Archlinux.

You need to first install the required dependencies from the AUR, by using your favourite AUR helper, e.g. with paru:

paru -S python python-toml mingw-w64 \
    mingw-w64-cmake mingw-w64-libusb mingw-w64-sdl2

In the parent directory to the source, you can now create the build directory aside it, by running either one of the following command depending on the architecture you’re targetting:

i686-w64-mingw32-cmake -B build -S cahute-0.5
x86_64-w64-mingw32-cmake -B build -S cahute-0.5

You can now build the project using the following command:

cmake --build build

Before testing with either Wine or a Windows host, it is recommended to copy the required shared libraries to the build directory, by running either one of the following command depending on the architecture you’re targetting:

cp /usr/i686-w64-mingw32/bin/{libssp-0,SDL2,libusb-1.0}.dll .
cp /usr/x86_64-w64-mingw32/bin/{libssp-0,SDL2,libusb-1.0}.dll .

Warning

In order for Cahute to be usable on Windows XP, you need to use a previous release of libusb as system requirements have been upgraded.

libusb 1.0.23 has been proven to work in such cases. The DLLs can be found in the libusb-1.0.23.7z archive, more specifically in the MinGW32/dll and MinGW64/dll directories.

Note

For reference, this build method is used in the MinGW build image for Cahute, which is exploited in the project’s continuous integration pipelines as described in .gitlab-ci.yml.

amigaos AmigaOS 3.2 and above, from Linux distributions

Warning

Both AmigaOS 3.2 and above as a target and this build method are not officially supported yet.

See #26 for more information.

Building Cahute for AmigaOS 3.2 and above from Linux distributions using m68k-amigaos-gcc, including the Native Development Kit (NDK), as described in Cross Compiling With CMake.

You need to first install m68k-amigaos-gcc and all available tools, using instructions present in the m68k-amigaos-gcc README.

Warning

Unfortunately this may not come easy, and there is no issue tracker with the project. Good luck!

This section assumes the toolchain is installed in /opt/amiga, as set by default. You must also download m68k-amigaos.cmake on your system, and prepare the absolute path to it.

You can now create the build directory aside the source directory, by running the following command:

cmake -B build -S cahute-0.5 -DCMAKE_TOOLCHAIN_FILE=/path/to/m68k-amigaos.cmake -DTOOLCHAIN_PREFIX=m68k-amigaos -DTOOLCHAIN_PATH=/opt/amiga

You can now build the project using the following command:

cmake --build build

Warning

p7screen will not be included, since it requires SDL2 which is not available with the AmigaOS 3.2 toolchain.

win Windows XP and above, using Visual Studio

Warning

Both Windows XP and above as a target and this build method are not officially supported yet.

See #10 for more information.

It is possible to build Cahute for Windows XP and above, using Microsoft’s Visual Studio starting from version 17.6 (VS2022).

Warning

Visual Studio is not to be confused with Visual Studio Code, which is an entirely different program.

Note

This version of Visual Studio is targeted since it is the first to include vcpkg (source). It may be possible to compile Cahute on earlier versions of Visual Studio; see Install and use packages with CMake for more information.

When opening Visual Studio, select “Clone a repository” (first option).

../_images/msvs1.png

Initial window for Visual Studio, with the first option selected.

Enter the URL of the repository you’re cloning (https://gitlab.com/cahuteproject/cahute.git if cloning the upstream), and select “Clone”.

../_images/msvs2.png

Repository cloning window, with the information filled out to clone the main branch on the official project repository.

Note

The IDE may open to nothing much, such as in this example:

../_images/msvs3.png

Empty IDE windows, obtained after cloning the repository.

In this case, double-clicking on “Directory view” in the Solution Explorer on the right should solve this.

Once the repository is loaded, the IDE should automatically prepare the repository for building using CMake and vcpkg. The resulting view should resemble this:

../_images/msvs4.png

Visual Studio, after the repository was successfully loaded and configured.

Warning

You may have the following error when configuring the project using CMake:

Could NOT find PkgConfig (missing: PKG_CONFIG_EXECUTABLE)

This is likely, in fact, an error with the vcpkg integration with Visual Studio, as by default, packages are not installed and accessed. In order to do this, as described in Installing and using packages (vcpkg), you can either:

  • Integrate vcpkg for all projects with Visual Studio, by running vcpkg integrate install;

  • Only enable vcpkg by setting CMAKE_TOOLCHAIN_FILE manually in the CMakeSettings.json to your vcpkg install’s vcpkg.cmake.

From here, you can select the target you want to build next to the green arrow on the top, and the architecture you’re targetting. By leaving the default (x64-Debug) and clicking on p7.exe, we obtain the following:

../_images/msvs5.png

Visual Studio, after building and running p7.

Since Cahute defines mostly command-line utilities, it may be more interesting to have access to a command-line interface. In order to this, in the context menu, select “Tools”, “Command line”, then “Developer Powershell”:

../_images/msvs6.png

Visual Studio, with contextual menus opened up to “Developer Powershell”.

A console should open at the bottom of the IDE. In this console, use cd to go to the build directory (by default, .\out\build\<target>), and run the command-line utilities from here with the options you want to test.

../_images/msvs7.png

A PowerShell developer console opened in Visual Studio, running p7 from the build directory directly.