90 lines
3.6 KiB
Markdown
90 lines
3.6 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`) and rebuilds/restarts your application instantly.
|
|
- 🔢 **Build Counter**: Increments a build number in `build.go` automatically with every compiled build.
|
|
- 🧹 **Auto-Import & Formatting**: Runs `goimports` on save (optional via `-i`) to keep your imports and formatting clean.
|
|
- 🖥️ **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.
|
|
- ☁️ **Remote Uploads**: Integrated command to securely upload build artifacts to a deployment server (`gozilla`).
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
Make sure you have [Go](https://go.dev/) and `goimports` installed and available in your system path:
|
|
```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`).
|
|
|
|
### 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). |
|
|
| `-i` | None | Runs `goimports` to clean up imports before building. |
|
|
| `-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). |
|
|
| `-u` | None | Uploads built binaries via SSH/SCP to the `gozilla` server. |
|
|
| `-v` | None | Displays the current version of `gbld`. |
|
|
| `-h` | None | Displays help and usage information. |
|
|
|
|
---
|
|
|
|
## 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:
|
|
|
|
```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. This is useful for stamping build numbers/versions inside your binary.
|
|
|
|
### 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:
|
|
```
|
|
./tmp/gbld.go.20260625145800
|
|
```
|
|
|
|
### 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`).
|