Building from source

It is easy to build GraphoOS from source on a GNU/Linux distribution. Cargo handles the build process, all you need to do, is ensure the correct dependencies are installed.

Install the Rust compiler and Cargo using rustup.rs. If you already have the toolchain, ensure you are using latest Rust version.
Install dependencies for your operating system:

Ubuntu

sudo apt install clang libxkbcommon-x11-dev pkg-config libvulkan-dev libwayland-dev xorg-dev libxcb-shape0-dev libxcb-xfixes0-dev

Fedora

sudo dnf install clang libxkbcommon-x11-devel libxcb-devel vulkan-loader-devel wayland-devel openssl-devel pkgconf

Void Linux

sudo xbps-install -S base-devel clang libxkbcommon-devel vulkan-loader wayland-devel

While the GraphoOS repositories are private, Cargo needs your GitHub credentials to fetch the graphoos-* dependencies. The repository's .cargo/config.toml already tells Cargo to use the system git, so it is enough to have gh auth login done (or a token in your git credential helper). In a container or CI job, export a token and run git config --global url."https://x-access-token:${GH_TOKEN}@github.com/".insteadOf "https://github.com/" before cloning: the clone needs it as much as the build. Verified on 2026-09-24 in a clean rust:1.98.1-bookworm container, following these steps as written (log in build-logs).

Clone this repository (this command will clone to your home directory):

git clone https://github.com/Empoorio/graphoos.git ~/graphoos

cd into the repository, and run the build command with the release flag

cd ~/graphoos

cargo install --path . --bin graphoos --profile release-lto --locked

release-lto optimises the whole program at once and needs well over 8 GB of memory for the last step; a container or machine with 8 GB or less is killed there without a word. On one of those, build with --profile release instead: the same editor, a little larger and slower.

If you use a different distribution, and are having trouble finding appropriate dependencies, let us know in an issue!

Once GraphoOS is compiled, the executable will be available in $HOME/.cargo/bin/graphoos and should be available in PATH automatically.

Grammars, queries and proxies

A program built with cargo alone has no syntax colours until it finds grammars: it looks for the ones it carries and then for downloaded ones. make app puts them in GraphoOS.app/Contents/Resources; for a build of your own, put them beside it with

scripts/bundle_resources.sh ~/.cargo/share/graphoos

(share/graphoos next to the folder of the program; resources/ beside the program also works, and GRAPHOOS_RESOURCES_DIR names any other folder). It takes the grammar archives from GRAPHOOS_GRAMMARS_DIST (the dist/ of the grammars repository) and the Linux proxies from scripts/build_linux_proxies.sh. With them, a clean install is coloured and connects to Linux machines with no network and no account. tools/bundled_smoke.py checks it in the running editor.

Building offline, and reproducibly

scripts/vendor_tarball.sh [commit] makes graphoos-<version>-<commit>-vendored.tar.gz: the repository at that commit and every dependency it builds with (vendor/), with a .cargo/config.toml that takes them from there. It builds with no network and no credentials:

tar xzf graphoos-0.5.0-beta.1-<commit>-vendored.tar.gz && cd graphoos-0.5.0-beta.1-<commit>
RUSTUP_TOOLCHAIN=1.98.1 cargo build --offline --frozen --profile release

RUSTUP_TOOLCHAIN because rust-toolchain.toml also asks for rustfmt and clippy, which a build does not need and rustup would try to download: with no network, name the installed toolchain.

Two builds of the same commit give the same bytes when they are made from the same path (scripts/reproducible_check.sh builds twice in /tmp/graphoos-build and compares). From two different folders they do not: cargo puts the path of the workspace's own packages in the names of their symbols, which --remap-path-prefix does not reach.

Building using Docker or Podman

Packages available in releases are built using containers based on multi-stage Dockerfiles. To easily orchestrate builds, there is a docker-bake.hcl manifest in root of repository that defines all stages and targets. If you want to build all packages for ubuntu, you can run RELEASE_TAG_NAME=nightly docker buildx bake ubuntu (RELEASE_TAG_NAME is a required environment variable used to tell what kind of release is being built as well as baking in the version itself). To scope in to specific distribution version, you can define target with it's version counterpart from matrix, e.g. to build only Ubuntu Focal package, you can run RELEASE_TAG_NAME=nightly docker buildx bake ubuntu-focal. Additionally to building multiple OS versions at the same time, Docker-based builds will also try to cross-compile GraphoOS for other architectures. This does not require QEMU installed as it's done via true cross-compilation meaning HOST will run your native OS/CPU architecture and TARGET will be the wanted architecture, instead of spawning container that's running OS using TARGET architecture.

![WARNING] Do not run plain targets like ubuntu or fedora if you don't have very powerful machine, as it will spawn many concurrent jobs which will take a long time to build.

Source: docs/building-from-source.md