# Build from source

> Workspace build of xai-grok-pager-bin: Rust toolchain pin, protoc/dotslash, cargo run/check/test per-crate, binary name xai-grok-pager vs shipped grok, and contribution policy constraints.

- Repository: xai-org/grok-build
- GitHub: https://github.com/xai-org/grok-build
- Human docs: https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458
- Complete Markdown: https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/llms-full.txt

## Source Files

- `README.md`
- `Cargo.toml`
- `rust-toolchain.toml`
- `crates/codegen/xai-grok-pager-bin/src/main.rs`
- `crates/codegen/xai-grok-pager-bin/Cargo.toml`
- `bin/protoc`
- `CONTRIBUTING.md`
- `clippy.toml`

---

---
title: "Build from source"
description: "Workspace build of xai-grok-pager-bin: Rust toolchain pin, protoc/dotslash, cargo run/check/test per-crate, binary name xai-grok-pager vs shipped grok, and contribution policy constraints."
---

The public tree is a Cargo workspace that produces the Grok Build CLI/TUI from the composition-root package `xai-grok-pager-bin`. That package owns the binary target named `xai-grok-pager` (still the on-disk artifact name in `target/`); official installers ship the same program as `grok`. The root `Cargo.toml` is generated and should be treated as read-only; edit per-crate manifests instead. Builds expect the pin in `rust-toolchain.toml` (channel `1.92.0`, `rustfmt` + `clippy`) and a working Protocol Buffers compiler resolved through `xai-proto-build` — typically the DotSlash launcher at `bin/protoc`, or `$PROTOC` / a `protoc` on `PATH`.

## When to build from source

| Goal | Prefer |
|------|--------|
| Day-to-day use | Released `grok` binary via install scripts |
| Inspect or run the open source tree | `cargo run -p xai-grok-pager-bin` |
| Local development / debugging | Debug build of `xai-grok-pager-bin` |
| Closer-to-ship artifact | `cargo build -p xai-grok-pager-bin --profile release-dist` |

For install layout, PATH, and version pins of the shipped binary, see [Installation](/installation).

## Requirements

- **Rust toolchain** — pinned by `rust-toolchain.toml`. With `rustup`, the first `cargo` invocation in the repo installs channel `1.92.0` and components `rustfmt` and `clippy`. The file also lists Linux cross targets (`x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`); the host target is added automatically.
- **Workspace edition** — workspace package edition is `2024` (set under `[workspace.package]`).
- **protoc** — needed when crates with protobuf build scripts compile (for example `xai-grok-tools-api` via `xai-proto-build`). Resolution order in `find_protoc()`:
  1. `$PROTOC` (absolute path override; used by hermetic/Bazel-style setups)
  2. `bin/protoc` found by walking up from the current directory (DotSlash wrapper for local dev)
  3. `protoc` on `$PATH`
- **DotSlash** — `bin/protoc` starts with `#!/usr/bin/env dotslash` and downloads pinned protobuf **v29.3** artifacts for `macos-aarch64`, `linux-x86_64`, and `linux-aarch64`. If the wrapper fails with a version check error, install DotSlash (`cargo install dotslash`) or point `$PROTOC` at a real compiler.
- **Host OS** — macOS and Linux are supported build hosts. Windows builds are best-effort and not tested from this tree.

<Warning>
On GitHub Actions, missing `protoc` is a hard error. Outside CI, `find_protoc` may return `None` and only print a warning — proto-generating crates can still fail later if they require a compiler.
</Warning>

## Quick build and run

From the repository root:

```sh
# Install pinned toolchain (rustup) and build + launch the TUI
cargo run -p xai-grok-pager-bin

# Fast typecheck of the composition root
cargo check -p xai-grok-pager-bin

# Optimized binary (default release profile)
cargo build -p xai-grok-pager-bin --release
# → target/release/xai-grok-pager

# Hardened distribution profile (thin LTO, codegen-units=1; used for shipping)
cargo build -p xai-grok-pager-bin --profile release-dist
# → target/release-dist/xai-grok-pager
```

Always pass `-p <crate>` (or an explicit package set). Full-workspace `cargo check` / `cargo test` without package filters is slow on this monorepo-sized tree.

### Binary name vs product name

| Surface | Name |
|---------|------|
| Cargo package | `xai-grok-pager-bin` |
| Binary target / `default-run` | `xai-grok-pager` |
| Debug/release artifact path | `target/{debug,release}/xai-grok-pager` |
| Official install / docs | `grok` |

You can put the built binary on your `PATH` under either name; CLI behavior matches the shipped `grok` entrypoint (TUI by default, headless `-p`, `agent`, etc.). Tests and the PTY harness look for `xai-grok-pager` (and env overrides such as `PAGER_BINARY` / `CARGO_BIN_EXE_xai-grok-pager`).

## Composition root: what `xai-grok-pager-bin` links

`xai-grok-pager-bin` exists so the binary can link both the main pager library and the optional `xai-grok-pager-minimal` render mode without a Cargo cycle (`minimal` depends on `xai-grok-pager`, so the library cannot depend back on it). At startup, `main` installs minimal-mode IoC hooks, then drives the same surfaces as the product CLI:

- Interactive TUI (`xai-grok-pager`)
- Agent runtime entry points from `xai-grok-shell` (headless, leader, stdio/ACP)
- Update / version / telemetry / workspace / crash-handler crates

Default package features include `jemalloc` (Unix global allocator) and `sandbox-enforce`. Feature `release-dist` is forwarded into the pager library for distribution builds.

```text
xai-grok-pager-bin (binary: xai-grok-pager)
├── xai-grok-pager          # TUI + app CLI parsing
├── xai-grok-pager-minimal  # optional render mode (wired at startup)
├── xai-grok-shell          # agent / headless / leader / ACP
├── xai-grok-update
├── xai-grok-version
├── xai-grok-telemetry
├── xai-grok-workspace
├── xai-crash-handler
└── xai-acp-lib
```

Related runtime crates commonly edited nearby: `xai-grok-tools`, `xai-grok-config`, `xai-grok-sandbox`, and the rest of the `crates/codegen/` closure listed in the workspace members.

## Version string baked into the binary

`crates/codegen/xai-grok-pager-bin/build.rs` emits `VERSION_WITH_COMMIT`:

1. Version from `GROK_VERSION` if set, else `CARGO_PKG_VERSION`
2. Short git commit from `git rev-parse --short HEAD`, or `unknown` if git is unavailable

That string feeds crash reporting, Sentry release tags, and other startup paths. `xai-grok-version` similarly prefers `GROK_VERSION` at compile time for the public version constant.

```sh
GROK_VERSION=0.1.220-alpha.4 cargo build -p xai-grok-pager-bin
```

## Development workflow

Prefer package-scoped commands:

```sh
cargo check -p xai-grok-config
cargo test  -p xai-grok-config
cargo clippy -p xai-grok-pager-bin
cargo fmt --all
```

| Tooling | Location / notes |
|---------|------------------|
| Toolchain pin | `rust-toolchain.toml` — bump one point version at a time; after a bump run `cargo check --all-targets --workspace` and `cargo clippy --all-targets --workspace` |
| rustfmt | `rustfmt.toml` (field-init shorthand) |
| Clippy (codegen crates) | Root `clippy.toml` — Clippy does **not** merge configs; nearest file wins. Disallows `std`/`tokio` `canonicalize` in favor of `dunce::canonicalize` (Windows verbatim-path safety). Large-error threshold `256` for tonic-related types |
| Workspace lints | `[workspace.lints.clippy]` in the generated root `Cargo.toml` |
| Lockfile | `Cargo.lock` is present; keep dependency changes intentional |

### Profiles (selection)

| Profile | Role |
|---------|------|
| `dev` | Local default; `panic = "abort"`, high `codegen-units` |
| `release` | Optimized local release; incremental, `panic = "abort"` |
| `release-dist` | Shipping hardening (thin LTO, `codegen-units = 1`, line-table debug retained for sidecar extraction) |
| `release-dist-jemalloc` | Named alias of `release-dist` for desktop/workflow references |

### protoc / DotSlash troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `protoc --version failed, likely dotslash is missing` | `bin/protoc` present but DotSlash not installed | `cargo install dotslash`, or set `$PROTOC` to a system `protoc` |
| `bin/protoc found … failed to execute; trying protoc from PATH` | DotSlash unavailable (e.g. some remote/Bazel envs) | Install a hermetic `protoc` and set `$PROTOC` |
| Hard fail only on GitHub Actions | No `protoc` anywhere | Provide `$PROTOC` or install `protoc` in the job image |
| Host not in DotSlash platforms | e.g. macOS x86_64 or Windows | Install platform `protoc` and set `$PROTOC` |

`bin/protoc` currently pins protobuf **29.3** zips for three platforms only (`macos-aarch64`, `linux-x86_64`, `linux-aarch64`). Other hosts should not rely on DotSlash for this launcher.

## Repository layout (build-relevant)

| Path | Role |
|------|------|
| `crates/codegen/xai-grok-pager-bin` | Composition root; `[[bin]] name = "xai-grok-pager"` |
| `crates/codegen/xai-grok-pager` | TUI and most application logic |
| `crates/codegen/xai-grok-shell` | Agent runtime and non-TUI entry points |
| `crates/build/xai-proto-build` | Shared prost/tonic configure + `find_protoc` |
| `bin/protoc` | DotSlash launcher for pinned protoc |
| `third_party/` | Vendored Mermaid stack and related ports |
| `Cargo.toml` | Generated workspace root — do not hand-edit for routine work |

## Contribution and license constraints

External pull requests and unsolicited patches are **not** accepted. The public tree is for source transparency and local builds under the Apache License, Version 2.0 (`LICENSE`). There is no CLA for outsiders because contributions are not taken.

- Security issues: report via the process in `SECURITY.md` (HackerOne); do not open public vulnerability issues.
- Third-party / vendored notices: `THIRD-PARTY-NOTICES`, crate-local notices under tools, and `third_party/NOTICE`.

## Related product surfaces after a local build

Once `xai-grok-pager` runs, the same authentication, config, and runtime flags apply as for a released `grok`:

- First launch may open browser OAuth — see [Authentication](/authentication)
- Config and feature resolution — [Configure Grok](/configure-grok)
- Non-interactive runs — [Headless mode](/headless-mode)
- ACP / IDE embedding — [Agent mode (ACP)](/agent-mode)

## Next

<CardGroup cols={2}>
  <Card title="Installation" href="/installation">
    Install the released `grok` binary, PATH under `~/.grok/bin`, and version verification.
  </Card>
  <Card title="Overview" href="/overview">
    Product surfaces (TUI, headless, ACP) and the shortest path to a first successful turn.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Top-level commands and shared runtime flags available on the built binary.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Terminal, auth, MCP, and diagnostics issues after launch.
  </Card>
</CardGroup>