Refactor watcher to use cross-platform fsnotify, remove deprecated platform-specific files, and add comprehensive README.md

2026-06-25 14:59:08 +02:00
parent c92ef2e0a9
commit d53fe33e03
6 changed files with 293 additions and 235 deletions
@@ -0,0 +1,89 @@
+# 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`).