197 lines
9.8 KiB
Markdown
197 lines
9.8 KiB
Markdown
# gbld — Simple Go Builder & Live-Reloader
|
|
|
|
`gbld` is a hot-reloader and build-automation utility for Go projects. It automatically tracks build numbers, formats source files using `goimports`, compiles the binary, manages the running process, and watches the project directory for changes to trigger automatic rebuilding and restarting.
|
|
|
|
---
|
|
|
|
## Key Features
|
|
|
|
- 🔄 **Hot Reloader**: Automatically watches for file changes (via `fsnotify`), recursively including subdirectories, and rebuilds/restarts your application instantly.
|
|
- 🔢 **Build Counter**: Increments a build number in `build.go` automatically with every compiled build.
|
|
- 🧹 **Auto-Import**: Runs `goimports` on save (optional via `-i`) to keep your imports clean — without touching the rest of your formatting.
|
|
- 🖥️ **Interactive Menu**: Uses a select menu (`gbld.menu.json`) if run without arguments, letting you define and run custom build tasks.
|
|
- 🚀 **Cross-Compilation**: Easily builds binaries for multiple target operating systems (macOS, Linux, Windows) and architectures (amd64, arm64) using a single command.
|
|
- 🔐 **Verified Self-Update**: Installs new versions from the Gitea releases over HTTPS and refuses anything that does not match its published SHA-256 checksum.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
Make sure you have [Go](https://go.dev/) installed and available in your system path. `goimports` is only required if you use the `-i` flag:
|
|
```bash
|
|
go install golang.org/x/tools/cmd/goimports@latest
|
|
```
|
|
|
|
### Building from Source
|
|
Clone the repository and compile `gbld`:
|
|
```bash
|
|
git clone https://git.fhi.mpg.de/mike/gbld.git
|
|
cd gbld
|
|
go build -o /usr/local/bin/gbld
|
|
```
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
gbld [flags] [target_name]
|
|
```
|
|
> [!NOTE]
|
|
> If `target_name` is omitted, the name of the current directory is used. The tool expects a main source file matching that name (e.g., `target_name.go`). The binary is always built from the package in the current directory, so the module path does not have to match the target name.
|
|
|
|
### CLI Flags
|
|
|
|
| Flag | Argument | Description |
|
|
| :--- | :--- | :--- |
|
|
| `-b` | None | **Build-only** mode (compiles the binary but does not run it). |
|
|
| `-1` | None | Run **once** (does not watch the directory for changes), see [Exit Codes](#exit-codes). |
|
|
| `-i` | None | Runs `goimports` to clean up imports before building. |
|
|
| `-x` | None | Exits after the first successful build and **leaves the started binary running**. |
|
|
| `-o` | `<args>` | Space-separated arguments to pass to the compiled binary on execution. |
|
|
| `-c` | `<command>` | Command to execute immediately after a successful build (before execution). |
|
|
| `-a` | None | Builds binaries for all supported platforms (Windows, macOS, Linux for AMD64/ARM64). |
|
|
| `-v` | None | Displays the current version of `gbld`. |
|
|
| `-h` | None | Displays help and usage information. |
|
|
| `--check-update` | None | Looks for a newer release and reports what it finds — installs nothing. |
|
|
| `--update` | None | Downloads the newest release and replaces the running binary with it. |
|
|
|
|
### Environment
|
|
|
|
| Variable | Description |
|
|
| :--- | :--- |
|
|
| `GBLD_NO_UPDATE` | Set to any value to silence the background update check (useful offline or in CI). `--update` and `--check-update` still work. |
|
|
|
|
---
|
|
|
|
## Configuration (`gbld.menu.json`)
|
|
|
|
To make running common tasks easier, you can place a `gbld.menu.json` file in your project directory. If you run `gbld` without any flags, it will parse this file and present an interactive selection menu (entries are shown in alphabetical order):
|
|
|
|
```json
|
|
{
|
|
"Build and Run (hot reload)": ["-i"],
|
|
"Build Only": ["-b", "-i", "-1"],
|
|
"Show Help": ["-h"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Under the Hood
|
|
|
|
### Build Increment
|
|
When compiling, `gbld` parses `build.go` to find a pattern matching `var build = "<number>"`. It increments this number by 1 and updates the file automatically, leaving the rest of the line (including trailing comments) untouched. This is useful for stamping build numbers/versions inside your binary. If there is no `build.go`, this step is silently skipped.
|
|
|
|
### Target Version
|
|
`-a` names its artifacts after the first `var version = "x.y.z"` found in the `*.go` files of the project. Ordinary builds do not need this variable.
|
|
|
|
### Automatic Backups
|
|
Before `gbld` runs `goimports` on a file or modifies `build.go`, it creates a timestamped backup in a `./tmp/` directory inside the project workspace (the directory is created on demand):
|
|
```
|
|
./tmp/gbld.go.20260625145800
|
|
```
|
|
If a backup cannot be written, the file is **not** modified.
|
|
|
|
### File Watching
|
|
The project directory is watched recursively; directories created while `gbld` is running are picked up automatically. Hidden entries (`.git`, …) as well as `bin`, `tmp`, `vendor`, `node_modules` and `testdata` are skipped. Only writes and newly created `.go` files trigger a rebuild — a pure `touch` (mtime only) does not. Rebuilds are debounced by 100 ms and never run in parallel.
|
|
|
|
### Process Management
|
|
When hot-reloading, `gbld` handles process termination gracefully:
|
|
1. It sends an `os.Interrupt` (SIGINT) to the running binary.
|
|
2. It waits up to 1 second for the process to exit clean.
|
|
3. If it does not exit within the timeout, it terminates the process forcefully (`SIGKILL`).
|
|
|
|
`gbld` itself also traps SIGINT/SIGTERM and stops the started binary before exiting, so no orphaned processes are left behind — except with `-x`, where detaching is the point.
|
|
|
|
### Exit Codes
|
|
With `-1`, `gbld` is usable from scripts and CI:
|
|
|
|
| Situation | Exit code |
|
|
| :--- | :--- |
|
|
| Build failed | `1` |
|
|
| `-b -1`, build succeeded | `0` |
|
|
| `-1` without `-b` | exit code of the built program (gbld waits for it) |
|
|
|
|
---
|
|
|
|
## Cross-Compilation
|
|
|
|
```bash
|
|
gbld -a # build bin/<name>_<version>_<os>_<arch> for all 6 targets
|
|
```
|
|
|
|
`-a` writes Windows artifacts with an `.exe` suffix and additionally produces:
|
|
|
|
- `bin/checksums.txt` — SHA-256 of every artifact, in the format used by `shasum -a 256 -c`
|
|
- `bin/version.txt` — the version that was built
|
|
|
|
If any target fails to build, `version.txt` is **not** written and `gbld` exits with `1`, so a half-published version can never be announced.
|
|
|
|
> [!NOTE]
|
|
> `-a` is the path for the programs `gbld` builds. `gbld` itself is released with `build.sh` (see below), which uses a different naming — both write `bin/checksums.txt`, so whichever ran last is the one that file describes.
|
|
|
|
---
|
|
|
|
## Releasing gbld itself
|
|
|
|
```bash
|
|
./build.sh # steps the patch version, builds every platform
|
|
VERSION=1.22.0 ./build.sh # a minor or major step is named outright
|
|
PLATFORMS="linux/amd64" ./build.sh
|
|
```
|
|
|
|
`build.sh` writes into `bin/` exactly what a release needs:
|
|
|
|
- `gbld-<goos>-<goarch>` — the binaries, `.exe` for Windows, built with `-trimpath -s -w` and the version injected via `-ldflags`
|
|
- `checksums.txt` — their SHA-256, in the format of `shasum -a 256`
|
|
|
|
`version.txt` holds the version just built and is stepped by `0.0.1` on every run. Upload **all** of these files to a Gitea release whose tag is the bare version number (`1.21.1`, a leading `v` is allowed) — that is the layout `--update` expects.
|
|
|
|
> [!IMPORTANT]
|
|
> `gbld -a` names its artifacts from `var version` in the sources, `build.sh` from `version.txt`, and nothing writes to a `.go` file. For gbld's own releases `build.sh` is the way — `var version` only shows up in a bare `go build`.
|
|
|
|
### Self-Update
|
|
|
|
`selfupdate.go` holds the whole mechanism and is meant to be copied into other programs: adjust the block at its head, hang the two options into the flags, done. It needs nothing but the standard library.
|
|
|
|
Once a day, in the background, `gbld` asks the Gitea for the newest release and notes the answer in the cache directory. The next run reads that note and prints one line if something newer exists — the foreground never touches the network, so an unreachable server can never delay a build. The hint appears only on a terminal: in a pipe, a script or under cron, `gbld` stays quiet, as it does with `GBLD_NO_UPDATE` set.
|
|
|
|
`--update` fetches the asset for the running platform, weighs it against the SHA-256 from the release's `checksums.txt`, and only then replaces the running binary — after calling the fresh one once with `-v` to be sure it runs at all. **A release without a matching checksum is refused**, and a download that does not match is deleted, not installed. The certificate of the Gitea is verified like any other.
|
|
|
|
---
|
|
|
|
## Colors
|
|
|
|
Output uses the [Catppuccin Mocha](https://terminalcolors.com/themes/catppuccin/mocha/) palette as 24-bit color:
|
|
|
|
| Helper | Palette | Hex |
|
|
| :--- | :--- | :--- |
|
|
| `Cr` / `Crb` | Red | `#f38ba8` |
|
|
| `Cg` / `Cgb` | Green | `#a6e3a1` |
|
|
| `Cy` / `Cyb` | Yellow | `#f9e2af` |
|
|
| `Cb` / `Cbb` | Blue | `#89b4fa` |
|
|
| `Cm` / `Cmb` | Pink | `#f5c2e7` |
|
|
| `Cc` / `Ccb` | Teal | `#94e2d5` |
|
|
| `Cw` | Subtext1 | `#bac2de` |
|
|
| `Cwb` | Text | `#cdd6f4` |
|
|
|
|
Mocha maps identical values to the normal and bright ANSI slots, so the bold helpers keep their hue and only add weight. The full palette is available as `CatMauve`, `CatPeach`, `CatLavender`, … in `tools.go`.
|
|
|
|
The interactive prompts (`survey`) are themed as well: their templates resolve colors through `{{color "green+hb"}}`-style names, and `tools.go` replaces that template function with one that maps those names onto the palette. This covers every prompt including its icons — question mark, select arrow, help and error markers — without copying any template.
|
|
|
|
Terminals that do not announce 24-bit color via `COLORTERM` fall back to the basic ANSI colors, so their own theme keeps deciding. `NO_COLOR` and non-TTY output disable colors entirely.
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
```bash
|
|
go test ./... # unit tests (build counter, version detection, update verification, toolbox)
|
|
go vet ./...
|
|
```
|
|
|
|
> [!NOTE]
|
|
> The sources are deliberately **not** `gofmt`-formatted (2-space indentation). The `-i` flag only replaces the `import (...)` block of a file and leaves the rest of the formatting alone — do not run `gofmt` over the tree.
|