diff --git a/PACKAGING.md b/PACKAGING.md new file mode 100644 index 000000000..77a64325d --- /dev/null +++ b/PACKAGING.md @@ -0,0 +1,89 @@ +# Packaging Ghostty for Distribution + +Ghostty relies on downstream package maintainers to distribute Ghostty to +end-users. This document provides guidance to package maintainers on how to +package Ghostty for distribution. + +> [!NOTE] +> +> While Ghostty went through an extensive private beta testing period, +> packaging Ghostty is immature and may require additional build script +> tweaks and documentation improvement. I'm extremely motivated to work with +> package maintainers to improve the packaging process. Please open issues +> to discuss any packaging issues you encounter. + +## Source Tarballs + +Source tarballs with stable checksums are available on the +[GitHub releases page](https://github.com/ghostty-org/ghostty/releases). + +> [!WARNING] +> +> These are not currently signed with PGP. I'm working on this. + +## Zig Version + +[Zig](https://ziglang.org) is required to build Ghostty. Prior to Zig 1.0, +Zig releases often have breaking changes. Ghostty requires specific Zig versions +depending on the Ghostty version in order to build. To make things easier for +package maintainers, Ghostty always uses some _released_ version of Zig. + +To find the version of Zig required to build Ghostty, check the `required_zig` +constant in `build.zig`. You don't need to know Zig to extract this information. +This version will always be an official released version of Zig. + +For example, at the time of writing this document, Ghostty requires Zig 0.13.0. + +## Building Ghostty + +The following is a standard example of how to build Ghostty _for system +packages_. This is not the recommended way to build Ghostty for your +own system. For that, see the primary README. + +1. First, we fetch our dependencies from the internet into a cached directory. + This is the only step that requires internet access: + +```sh +ZIG_GLOBAL_CACHE_DIR=/tmp/offline-cache ./nix/build-support/fetch-zig-cache.sh +``` + +2. Next, we build Ghostty. This step requires no internet access: + +```sh +DESTDIR=/tmp/ghostty \ +zig build \ + --prefix /usr \ + --system /tmp/offline-cache/p \ + -Doptimize=ReleaseFast \ + -Dcpu=baseline +``` + +The build options are covered in the next section, but this will build +and install Ghostty to `/tmp/ghostty` with the prefix `/usr` (i.e. the +binary will be at `/tmp/ghostty/usr/bin/ghostty`). This style is common +for system packages which separate a build and install step, since the +install step can then be done with a `mv` or `cp` command (from `/tmp/ghostty` +to wherever the package manager expects it). + +### Build Options + +Ghostty uses the Zig build system. You can see all available build options by +running `zig build --help`. The following are options that are particularly +relevant to package maintainers: + +- `--prefix`: The installation prefix. Combine with the `DESTDIR` environment + variable to install to a temporary directory for packaging. + +- `--system`: The path to the offline cache directory. This disables + any package fetching from the internet. This flag also triggers all + dependencies to be dynamically linked by default. + +- `-Doptimize=ReleaseFast`: Build with optimizations enabled and safety checks + disabled. This is the recommended build mode for distribution. I'd prefer + a safe build but terminal emulators are performance-sensitive and the + safe build is currently too slow. I plan to improve this in the future. + Other build modes are available: `Debug`, `ReleaseSafe`, and `ReleaseSmall`. + +- `-Dcpu=baseline`: Build for the "baseline" CPU of the target architecture. + This avoids building for newer CPU features that may not be available on + all target machines.