docs: separate out HACKING.md from README.md
Also did some copy-editing and removed some things that haven't been present in the codebase for a while (I thought we nuked conformance stuff in 1.1 already...?)pull/8445/head
Leah Amelia Chen
parent
f4abecefe4
commit
2701932475
|
|
@ -0,0 +1,126 @@
|
||||||
|
# Developing Ghostty
|
||||||
|
|
||||||
|
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 detect memory misuses |
|
||||||
|
| `zig build test` | Runs unit tests (accepts `-Dtest-filter=<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.
|
||||||
116
README.md
116
README.md
|
|
@ -13,7 +13,7 @@
|
||||||
·
|
·
|
||||||
<a href="https://ghostty.org/docs">Documentation</a>
|
<a href="https://ghostty.org/docs">Documentation</a>
|
||||||
·
|
·
|
||||||
<a href="#developing-ghostty">Developing</a>
|
<a href="HACKING.md">Developing</a>
|
||||||
</p>
|
</p>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
|
@ -187,116 +187,4 @@ SENTRY_DSN=https://e914ee84fd895c4fe324afa3e53dac76@o4507352570920960.ingest.us.
|
||||||
|
|
||||||
## Developing Ghostty
|
## Developing Ghostty
|
||||||
|
|
||||||
See the documentation on the Ghostty website for
|
Please check out our [HACKING.md](HACKING.md) for more details.
|
||||||
[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=<filter>` for running a specific subset of those unit tests
|
|
||||||
- `zig build run -Dconformance=<name>` 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.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue