Installation

← back to the handbook

Every new version of HORCOM appears on the GitHub releases page. Versions stay 0.x until the 1.0 release. Each release carries three downloads.

Windows

1. Download horcom-windows-x64.zip and unpack it into a folder of your choice, for example Documents\HORCOM.
2. Start horcom_gui.exe in that folder. The data folder must stay beside it.

Windows may warn about an unknown publisher on the first start. That is expected for a young open source program without a paid code signing certificate. Click More info, then Run anyway. To verify a download, compare the output of Get-FileHash horcom-windows-x64.zip in PowerShell with the line in SHA256SUMS.txt.

The program keeps your work in its own data folder, your defaults in the file konsta.int, and the file dialogs for your chart collections and place files open there. Unpacked to a folder you cannot write to, such as Program Files, it works in %LOCALAPPDATA%\horcom\data instead. To update, unpack the new release over the old folder, your own files are kept. To uninstall, delete the folder.

Linux

The AppImage is one self contained file, Qt and every library it needs travel inside, nothing is installed into the system.

chmod +x horcom-linux-x86_64.AppImage
./horcom-linux-x86_64.AppImage

In a file manager, open the file's properties, allow executing it as a program and double click it. To verify the download, run sha256sum -c SHA256SUMS.txt --ignore-missing in the download folder.

If the image does not start and mentions FUSE, the system lacks the old FUSE 2 library that AppImages mount themselves with. Install it (sudo apt install libfuse2t64 on Ubuntu 24.04, sudo apt install libfuse2 on Ubuntu 22.04 and Debian, sudo dnf install fuse-libs on Fedora), or start the image with --appimage-extract-and-run, which works everywhere.

Menu entry and updates

The image carries its own desktop entry and icon. A helper such as Gear Lever or AppImageLauncher files it into the application menu with one click and keeps it up to date, every release ships a .zsync file for delta updates. Without a helper, replace the file with a newer download, your own files are not stored inside it.

Where your files live

The shipped data inside the image is read only. On the first start the program copies its working files, about 1 MB, into the folder above and works there from then on. A later release adds new shipped files there but never overwrites one you already have. The planet tables and ephemeris files are always read from the image. To uninstall, delete the AppImage and, if you want to lose your files too, the two locations above.

Fonts

The sheets and tables are laid out in Courier New. Where it is missing, the program falls back to Liberation Mono, which has exactly the same character widths, so every column lines up as on Windows. The AppImage brings Liberation Mono along. Menu shortcut letters are underlined permanently on Linux, the usual convention there.

Building from source

This and the following section are for developers. To use HORCOM, the downloads above are all you need.

The library, the horcom command line tool and the tests need a C++20 compiler and CMake 3.25 or newer. The desktop shell horcom_gui additionally needs Qt 6 with Widgets, Svg, PrintSupport and the Linguist tools. Where Qt is absent the shell is skipped and the rest still builds. Warnings are errors on every compiler.

Windows

Install the Visual Studio 2022 Build Tools with the C++ workload, CMake, Ninja and Qt 6.8 for MSVC 2022 64 bit. build.bat in the repository root configures, builds and runs the tests in one go, it expects Qt in C:\Qt\6.8.3\msvc2022_64. By hand:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=C:/Qt/6.8.3/msvc2022_64
cmake --build build
ctest --test-dir build --output-on-failure --parallel 8

A shell built in the source tree finds the data folder of the repository, which is what every release ships. It never works in it. Like a read only install it copies its working files once into %LOCALAPPDATA%\horcom\data or ~/.local/share/horcom/data and keeps your KONSTA settings and own files there, so a session never changes the shipped files.

Linux

GCC 12 or newer and Clang 18 or newer both work, the distribution's own Qt 6 is enough. Install the tools for your distribution.

Then, from the repository root, ./build.sh configures, builds and runs the tests. Set QT_PREFIX to use a Qt outside the system, for example QT_PREFIX=~/Qt/6.8.3/gcc_64 ./build.sh. The programs land in build/apps and find the data folder of the checkout by themselves.

A system wide install follows the usual layout, the binaries in bin, the data in share/horcom/data, plus the desktop entry, the AppStream metadata and the icons. Distribution packagers stage it with DESTDIR.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local
cmake --build build
sudo cmake --install build

packaging/linux/appimage.sh builds the release AppImage itself, given a Qt prefix in QT_ROOT_DIR. Build it on the oldest distribution it should run on, its C library sets the floor, the release image is built on Ubuntu 22.04 with Qt 6.8.3.

Same numbers everywhere

Robert's advice to keep the computation order of the original binds the port, so the Linux build switches off the fused multiply add contraction that would let a compiler reorder his arithmetic. Before the Linux build was released, 600 randomised charts across all house systems, parallax, the extra bodies and dates from the year -500 to 3000 were computed with MSVC, GCC and Clang. Every coordinate table and every SVG wheel came out byte for byte identical on all three.