mirror of
https://github.com/ghostty-org/ghostty.git
synced 2025-07-14 15:56:13 +03:00
fb9c52ecf4
This deletes the GLFW apprt from the Ghostty codebase.
The GLFW apprt was the original apprt used by Ghostty (well, before
Ghostty even had the concept of an "apprt" -- it was all just a single
application then). It let me iterate on the core terminal features,
rendering, etc. without bothering about the UI. It was a good way to get
started. But it has long since outlived its usefulness.
We've had a stable GTK apprt for Linux (and Windows via WSL) and a
native macOS app via libghostty for awhile now. The GLFW apprt only
remained within the tree for a few reasons:
1. Primarily, it provided a faster feedback loop on macOS because
building the macOS app historically required us to hop out of the
zig build system and into Xcode, which is slow and cumbersome.
2. It was a convenient way to narrow whether a bug was in the
core Ghostty codebase or in the apprt itself. If a bug was in both
the glfw and macOS app then it was likely in the core.
3. It provided us a way on macOS to test OpenGL.
All of these reasons are no longer valid. Respectively:
1. Our Zig build scripts now execute the `xcodebuild` CLI directly and
can open the resulting app, stream logs, etc. This is the same
experience we have on Linux. (Xcode has always been a dependency of
building on macOS in general, so this is not cumbersome.)
2. We have a healthy group of maintainers, many of which have access
to both macOS and Linux, so we can quickly narrow down bugs
regardless of the apprt.
3. Our OpenGL renderer hasn't been compatible with macOS for some time
now, so this is no longer a useful feature.
At this point, the GLFW apprt is just a burden. It adds complexity
across the board, and some people try to run Ghostty with it in the real
world and get confused when it doesn't work (it's always been lacking in
features and buggy compared to the other apprts).
So, it's time to say goodbye. Its bittersweet because it is a big part
of Ghostty's history, but we've grown up now and it's time to move on.
Thank you, goodbye.
(NOTE: If you are a user of the GLFW apprt, then please fork the project
prior to this commit or start a new project based on it. We've warned
against using it for a very, very long time now.)
125 lines
5.0 KiB
Markdown
125 lines
5.0 KiB
Markdown
# 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.
|
|
|
|
> [!IMPORTANT]
|
|
>
|
|
> This document is only accurate for the Ghostty source alongside it.
|
|
> **Do not use this document for older or newer versions of Ghostty!** If
|
|
> you are reading this document in a different version of Ghostty, please
|
|
> find the `PACKAGING.md` file alongside that version.
|
|
|
|
## Source Tarballs
|
|
|
|
Source tarballs with stable checksums are available for tagged releases
|
|
at `release.files.ghostty.org` in the following URL format where
|
|
`VERSION` is the version number with no prefix such as `1.0.0`:
|
|
|
|
```
|
|
https://release.files.ghostty.org/VERSION/ghostty-VERSION.tar.gz
|
|
https://release.files.ghostty.org/VERSION/ghostty-VERSION.tar.gz.minisig
|
|
```
|
|
|
|
Signature files are signed with
|
|
[minisign](https://jedisct1.github.io/minisign/)
|
|
using the following public key:
|
|
|
|
```
|
|
RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV
|
|
```
|
|
|
|
**Tip source tarballs** are available on the
|
|
[GitHub releases page](https://github.com/ghostty-org/ghostty/releases/tag/tip).
|
|
Use the `ghostty-source.tar.gz` asset and _not the GitHub auto-generated
|
|
source tarball_. These tarballs are generated for every commit to
|
|
the `main` branch and are not associated with a specific version.
|
|
|
|
> [!WARNING]
|
|
>
|
|
> Source tarballs are _not the same_ as a Git checkout. Source tarballs
|
|
> contain some preprocessed files that allow building Ghostty with less
|
|
> dependencies. If you are building Ghostty from a Git checkout, the
|
|
> steps below are the same but they may require additional dependencies
|
|
> not listed here. See the `README.md` for more information on building
|
|
> from a Git checkout.
|
|
>
|
|
> For everyone except Ghostty developers, please use the source tarballs.
|
|
> We generate tip source tarballs for users following the development
|
|
> branch.
|
|
|
|
## 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.14.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. This flag also makes
|
|
the binary a PIE (Position Independent Executable) by default (override
|
|
with `-Dpie`).
|
|
|
|
- `-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.
|
|
|
|
- `-Dtarget=$arch-$os-$abi`: Build for a specific target triple. This is
|
|
often necessary for system packages to specify a specific minimum Linux
|
|
version, glibc, etc. Run `zig targets` to a get a full list of available
|
|
targets.
|