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:
cmake >= 3.16;
Python >= 3.8;
toml module for Python, either installed through pip or as a native package such as
python-toml
orpython3-toml
;GNU Make, pkg-config, and other C compilation and linking utilities.
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 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>
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.
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 #32 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 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.
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.
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).
Enter the URL of the repository you’re cloning
(https://gitlab.com/cahuteproject/cahute.git
if cloning the upstream),
and select “Clone”.
Note
The IDE may open to nothing much, such as in this example:
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:
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:
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”:
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.