diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e988704b..777771145 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,9 @@ -# Ghostty Development Process +# Contributing to Ghostty -This document describes the development process for Ghostty. It is intended for -anyone considering opening an **issue** or **pull request**. If in doubt, -please open a [discussion](https://github.com/ghostty-org/ghostty/discussions); -we can always convert that to an issue later. +This document describes the process of contributing to Ghostty. It is intended +for anyone considering opening an **issue**, **discussion** or **pull request**. +For people who are interested in developing Ghostty and technical details behind +it, please check out our ["Developing Ghostty"](HACKING.md) document as well. > [!NOTE] > @@ -49,13 +49,16 @@ Please be respectful to maintainers and disclose AI assistance. ## Quick Guide -**I'd like to contribute!** +### I'd like to contribute! -All issues are actionable. Pick one and start working on it. Thank you. -If you need help or guidance, comment on the issue. Issues that are extra -friendly to new contributors are tagged with "contributor friendly". +[All issues are actionable](#issues-are-actionable). Pick one and start +working on it. Thank you. If you need help or guidance, comment on the issue. +Issues that are extra friendly to new contributors are tagged with +["contributor friendly"]. -**I'd like to translate Ghostty to my language!** +["contributor friendly"]: https://github.com/ghostty-org/ghostty/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22contributor%20friendly%22 + +### I'd like to translate Ghostty to my language! We have written a [Translator's Guide](po/README_TRANSLATORS.md) for everyone interested in contributing translations to Ghostty. @@ -64,25 +67,39 @@ and you can submit pull requests directly, although please make sure that our [Style Guide](po/README_TRANSLATORS.md#style-guide) is followed before submission. -**I have a bug!** +### I have a bug! / Something isn't working! -1. Search the issue tracker and discussions for similar issues. -2. If you don't have steps to reproduce, open a discussion. -3. If you have steps to reproduce, open an issue. +1. Search the issue tracker and discussions for similar issues. Tip: also + search for [closed issues] and [discussions] — your issue might have already + been fixed! +2. If your issue hasn't been reported already, open an ["Issue Triage" discussion] + and make sure to fill in the template **completely**. They are vital for + maintainers to figure out important details about your setup. Because of + this, please make sure that you _only_ use the "Issue Triage" category for + reporting bugs — thank you! -**I have an idea for a feature!** +[closed issues]: https://github.com/ghostty-org/ghostty/issues?q=is%3Aissue%20state%3Aclosed +[discussions]: https://github.com/ghostty-org/ghostty/discussions?discussions_q=is%3Aclosed +["Issue Triage" discussion]: https://github.com/ghostty-org/ghostty/discussions/new?category=issue-triage -1. Open a discussion. +### I have an idea for a feature! -**I've implemented a feature!** +Open a discussion in the ["Feature Requests, Ideas" category](https://github.com/ghostty-org/ghostty/discussions/new?category=feature-requests-ideas). -1. If there is an issue for the feature, open a pull request. +### I've implemented a feature! + +1. If there is an issue for the feature, open a pull request straight away. 2. If there is no issue, open a discussion and link to your branch. -3. If you want to live dangerously, open a pull request and hope for the best. +3. If you want to live dangerously, open a pull request and + [hope for the best](#pull-requests-implement-an-issue). -**I have a question!** +### I have a question! -1. Open a discussion or use Discord. +Open an [Q&A discussion], or join our [Discord Server] and ask away in the +`#help` channel. + +[Q&A discussion]: https://github.com/ghostty-org/ghostty/discussions/new?category=q-a +[Discord Server]: https://discord.gg/ghostty ## General Patterns @@ -120,209 +137,3 @@ pull request will be accepted with a high degree of certainty. > **Pull requests are NOT a place to discuss feature design.** Please do > not open a WIP pull request to discuss a feature. Instead, use a discussion > and link to your branch. - -# Developer Guide - -> [!NOTE] -> -> **The remainder of this file is dedicated to developers actively -> working on Ghostty.** If you're a user reporting an issue, you can -> ignore the rest of this document. - -## Including and Updating Translations - -See the [Contributor's Guide](po/README_CONTRIBUTORS.md) for more details. - -## Checking for Memory Leaks - -While Zig does an amazing job of finding and preventing memory leaks, -Ghostty uses many third-party libraries that are written in C. Improper usage -of those libraries or bugs in those libraries can cause memory leaks that -Zig cannot detect by itself. - -### On Linux - -On Linux the recommended tool to check for memory leaks is Valgrind. The -recommended way to run Valgrind is via `zig build`: - -```sh -zig build run-valgrind -``` - -This builds a Ghostty executable with Valgrind support and runs Valgrind -with the proper flags to ensure we're suppressing known false positives. - -You can combine the same build args with `run-valgrind` that you can with -`run`, such as specifying additional configurations after a trailing `--`. - -## Input Stack Testing - -The input stack is the part of the codebase that starts with a -key event and ends with text encoding being sent to the pty (it -does not include _rendering_ the text, which is part of the -font or rendering stack). - -If you modify any part of the input stack, you must manually verify -all the following input cases work properly. We unfortunately do -not automate this in any way, but if we can do that one day that'd -save a LOT of grief and time. - -Note: this list may not be exhaustive, I'm still working on it. - -### Linux IME - -IME (Input Method Editors) are a common source of bugs in the input stack, -especially on Linux since there are multiple different IME systems -interacting with different windowing systems and application frameworks -all written by different organizations. - -The following matrix should be tested to ensure that all IME input works -properly: - -1. Wayland, X11 -2. ibus, fcitx, none -3. Dead key input (e.g. Spanish), CJK (e.g. Japanese), Emoji, Unicode Hex -4. ibus versions: 1.5.29, 1.5.30, 1.5.31 (each exhibit slightly different behaviors) - -> [!NOTE] -> -> This is a **work in progress**. I'm still working on this list and it -> is not complete. As I find more test cases, I will add them here. - -#### Dead Key Input - -Set your keyboard layout to "Spanish" (or another layout that uses dead keys). - -1. Launch Ghostty -2. Press `'` -3. Press `a` -4. Verify that `á` is displayed - -Note that the dead key may or may not show a preedit state visually. -For ibus and fcitx it does but for the "none" case it does not. Importantly, -the text should be correct when it is sent to the pty. - -We should also test canceling dead key input: - -1. Launch Ghostty -2. Press `'` -3. Press escape -4. Press `a` -5. Verify that `a` is displayed (no diacritic) - -#### CJK Input - -Configure fcitx or ibus with a keyboard layout like Japanese or Mozc. The -exact layout doesn't matter. - -1. Launch Ghostty -2. Press `Ctrl+Shift` to switch to "Hiragana" -3. On a US physical layout, type: `konn`, you should see `こん` in preedit. -4. Press `Enter` -5. Verify that `こん` is displayed in the terminal. - -We should also test switching input methods while preedit is active, which -should commit the text: - -1. Launch Ghostty -2. Press `Ctrl+Shift` to switch to "Hiragana" -3. On a US physical layout, type: `konn`, you should see `こん` in preedit. -4. Press `Ctrl+Shift` to switch to another layout (any) -5. Verify that `こん` is displayed in the terminal as committed text. - -## Nix Virtual Machines - -Several Nix virtual machine definitions are provided by the project for testing -and developing Ghostty against multiple different Linux desktop environments. - -Running these requires a working Nix installation, either Nix on your -favorite Linux distribution, NixOS, or macOS with nix-darwin installed. Further -requirements for macOS are detailed below. - -VMs should only be run on your local desktop and then powered off when not in -use, which will discard any changes to the VM. - -The VM definitions provide minimal software "out of the box" but additional -software can be installed by using standard Nix mechanisms like `nix run nixpkgs#`. - -### Linux - -1. Check out the Ghostty source and change to the directory. -2. Run `nix run .#`. `` can be any of the VMs defined in the - `nix/vm` directory (without the `.nix` suffix) excluding any file prefixed - with `common` or `create`. -3. The VM will build and then launch. Depending on the speed of your system, this - can take a while, but eventually you should get a new VM window. -4. The Ghostty source directory should be mounted to `/tmp/shared` in the VM. Depending - on what UID and GID of the user that you launched the VM as, `/tmp/shared` _may_ be - writable by the VM user, so be careful! - -### macOS - -1. To run the VMs on macOS you will need to enable the Linux builder in your `nix-darwin` - config. This _should_ be as simple as adding `nix.linux-builder.enable=true` to your - configuration and then rebuilding. See [this](https://nixcademy.com/posts/macos-linux-builder/) - blog post for more information about the Linux builder and how to tune the performance. -2. Once the Linux builder has been enabled, you should be able to follow the Linux instructions - above to launch a VM. - -### Custom VMs - -To easily create a custom VM without modifying the Ghostty source, create a new -directory, then create a file called `flake.nix` with the following text in the -new directory. - -``` -{ - inputs = { - nixpkgs.url = "nixpkgs/nixpkgs-unstable"; - ghostty.url = "github:ghostty-org/ghostty"; - }; - outputs = { - nixpkgs, - ghostty, - ... - }: { - nixosConfigurations.custom-vm = ghostty.create-gnome-vm { - nixpkgs = nixpkgs; - system = "x86_64-linux"; - overlay = ghostty.overlays.releasefast; - # module = ./configuration.nix # also works - module = {pkgs, ...}: { - environment.systemPackages = [ - pkgs.btop - ]; - }; - }; - }; -} -``` - -The custom VM can then be run with a command like this: - -``` -nix run .#nixosConfigurations.custom-vm.config.system.build.vm -``` - -A file named `ghostty.qcow2` will be created that is used to persist any changes -made in the VM. To "reset" the VM to default delete the file and it will be -recreated the next time you run the VM. - -### Contributing new VM definitions - -#### VM Acceptance Criteria - -We welcome the contribution of new VM definitions, as long as they meet the following criteria: - -1. They should be different enough from existing VM definitions that they represent a distinct - user (and developer) experience. -2. There's a significant Ghostty user population that uses a similar environment. -3. The VMs can be built using only packages from the current stable NixOS release. - -#### VM Definition Criteria - -1. VMs should be as minimal as possible so that they build and launch quickly. - Additional software can be added at runtime with a command like `nix run nixpkgs#`. -2. VMs should not expose any services to the network, or run any remote access - software like SSH daemons, VNC or RDP. -3. VMs should auto-login using the "ghostty" user. diff --git a/HACKING.md b/HACKING.md new file mode 100644 index 000000000..d79d15a4a --- /dev/null +++ b/HACKING.md @@ -0,0 +1,329 @@ +# Developing Ghostty + +This document describes the technical details behind Ghostty's development. +If you'd like to open any pull requests or would like to implement new features +into Ghostty, please make sure to read our ["Contributing to Ghostty"](CONTRIBUTING.md) +document first. + +To start development on Ghostty, you need to build Ghostty from a Git checkout, +which is very similar in process to [building Ghostty from a source tarball](http://ghostty.org/docs/install/build). One key difference is that obviously +you need to clone the Git repository instead of unpacking the source tarball: + +```shell +git clone https://github.com/ghostty-org/ghostty +cd ghostty +``` + +> [!NOTE] +> +> Ghostty may require [extra dependencies](#extra-dependencies) +> when building from a Git checkout compared to a source tarball. +> Tip versions may also require a different version of Zig or other toolchains +> (e.g. the Xcode SDK on macOS) compared to stable versions — make sure to +> follow the steps closely! + +When you're developing Ghostty, it's very likely that you will want to build a +_debug_ build to diagnose issues more easily. This is already the default for +Zig builds, so simply run `zig build` **without any `-Doptimize` flags**. + +There are many more build steps than just `zig build`, some of which are listed +here: + +| Command | Description | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `zig build run` | Runs Ghostty | +| `zig build run-valgrind` | Runs Ghostty under Valgrind to [check for memory leaks](#checking-for-memory-leaks) | +| `zig build test` | Runs unit tests (accepts `-Dtest-filter=` to only run tests whose name matches the filter) | +| `zig build update-translations` | Updates Ghostty's translation strings (see the [Contributor's Guide on Localizing Ghostty](po/README_CONTRIBUTORS.md)) | +| `zig build dist` | Builds a source tarball | +| `zig build distcheck` | Installs and validates a source tarball | + +## Extra Dependencies + +Building Ghostty from a Git checkout on Linux requires some additional +dependencies: + +- `blueprint-compiler` (version 0.16.0 or newer) + +macOS users don't require any additional dependencies. + +## Xcode Version and SDKs + +Building the Ghostty macOS app requires that Xcode, the macOS SDK, +and the iOS SDK are all installed. + +A common issue is that the incorrect version of Xcode is either +installed or selected. Use the `xcode-select` command to +ensure that the correct version of Xcode is selected: + +```shell-session +sudo xcode-select --switch /Applications/Xcode-beta.app +``` + +> [!IMPORTANT] +> +> Main branch development of Ghostty is preparing for the next major +> macOS release, Tahoe (macOS 26). Therefore, the main branch requires +> **Xcode 26 and the macOS 26 SDK**. +> +> You do not need to be running on macOS 26 to build Ghostty, you can +> still use Xcode 26 beta on macOS 15 stable. + +## Linting + +### Prettier + +Ghostty's docs and resources (not including Zig code) are linted using +[Prettier](https://prettier.io) with out-of-the-box settings. A Prettier CI +check will fail builds with improper formatting. Therefore, if you are +modifying anything Prettier will lint, you may want to install it locally and +run this from the repo root before you commit: + +``` +prettier --write . +``` + +Make sure your Prettier version matches the version of Prettier in [devShell.nix](https://github.com/ghostty-org/ghostty/blob/main/nix/devShell.nix). + +Nix users can use the following command to format with Prettier: + +``` +nix develop -c prettier --write . +``` + +### Alejandra + +Nix modules are formatted with [Alejandra](https://github.com/kamadorueda/alejandra/). An Alejandra CI check +will fail builds with improper formatting. + +Nix users can use the following command to format with Alejandra: + +``` +nix develop -c alejandra . +``` + +Non-Nix users should install Alejandra and use the following command to format with Alejandra: + +``` +alejandra . +``` + +Make sure your Alejandra version matches the version of Alejandra in [devShell.nix](https://github.com/ghostty-org/ghostty/blob/main/nix/devShell.nix). + +### Updating the Zig Cache Fixed-Output Derivation Hash + +The Nix package depends on a [fixed-output +derivation](https://nix.dev/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHash) +that manages the Zig package cache. This allows the package to be built in the +Nix sandbox. + +Occasionally (usually when `build.zig.zon` is updated), the hash that +identifies the cache will need to be updated. There are jobs that monitor the +hash in CI, and builds will fail if it drifts. + +To update it, you can run the following in the repository root: + +``` +./nix/build-support/check-zig-cache-hash.sh --update +``` + +This will write out the `nix/zigCacheHash.nix` file with the updated hash +that can then be committed and pushed to fix the builds. + +## Including and Updating Translations + +See the [Contributor's Guide](po/README_CONTRIBUTORS.md) for more details. + +## Checking for Memory Leaks + +While Zig does an amazing job of finding and preventing memory leaks, +Ghostty uses many third-party libraries that are written in C. Improper usage +of those libraries or bugs in those libraries can cause memory leaks that +Zig cannot detect by itself. + +### On Linux + +On Linux the recommended tool to check for memory leaks is Valgrind. The +recommended way to run Valgrind is via `zig build`: + +```sh +zig build run-valgrind +``` + +This builds a Ghostty executable with Valgrind support and runs Valgrind +with the proper flags to ensure we're suppressing known false positives. + +You can combine the same build args with `run-valgrind` that you can with +`run`, such as specifying additional configurations after a trailing `--`. + +## Input Stack Testing + +The input stack is the part of the codebase that starts with a +key event and ends with text encoding being sent to the pty (it +does not include _rendering_ the text, which is part of the +font or rendering stack). + +If you modify any part of the input stack, you must manually verify +all the following input cases work properly. We unfortunately do +not automate this in any way, but if we can do that one day that'd +save a LOT of grief and time. + +Note: this list may not be exhaustive, I'm still working on it. + +### Linux IME + +IME (Input Method Editors) are a common source of bugs in the input stack, +especially on Linux since there are multiple different IME systems +interacting with different windowing systems and application frameworks +all written by different organizations. + +The following matrix should be tested to ensure that all IME input works +properly: + +1. Wayland, X11 +2. ibus, fcitx, none +3. Dead key input (e.g. Spanish), CJK (e.g. Japanese), Emoji, Unicode Hex +4. ibus versions: 1.5.29, 1.5.30, 1.5.31 (each exhibit slightly different behaviors) + +> [!NOTE] +> +> This is a **work in progress**. I'm still working on this list and it +> is not complete. As I find more test cases, I will add them here. + +#### Dead Key Input + +Set your keyboard layout to "Spanish" (or another layout that uses dead keys). + +1. Launch Ghostty +2. Press `'` +3. Press `a` +4. Verify that `á` is displayed + +Note that the dead key may or may not show a preedit state visually. +For ibus and fcitx it does but for the "none" case it does not. Importantly, +the text should be correct when it is sent to the pty. + +We should also test canceling dead key input: + +1. Launch Ghostty +2. Press `'` +3. Press escape +4. Press `a` +5. Verify that `a` is displayed (no diacritic) + +#### CJK Input + +Configure fcitx or ibus with a keyboard layout like Japanese or Mozc. The +exact layout doesn't matter. + +1. Launch Ghostty +2. Press `Ctrl+Shift` to switch to "Hiragana" +3. On a US physical layout, type: `konn`, you should see `こん` in preedit. +4. Press `Enter` +5. Verify that `こん` is displayed in the terminal. + +We should also test switching input methods while preedit is active, which +should commit the text: + +1. Launch Ghostty +2. Press `Ctrl+Shift` to switch to "Hiragana" +3. On a US physical layout, type: `konn`, you should see `こん` in preedit. +4. Press `Ctrl+Shift` to switch to another layout (any) +5. Verify that `こん` is displayed in the terminal as committed text. + +## Nix Virtual Machines + +Several Nix virtual machine definitions are provided by the project for testing +and developing Ghostty against multiple different Linux desktop environments. + +Running these requires a working Nix installation, either Nix on your +favorite Linux distribution, NixOS, or macOS with nix-darwin installed. Further +requirements for macOS are detailed below. + +VMs should only be run on your local desktop and then powered off when not in +use, which will discard any changes to the VM. + +The VM definitions provide minimal software "out of the box" but additional +software can be installed by using standard Nix mechanisms like `nix run nixpkgs#`. + +### Linux + +1. Check out the Ghostty source and change to the directory. +2. Run `nix run .#`. `` can be any of the VMs defined in the + `nix/vm` directory (without the `.nix` suffix) excluding any file prefixed + with `common` or `create`. +3. The VM will build and then launch. Depending on the speed of your system, this + can take a while, but eventually you should get a new VM window. +4. The Ghostty source directory should be mounted to `/tmp/shared` in the VM. Depending + on what UID and GID of the user that you launched the VM as, `/tmp/shared` _may_ be + writable by the VM user, so be careful! + +### macOS + +1. To run the VMs on macOS you will need to enable the Linux builder in your `nix-darwin` + config. This _should_ be as simple as adding `nix.linux-builder.enable=true` to your + configuration and then rebuilding. See [this](https://nixcademy.com/posts/macos-linux-builder/) + blog post for more information about the Linux builder and how to tune the performance. +2. Once the Linux builder has been enabled, you should be able to follow the Linux instructions + above to launch a VM. + +### Custom VMs + +To easily create a custom VM without modifying the Ghostty source, create a new +directory, then create a file called `flake.nix` with the following text in the +new directory. + +``` +{ + inputs = { + nixpkgs.url = "nixpkgs/nixpkgs-unstable"; + ghostty.url = "github:ghostty-org/ghostty"; + }; + outputs = { + nixpkgs, + ghostty, + ... + }: { + nixosConfigurations.custom-vm = ghostty.create-gnome-vm { + nixpkgs = nixpkgs; + system = "x86_64-linux"; + overlay = ghostty.overlays.releasefast; + # module = ./configuration.nix # also works + module = {pkgs, ...}: { + environment.systemPackages = [ + pkgs.btop + ]; + }; + }; + }; +} +``` + +The custom VM can then be run with a command like this: + +``` +nix run .#nixosConfigurations.custom-vm.config.system.build.vm +``` + +A file named `ghostty.qcow2` will be created that is used to persist any changes +made in the VM. To "reset" the VM to default delete the file and it will be +recreated the next time you run the VM. + +### Contributing new VM definitions + +#### VM Acceptance Criteria + +We welcome the contribution of new VM definitions, as long as they meet the following criteria: + +1. They should be different enough from existing VM definitions that they represent a distinct + user (and developer) experience. +2. There's a significant Ghostty user population that uses a similar environment. +3. The VMs can be built using only packages from the current stable NixOS release. + +#### VM Definition Criteria + +1. VMs should be as minimal as possible so that they build and launch quickly. + Additional software can be added at runtime with a command like `nix run nixpkgs#`. +2. VMs should not expose any services to the network, or run any remote access + software like SSH daemons, VNC or RDP. +3. VMs should auto-login using the "ghostty" user. diff --git a/README.md b/README.md index a761e25ce..df86f7830 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,9 @@ · Documentation · - Developing + Contributing + · + Developing

@@ -49,6 +51,14 @@ See the [download page](https://ghostty.org/download) on the Ghostty website. See the [documentation](https://ghostty.org/docs) on the Ghostty website. +## Contributing and Developing + +If you have any ideas, issues, etc. regarding Ghostty, or would like to +contribute to Ghostty through pull requests, please check out our +["Contributing to Ghostty"](CONTRIBUTING.md) document. Those who would like +to get involved with Ghostty's development as well should also read the +["Developing Ghostty"](HACKING.md) document for more technical details. + ## Roadmap and Status The high-level ambitious plan for the project, in order: @@ -184,119 +194,3 @@ SENTRY_DSN=https://e914ee84fd895c4fe324afa3e53dac76@o4507352570920960.ingest.us. > stack memory of each thread at the time of the crash. This information > is used to rebuild the stack trace but can also contain sensitive data > depending when the crash occurred. - -## Developing Ghostty - -See the documentation on the Ghostty website for -[building Ghostty from a source tarball](http://ghostty.org/docs/install/build). -Building Ghostty from a Git checkout is very similar, except you want to -omit the `-Doptimize` flag to build a debug build, and you may require -additional dependencies since the source tarball includes some processed -files that are not in the Git repository. - -Other useful commands: - -- `zig build test` for running unit tests. -- `zig build test -Dtest-filter=` for running a specific subset of those unit tests -- `zig build run -Dconformance=` runs a conformance test case from - the `conformance` directory. The `name` is the name of the file. This runs - in the current running terminal emulator so if you want to check the - behavior of this project, you must run this command in Ghostty. - -### Extra Dependencies - -Building Ghostty from a Git checkout on Linux requires some additional -dependencies: - -- `blueprint-compiler` - -macOS users don't require any additional dependencies. - -> [!NOTE] -> This only applies to building from a _Git checkout_. This section does -> not apply if you're building from a released _source tarball_. For -> source tarballs, see the -> [website](http://ghostty.org/docs/install/build). - -### Xcode Version and SDKs - -Building the Ghostty macOS app requires that Xcode, the macOS SDK, -and the iOS SDK are all installed. - -A common issue is that the incorrect version of Xcode is either -installed or selected. Use the `xcode-select` command to -ensure that the correct version of Xcode is selected: - -```shell-session -sudo xcode-select --switch /Applications/Xcode-beta.app -``` - -> [!IMPORTANT] -> -> Main branch development of Ghostty is preparing for the next major -> macOS release, Tahoe (macOS 26). Therefore, the main branch requires -> **Xcode 26 and the macOS 26 SDK**. -> -> You do not need to be running on macOS 26 to build Ghostty, you can -> still use Xcode 26 beta on macOS 15 stable. - -### Linting - -#### Prettier - -Ghostty's docs and resources (not including Zig code) are linted using -[Prettier](https://prettier.io) with out-of-the-box settings. A Prettier CI -check will fail builds with improper formatting. Therefore, if you are -modifying anything Prettier will lint, you may want to install it locally and -run this from the repo root before you commit: - -``` -prettier --write . -``` - -Make sure your Prettier version matches the version of Prettier in [devShell.nix](https://github.com/ghostty-org/ghostty/blob/main/nix/devShell.nix). - -Nix users can use the following command to format with Prettier: - -``` -nix develop -c prettier --write . -``` - -#### Alejandra - -Nix modules are formatted with [Alejandra](https://github.com/kamadorueda/alejandra/). An Alejandra CI check -will fail builds with improper formatting. - -Nix users can use the following command to format with Alejandra: - -``` -nix develop -c alejandra . -``` - -Non-Nix users should install Alejandra and use the following command to format with Alejandra: - -``` -alejandra . -``` - -Make sure your Alejandra version matches the version of Alejandra in [devShell.nix](https://github.com/ghostty-org/ghostty/blob/main/nix/devShell.nix). - -#### Updating the Zig Cache Fixed-Output Derivation Hash - -The Nix package depends on a [fixed-output -derivation](https://nix.dev/manual/nix/stable/language/advanced-attributes.html#adv-attr-outputHash) -that manages the Zig package cache. This allows the package to be built in the -Nix sandbox. - -Occasionally (usually when `build.zig.zon` is updated), the hash that -identifies the cache will need to be updated. There are jobs that monitor the -hash in CI, and builds will fail if it drifts. - -To update it, you can run the following in the repository root: - -``` -./nix/build-support/check-zig-cache-hash.sh --update -``` - -This will write out the `nix/zigCacheHash.nix` file with the updated hash -that can then be committed and pushed to fix the builds.