Build from source¶

Valerian is free software under the GPLv3 and the whole source is public, so you can build it yourself on any supported system. This page takes you from nothing to working valerian and valerian-gui programs. If you would rather not build, ready-made installers are sold on 12hobbies.studio (that page is coming soon while the store is set up); see Get Valerian.

You get two programs:

• valerian, the command line tool (which also runs the API server);
• valerian-gui, the desktop app.

What you need¶

Get the source:

git clone https://github.com/qisback/valerian.git
cd valerian

To build a released version, check out its tag afterwards (git tag lists them), or download the source archive of that tag from the repository's releases page.

Windows 10 and 11¶

1. Install the Visual Studio Build Tools (2022 or newer) with the workload "Desktop development with C++". Rust needs the Microsoft linker and the Windows SDK. For a Windows on Arm machine also tick the "MSVC ARM64 build tools" component.
2. Install Rust with rustup-init.exe from rustup.rs. The default host is x86_64-pc-windows-msvc; on Windows on Arm choose aarch64-pc-windows-msvc. The project's own builds and tests are x86-64; the Arm build is expected to work but is not tested by the project.
3. Install Git for Windows and clone the source as above.
4. In a terminal, in the checkout:

cargo build --release --locked -p valerian-cli -p valerian-gui

The programs are target\release\valerian.exe and target\release\valerian-gui.exe. Your graphics driver provides DX12 or Vulkan. If a corporate policy blocks programs built inside the checkout (Windows Application Control can refuse build scripts), point CARGO_TARGET_DIR at a folder the policy allows.

macOS (Apple silicon and Intel)¶

1. Install the Xcode command line tools: xcode-select --install.
2. Install Rust with rustup (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh).
3. Build:

cargo build --release --locked -p valerian-cli -p valerian-gui

Valerian uses Metal, which needs no extra setup. The programs are target/release/valerian and target/release/valerian-gui. The GPU parity tests and the GUI snapshots pass on an Apple M1 (see Run the tests). Programs you build yourself are not signed or notarised; on your own machine that is not a problem, and to share the app with other Macs see Optional: make packages.

Debian, Ubuntu, Raspberry Pi OS and Linux Mint¶

sudo apt-get update
sudo apt-get install build-essential pkg-config git curl \
    libvulkan1 mesa-vulkan-drivers \
    libxkbcommon-dev libwayland-dev libx11-dev libxcursor-dev libxrandr-dev libxi-dev

mesa-vulkan-drivers covers AMD, Intel and the Raspberry Pi. NVIDIA owners use NVIDIA's own driver instead. These are the packages the project's own builds install, on Debian 12 and Ubuntu 22.04 and 24.04. Then install Rust with rustup and build:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"
cargo build --release --locked -p valerian-cli -p valerian-gui

On a Raspberry Pi use a 64-bit operating system (Raspberry Pi OS 64-bit or Ubuntu for Pi). The project's automated tests run on 64-bit Arm Linux with a software GPU, not on Raspberry Pi hardware, so report what you find. Compiling on a Pi is slow and needs plenty of memory; add swap, or cross-compile from a PC.

Fedora, RHEL and relatives¶

sudo dnf install gcc gcc-c++ make pkgconf-pkg-config git curl \
    vulkan-loader mesa-vulkan-drivers \
    libxkbcommon-devel wayland-devel libX11-devel libXcursor-devel libXrandr-devel libXi-devel

Then install Rust with rustup and build as above. These are the Fedora names of the Debian packages listed above; the project's own builds run on Debian and Ubuntu, so tell me if a name differs on your release.

Arch Linux and relatives¶

sudo pacman -S --needed base-devel git rustup vulkan-icd-loader mesa \
    libxkbcommon wayland libx11 libxcursor libxrandr libxi
rustup default stable

Install the Vulkan driver for your card too (vulkan-radeon, vulkan-intel or nvidia-utils). Then build as above. As for Fedora, the names are the Arch equivalents of the Debian list.

Any other Linux¶

You need a C compiler and linker, pkg-config, git, and the development files for xkbcommon, Wayland, X11 (libX11, libXcursor, libXrandr, libXi) and the Vulkan loader, plus a Vulkan driver for your GPU. Find the equivalents of the Debian packages above in your distribution, then build with rustup's Rust. The command line tool alone (-p valerian-cli) needs no windowing libraries.

Build¶

The first build needs network access to github.com: Valerian uses Helia's core and GPU crates (helia-core, helia-gpu) as git dependencies pinned to one commit of the Helia repository, and cargo fetches them.

cargo build --release --locked -p valerian-cli -p valerian-gui   # the two programs
cargo build --release --locked                             # every crate in the workspace

--locked builds exactly the dependency versions in Cargo.lock. The first build takes a while and later ones are quick. The workspace members are crates/* and xtask.

Check it works¶

target/release/valerian --version
target/release/valerian info --gpu
target/release/valerian-gui

On Windows use target\release\valerian.exe. valerian info --gpu also opens the graphics adapter and reports it. To try Valerian without data, a first session ends with a small synthetic session you can make with one script. The top bar of the desktop app says GPU or CPU; if you expected a GPU, see GPU acceleration.

The star catalogue¶

valerian solve and valerian photocal read a star catalogue, gaia-dr3-g11.vcat (Gaia DR3 to G = 11). It is in the repository, in crates/valerian-core/data, and a build in the checkout finds it by itself. If you copy the programs elsewhere, copy the file beside them, or point VALERIAN_CATALOGUE at it. valerian info prints the catalogue: line it found. The catalogue is derived from ESA Gaia data under the CC BY-NC 3.0 IGO licence: non-commercial use only, with its licence text kept beside it. scripts/build_catalogue.py rebuilds it from the Gaia archive.

Install the programs¶

Copy the two programs somewhere on your PATH, or let cargo do it:

cargo install --locked --path crates/valerian-cli
cargo install --locked --path crates/valerian-gui

That puts them in ~/.cargo/bin (%USERPROFILE%\.cargo\bin on Windows). To remove them later, cargo uninstall valerian-cli valerian-gui. Settings are kept apart from the programs, in ~/.config/valerian (%APPDATA%\valerian on Windows); delete that folder if you want them gone.

Run the tests¶

VALERIAN_GPU_TESTS=software cargo test --workspace --all-features

VALERIAN_GPU_TESTS chooses the graphics adapter the GPU tests use: software (the fallback adapter: WARP on Windows, lavapipe on Linux; install mesa-vulkan-drivers), hardware (your GPU), or unset to skip them. On macOS there is no software adapter, so use hardware. In PowerShell set the variable first: $env:VALERIAN_GPU_TESTS = "software".

Optional: make packages¶

The scripts the project uses for its own installers are in packaging/, for people who want to distribute their own build. They need the release binaries and the licence summary produced by cargo about (see packaging/about.toml). Read each script's header for its arguments.

Whoever distributes a build must keep the copyright line and the dedication and mark modified versions as changed: the additional terms are in ADDITIONAL-TERMS.md.

If the build fails¶

If something here is wrong or missing for your system, open an issue on the GitHub repository.