Merge pull request #358 from pluiedev/pluie/jj-skqxktqmsvox

docs/install: revamp build instructions for 1.2

Author: mitchellh

docs/install/build.mdx

@@ -7,22 +7,35 @@ description: |-
 ---
 
 <Tip>
+
 **Building Ghostty from source is not recommended for most users.**
 If you have access to a prebuilt binary or package, you should use that
 instead. See [the binaries and packages page](/docs/install/binary) to
 see if a prebuilt binary or package is available for your platform.
+
 </Tip>
 
-To build Ghostty, you need [Zig 0.14](https://ziglang.org/) installed.
+To build Ghostty, you need [Zig](https://ziglang.org/) installed.
 
 <Important>
-**Zig 0.14 is required.** Ghostty only guarantees that it can build
-against 0.14. Zig is still a fast-moving project so it is likely newer
-versions will not be able to build Ghostty yet. You can find binary
-releases of Zig release builds on the
-[Zig downloads page](https://ziglang.org/download/).
+
+Each version of Ghostty is only guaranteed to build for one **specific** version
+of Zig as it is still a rapidly-evolving project. **Either older or newer
+Zig compilers may not be able to build Ghostty.** If your package manager
+maintains a different version of Zig than what Ghostty requires, you can use
+static binary releases of the Zig compiler on the [Zig downloads page](https://ziglang.org/download/).
+
 </Important>
 
+The Zig version that each Ghostty version requires is as follows:
+
+| Ghostty version | Zig version |
+|-----------------|-------------|
+| 1.0.x           | 0.13.0      |
+| 1.1.x           | 0.13.0      |
+| 1.2.x           | 0.14.1      |
+| tip             | 0.14.1      |
+
 The official build environment is defined by [Nix](https://nixos.org/).
 You do not need to use Nix to build Ghostty, but the Nix environment is the
 environment which runs CI tests and builds release artifacts, so it is the most
@@ -33,24 +46,64 @@ Depending on your platform, you may also need to install additional
 dependencies to build Ghostty. For Linux, see [Linux](#linux). For macOS,
 see [macOS](#macos).
 
-Begin by cloning the Ghostty repository and changing into the directory:
+## Getting the source code
 
-```sh
-git clone https://github.com/ghostty-org/ghostty
-cd ghostty
+Begin by **downloading Ghostty's source tarball**.
+
+<Warning>
+
+While you can compile Ghostty from source by checking out its Git repository,
+this is **not recommended** for anyone but Ghostty developers and contributors.
+This is because source tarballs contain various preprocessed files that make
+Ghostty require far fewer dependencies to compile.
+
+If you intend to contribute to Ghostty, please consult the
+[README](https://github.com/ghostty-org/ghostty/blob/main/README.md#developing-ghostty)
+file on the steps to build Ghostty in a development environment.
+While most of the steps are exactly the same, we will be assuming a source
+tarball-based build for now on for the sake of simplicity.
+
+</Warning>
+
+For stable releases, source tarballs and their accompanying checksums can be
+found at `releases.files.ghostty.org` at the following paths, where `VERSION`
+is an unprefixed version number 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
 ```
 
-To build a stable release, check out the associated tag. If you skip this
-step you'll build the [tip version](/docs/install/pre).
+Signature files are signed with
+[minisign](https://jedisct1.github.io/minisign/)
+using the following public key:
+```
+RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV
+```
+
+For development ("tip") versions, the source tarball can be found via the
+[`tip` release on GitHub](https://github.com/ghostty-org/ghostty/releases/tag/tip),
+under the name `ghostty-source.tar.gz`.
 
 <Important>
-**Version 1.1.3 and under requires Zig version 0.13 to build**. When building
-from tip you will however need Zig version 0.14 due to build system changes and
-other updates to the tooling used.
+
+The source tarball is **different** from GitHub's autogenerated tarball
+labelled "Source code (zip)" or "Source code (tar.gz)": the latter of which does
+not contain any preprocessed files, making it identical to a Git checkout.
+
 </Important>
 
-```
-git checkout <tag>
+Decompress the release tarball, and then navigate into the unpacked source folder:
+
+```sh
+tar -xf ghostty-VERSION.tar.gz
+cd ghostty-VERSION/
+
+# Or when using a tip source tarball:
+# (REVISION is the commit SHA of the latest commit)
+
+tar -xf ghostty-source.tar.gz
+cd ghostty-VERSION-main+REVISION/
 ```
 
 With Zig and necessary dependencies installed, a binary can then be built
@@ -64,14 +117,18 @@ On Linux, this will build a ready-to-use binary at `zig-out/bin/ghostty`.
 On macOS, this will build the app bundle at `zig-out/Ghostty.app`.
 
 <Tip>
+
 For Linux users: To install system-wide or on your user account, see
 [Installation Directory](#installation-directory).
+
 </Tip>
 
 <Tip>
+
 For a debug build, omit the `-Doptimize=ReleaseFast` flag. Debug builds
 are **extremely slow** (over 100x slower) than release builds, so only
 use them for development.
+
 </Tip>
 
 ## Linux
@@ -86,105 +143,143 @@ Required dependencies:
 
   * `gtk4`
   * `libadwaita`
-  * `blueprint-compiler`
-  * `pkg-config`
+  * `gtk4-layer-shell`
+  * `pkg-config` or `pkgconf`
   * `gettext`
 
-<Warning>
-GTK 4.14 on Wayland has a bug which may cause an immediate crash.
-There is an
-[open issue](https://gitlab.gnome.org/GNOME/gtk/-/issues/6589)
-to track this GTK bug. You can workaround this issue by running ghostty with
-`GDK_DEBUG=gl-disable-gles ghostty`.
-</Warning>
+<Important>
+
+If you're using a Git checkout, you also need to install these dependnecies:
+
+  * `blueprint-compiler`
+
+</Important>
+
+<Tip>
+
+If your distro has yet to package `gtk4-layer-shell` (e.g. Ubuntu 24.04, Debian
+12, Linux Mint 22.1, OpenSUSE, etc.), you need to allow Ghostty to compile
+`gtk4-layer-shell` from source by adding the flag `-fno-sys=gtk4-layer-shell`
+to `zig build`.
+
+</Tip>
 
 #### Alpine
 
 ```sh
-doas apk add gtk4.0-dev libadwaita-dev pkgconf ncurses blueprint-compiler gettext
+doas apk add \
+  gtk4.0-dev \
+  libadwaita-dev \
+  pkgconf \
+  ncurses \
+  gettext
 ```
 
 #### Arch Linux
 
 ```sh
-sudo pacman -S gtk4 gtk4-layer-shell libadwaita blueprint-compiler gettext
+sudo pacman -S \
+  gtk4 \
+  gtk4-layer-shell \
+  libadwaita \
+  gettext
 ```
 
 #### Debian and Ubuntu
 
 ```sh
-sudo apt install libgtk-4-dev libadwaita-1-dev git blueprint-compiler gettext libxml2-utils
+sudo apt install \
+  libgtk-4-dev \
+  libgtk4-layer-shell-dev \
+  libadwaita-1-dev \
+  gettext \
+  libxml2-utils
 ```
 
 On Debian unstable/testing, the `gcc-multilib` package is also required
 for building.
 
-On Ubuntu 24.10+ and Debian trixie+, `libgtk4-layer-shell-dev` is also
-needed for building.
-
-<Note>
-**A recent GTK is required for Ghostty to work with Nvidia (GL) drivers
-under x11.** Ubuntu 22.04 LTS has GTK 4.6 which is not new enough. Ubuntu 23.10
-has GTK 4.12 and works. From [this discussion](https://discourse.gnome.org/t/opengl-context-version-not-respected-on-gtk4-rs/12162?u=cdehais)
-the problem was fixed in GTK by Dec 2022. Also, if you are a BTRFS user, make
-sure to manually upgrade your Kernel (6.6.6 will work). The stock kernel in
-Ubuntu 23.10 is 6.5.0 which has a bug which
-[causes zig to fail its hash check for packages](https://github.com/ziglang/zig/issues/17282).
-</Note>
-
 #### Fedora
 
 On Fedora variants, use
 
 ```sh
-sudo dnf install gtk4-devel gtk4-layer-shell-devel zig libadwaita-devel blueprint-compiler gettext
+sudo dnf install \
+  gtk4-devel \
+  gtk4-layer-shell-devel \
+  zig \
+  libadwaita-devel \
+  gettext
 ```
 
 On Fedora Atomic variants, use
 
 ```sh
-rpm-ostree install gtk4-devel gtk4-layer-shell-devel zig libadwaita-devel blueprint-compiler gettext
+rpm-ostree install \
+  gtk4-devel \
+  gtk4-layer-shell-devel \
+  zig \
+  libadwaita-devel \
+  gettext
 ```
 
 #### Gentoo
 
 ```sh
-emerge -av libadwaita gtk blueprint-compiler gettext
+emerge -av \
+  libadwaita \
+  gtk \
+  blueprint-compiler \
+  gettext
 ```
 
 #### openSUSE Tumbleweed
 
 ```sh
-sudo zypper install gtk4-devel libadwaita-devel pkgconf ncurses-devel zig blueprint-compiler gettext
+sudo zypper install \
+  gtk4-devel \
+  libadwaita-devel \
+  pkgconf \
+  ncurses-devel \
+  zig \
+  gettext
 ```
 
 #### openSUSE Leap
 
 ```sh
-sudo zypper install gtk4-devel libadwaita-devel pkgconf ncurses-devel blueprint-compiler gettext
+sudo zypper install \
+  gtk4-devel \
+  libadwaita-devel \
+  pkgconf \
+  ncurses-devel \
+  zig \
+  gettext
 ```
 
 #### Solus
 
 ```sh
-sudo eopkg install libgtk-4-devel libadwaita-devel pkgconf zig blueprint-compiler gettext
+sudo eopkg install \
+  libgtk-4-devel \
+  libadwaita-devel \
+  pkgconf \
+  zig \
+  gettext
 ```
 
 #### Void
 
 ```sh
-sudo xbps-install gtk4-devel libadwaita-devel pkg-config zig blueprint-compiler gettext
+sudo xbps-install \
+  gtk4-devel \
+  gtk4-layer-shell-devel \
+  libadwaita-devel \
+  pkg-config \
+  zig \
+  gettext
 ```
 
-### Broken Dependencies
-
-#### Pango
-
-If you are experiencing a segfault in `cairo_scaled_font_get_font_options`
-when running Ghostty, your Pango version may have a bug. See
-[this discussion on GitHub](https://github.com/ghostty-org/ghostty/discussions/3258#)
-for more information on how to resolve this.
-
 ### Installation Directory
 
 Use `zig build` with the `-p` (prefix) flag to install Ghostty into
@@ -194,12 +289,11 @@ all work.
 
 For local, unprivileged installs, we recommend `$HOME/.local`:
 
-```
+```sh
 zig build -p $HOME/.local -Doptimize=ReleaseFast
-...
 ```
 
-With a typical Freedesktop-compatible desktop environment (i.e. Gnome,
+With a typical Freedesktop-compatible desktop environment (i.e. GNOME,
 KDE), this will make Ghostty available as an app in your app launcher.
 If you don't see it immediately you may have to log out and log back
 in or maybe even restart.