> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jylhis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> How to build and install Jotain

# Installation

Jotain uses [Nix](https://nixos.org/) to build Emacs from source, driven by a `Justfile` task runner. Development assumes a [devenv](https://devenv.sh) shell (managed by `direnv` via `.envrc`, or entered manually with `devenv shell`).

## Prerequisites

* [Nix package manager](https://nixos.org/download) with `nix-build` available
* [just](https://github.com/casey/just) task runner (provided by the devenv shell)
* [devenv](https://devenv.sh) (optional but recommended for development)

All `just` recipes assume the devenv shell is active. If you do not use direnv, prefix any command with `devenv shell --`, e.g. `devenv shell -- just check`.

## Building Emacs

The default build targets the current system and includes every tree-sitter grammar from nixpkgs:

```bash theme={}
just build
```

This runs `nix-build --argstr system <current-system> default.nix`, which wraps `emacs.nix` with `emacsPackagesFor ... withPackages` to add `treesit-grammars.with-all-grammars`. For the plain mainline build (the `emacs.nix` default), the store path is bit-for-bit identical to nixpkgs' default `pkgs.emacs`, so the official binary cache is hit and nothing recompiles from source; the git-based variants are likewise cache hits from [`nix-community/emacs-overlay`](https://github.com/nix-community/emacs-overlay)'s `nix-community.cachix.org`.

### Build Variants

Every `emacs.nix` argument is forwarded through `default.nix`. The `Justfile` provides shortcuts for the common flavours:

```bash theme={}
just build          # mainline Emacs 31 + every grammar (default)
just build-bare     # bare Emacs from emacs.nix — no grammars
just build-jylhis   # bare github:jylhis/emacs Meson fork
just build-pgtk     # --with-pgtk (pure GTK, Wayland)
just build-gtk3     # --with-x-toolkit=gtk3 (X11 + GTK3)
just build-nox      # --without-x --without-ns (terminal only)
just build-macport  # jdtsmith/emacs-mac fork (Darwin only)
just build-git      # bleeding-edge master from git.savannah.gnu.org
just build-igc      # feature/igc3 MPS incremental GC branch
just build-android  # aarch64-linux nox (Termux)
```

Or call `nix-build` directly with any argument the `emacs.nix` file accepts:

```bash theme={}
nix-build default.nix                                    # mainline + grammars
nix-build default.nix --arg withTreeSitterGrammars false # grammars off
nix-build emacs.nix  --arg withNativeCompilation false   # no native-comp
nix-build emacs.nix  --arg variant '"git"'               # master
nix-build emacs.nix  --arg variant '"igc"'               # MPS GC branch
nix-build emacs.nix  --arg variant '"macport"'           # macOS macport fork
```

<Note>
  `git`/`unstable`/`igc` build the revision pinned by emacs-overlay and are binary-cache hits. Only when pinning a custom commit via `--argstr rev "..."` does the first build fail and report the expected hash to pass back via `--argstr hash "sha256-..."`.
</Note>

## Installing from a Consumer Flake

Jotain exposes Home Manager, NixOS, and nix-darwin modules. The default backend stays on the cache-friendly `emacs.nix` build:

```nix theme={}
{
  imports = [ inputs.jotain.homeManagerModules.default ];

  services.jotain.enable = true;
}
```

To install the same Jotain setup on the `github:jylhis/emacs` Meson fork, select the fork backend:

```nix theme={}
{
  imports = [ inputs.jotain.homeManagerModules.default ];

  services.jotain = {
    enable = true;
    emacsBackend = "jylhis";
  };
}
```

Downstream flakes can override the fork source by following the `jylhis-emacs` input:

```nix theme={}
inputs.jotain.url = "github:jylhis/jotain";
inputs.my-emacs-fork = {
  url = "github:jylhis/emacs/my-branch-or-rev";
  flake = false;
};
inputs.jotain.inputs.jylhis-emacs.follows = "my-emacs-fork";
```

The bare fork package is checked directly. The full fork-backed package set is **not** exposed as a flake `packages` output, because the Meson fork still crashes while byte-compiling some bundled Emacs packages. It remains reachable via the Home Manager `services.jotain.emacsBackend = "jylhis"` option (which consumes the `jylhisEmacsPackages` overlay attribute directly) for those who want to exercise that experimental path.

### nix-on-droid (Android)

Jotain also ships a [nix-on-droid](https://github.com/nix-community/nix-on-droid) module for running Emacs on Android (Termux/proot). Android is headless under proot, so the module installs a **terminal-only** (`-nw`) Emacs into `environment.packages` and wires `EDITOR`/`VISUAL` to an `emacsclient` wrapper — there is no systemd daemon, launchd agent, or GUI frame.

```nix theme={}
{
  imports = [ jotain.nixOnDroidModules.default ];

  services.jotain.enable = true;
}
```

Switch it in with `nix-on-droid switch --flake .#default`. See `nixOnDroidConfigurations.default` in Jotain's `flake.nix` for a complete example wiring.

<Note>
  Like the NixOS / nix-darwin module (`module-system.nix`), this module installs the **curated Jotain Emacs package** — Jotain's Emacs packages, tree-sitter grammars, themes, and Info manual are on the `load-path` — but it does not install Jotain's own `early-init.el` / `init.el` / `lisp/`. To have Emacs boot the full Jotain configuration, point it at the config with `--init-directory` (the way `just run` does) or layer the Home Manager module through nix-on-droid's `home-manager.config`, which installs the config into a writable `~/.config/emacs`. A bare `--init-directory` into the read-only Nix store will not work, because Jotain writes `var/`, `elpa/`, and `eln-cache/` under `user-emacs-directory`.
</Note>

### Overriding nixpkgs

Downstream flakes may pin a different nixpkgs (release branches **24.05+** through unstable) by following the input:

```nix theme={}
inputs.jotain.inputs.nixpkgs.follows = "nixpkgs";
```

`emacs.nix` gates the Emacs build flags that newer `make-emacs.nix` versions introduced, so the modules still evaluate and build on older releases. Note that on 24.05 `pkgs.emacs` is Emacs 29 while Jotain's Elisp targets Emacs 30/31 — the build succeeds, but full runtime behaviour is only guaranteed on the pinned unstable.

## Running

Jotain is designed to be launched out of its own checkout via `--init-directory`, so it never touches `~/.emacs.d`.

```bash theme={}
just run                # launch Emacs with this config (GUI)
just debug              # same, with --debug-init and debug-on-error
just tty                # -nw terminal session (exercises kkp + clipetty)
just run-built          # build for this platform, then launch result/bin/emacs
```

`just run` simply invokes `emacs --init-directory=<repo>`. The devenv shell ships the same Emacs that `just build-bare` produces, so running inside direnv is usually enough for day-to-day use — no `nix-build` required.