generated from eblume/project-template
Erich Blume
521e5d62df
All checks were successful
Build / validate (pull_request) Successful in 5m5s
Replace the pre-release 'install from feature/v1-prototype' instructions with `--tag v1.0.0` as the default, and document `--branch main` as the track- unreleased-work alternative. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
88 lines
2.9 KiB
Markdown
88 lines
2.9 KiB
Markdown
---
|
|
title: Install heph (and isolate dev)
|
|
modified: 2026-06-04
|
|
tags:
|
|
- how-to
|
|
---
|
|
|
|
# Install heph (and isolate dev)
|
|
|
|
How to install `heph`/`hephd` from the forge and run the `heph.nvim` plugin,
|
|
**isolated** from in-repo development so the two never share data. No prebuilt
|
|
binaries yet — everything builds from source (works on macOS/arm64,
|
|
linux/arm64, linux/amd64).
|
|
|
|
## 1. Install the binaries from the forge
|
|
|
|
Build and install `heph` + `hephd` to `~/.cargo/bin` (on `PATH`) from the latest
|
|
release tag:
|
|
|
|
```bash
|
|
cargo install --locked \
|
|
--git ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
|
|
--tag v1.0.0 \
|
|
heph hephd
|
|
```
|
|
|
|
Bump `--tag` to upgrade to a newer release; to track unreleased work instead,
|
|
swap `--tag vX.Y.Z` for `--branch main`. This needs forge SSH access (an
|
|
unlocked 1Password / ssh-agent key).
|
|
|
|
`heph --version` / `hephd --version` report `X.Y.Z (<git-sha>)` for a tagged
|
|
install and `0.0.0 (<git-sha>)` for a branch/dev install — the release version
|
|
is baked into the tag's manifest (`main` itself stays `0.0.0`), and the short
|
|
SHA is captured at build time so any build is traceable to its commit.
|
|
|
|
The **installed** daemon owns the default paths — socket
|
|
`$XDG_RUNTIME_DIR/heph/hephd.sock`, DB `$XDG_DATA_HOME/heph/heph.db` — i.e. your
|
|
real data.
|
|
|
|
## 2. The Neovim plugin
|
|
|
|
The plugin lives in its own forge repo,
|
|
[eblume/hephaestus.nvim](ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.nvim.git),
|
|
with the plugin at the repo root — so lazy.nvim loads it from a bare git URL.
|
|
Point lazy at the forge over SSH:
|
|
|
|
```lua
|
|
-- lazy.nvim spec
|
|
{
|
|
url = "ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.nvim.git",
|
|
config = function()
|
|
require("heph").setup({}) -- connect-only: talks to the daemon you started
|
|
end,
|
|
}
|
|
```
|
|
|
|
The plugin is **connect-only** — it talks to a `hephd` you run as a service, it
|
|
does not start one itself. Start the daemon once:
|
|
|
|
```bash
|
|
heph daemon start # launchd agent (macOS) / systemd user service (Linux)
|
|
```
|
|
|
|
See [[run-the-daemon]] for `start`/`stop`/`restart`/`status`. Update the plugin
|
|
with `:Lazy update` (and after a `cargo install` upgrade of the binaries, `heph
|
|
daemon restart` to pick up the new `hephd`).
|
|
|
|
## 3. Isolate development
|
|
|
|
In-repo development must not touch the installed store. Run the dev daemon on
|
|
separate paths and point a dev Neovim at it:
|
|
|
|
```bash
|
|
mise run dev # runs the working-tree hephd on .dev/hephd.sock + .dev/heph.db
|
|
```
|
|
|
|
```bash
|
|
# dev Neovim — the plugin reads these envs and targets the dev daemon
|
|
HEPH_SOCKET="$PWD/.dev/hephd.sock" HEPH_DB="$PWD/.dev/heph.db" nvim
|
|
```
|
|
|
|
The installed plugin (no envs) talks to the installed daemon; the dev Neovim
|
|
talks to the dev daemon. They never share a socket or DB. `.dev/` is gitignored.
|
|
|
|
## Related
|
|
|
|
- [[heph-nvim]] — the plugin surface and its managed-daemon lifecycle
|
|
- [[v1-prototype-tech-spec]] — §3.1 runtime modes; the daemon's exclusive DB lock
|