From 0f171edd75b66ff3e2891f80a4fb58b0704636bf Mon Sep 17 00:00:00 2001 From: mixeme Date: Mon, 27 Jul 2026 22:08:03 +0300 Subject: [PATCH] docs: reorder DEVELOPMENT.md and give it a table of contents The document opened with dependency installation and buried "Run From Source" between the build and release sections, so a newcomer met the MSYS2 setup before learning what the stack was. Reorder it as stack and tools, external libraries, run from source, build, release, CI, and add a clickable two-level Contents block. External libraries now list version, repository, and license type in one table, and the package-* scripts are documented for the first time. The Project Layout section is gone: it duplicated the package map in ARCHITECTURE.md and had drifted out of date, missing src/platform/filemanager. Co-Authored-By: Claude Opus 5 --- docs/DEVELOPMENT.md | 227 ++++++++++++++++++++++++++++---------------- 1 file changed, 143 insertions(+), 84 deletions(-) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index 17f6abb..0b1bbbf 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -1,18 +1,50 @@ # GoSentry — Development -Build instructions, project layout, and dependency information for contributors. +Toolchain, dependency, build, and release information for contributors. -## Requirements +## Contents -Common: +1. [Technology Stack and Tools](#1-technology-stack-and-tools) + - [Toolchain — Windows](#toolchain--windows) + - [Toolchain — Linux](#toolchain--linux) + - [Repository scripts](#repository-scripts) +2. [External Libraries](#2-external-libraries) +3. [Run From Source](#3-run-from-source) +4. [Building the Executable](#4-building-the-executable) + - [Windows](#windows) + - [Linux](#linux) + - [Linux using Docker](#linux-using-docker) +5. [Building a Release](#5-building-a-release) + - [All targets from Linux](#all-targets-from-linux) + - [Packaging](#packaging) +6. [CI](#6-ci) + - [Cutting a release](#cutting-a-release) + +## 1. Technology Stack and Tools + +GoSentry is a single desktop process written in Go with a Fyne GUI. There is no +server component and no external runtime: the release artifact is one native +executable per platform. + +| Layer | Choice | +| --- | --- | +| Language | Go 1.22 or newer | +| GUI toolkit | Fyne v2 (OpenGL desktop backend) | +| Scheduling | `robfig/cron/v3` expression parser | +| Persistence | Plain JSON files (`gosentry.json`, `jobs.json`) | +| Build | `go build` driven by the scripts in `scripts/` | +| Reproducible builds | Docker (`golang:1.22-bookworm` based [Dockerfile](../Dockerfile)) | +| CI | GitHub Actions and Forgejo Actions (Codeberg) | + +CGO is mandatory. The Fyne desktop backend links against native OpenGL and +window-system libraries, so a C compiler must be present for every build, +including `go run` and `go test`. + +### Toolchain — Windows - [Go](https://go.dev/) 1.22 or newer. - -Windows: - -- MSYS2 with UCRT64 GCC in `C:\msys64\ucrt64\bin`. - -Install these dependencies on Windows: +- MSYS2 with UCRT64 GCC in `C:\msys64\ucrt64\bin` (plus `windres` for the icon + resource). ```powershell # 1. Install Go 1.22 or newer from https://go.dev/dl/. @@ -33,12 +65,12 @@ Test-Path C:\msys64\ucrt64\bin\gcc.exe Test-Path C:\msys64\ucrt64\bin\windres.exe ``` -Linux: +### Toolchain — Linux +- [Go](https://go.dev/) 1.22 or newer. - A C compiler. -- [Fyne](https://fyne.io/) native build dependencies, including OpenGL/X11 development packages. - -On Debian/Ubuntu, the Linux dependencies are typically: +- [Fyne](https://fyne.io/) native build dependencies, including OpenGL/X11 + development packages. ```bash # Go builds the application, gcc is required by CGO/Fyne, and the OpenGL/X11 @@ -46,7 +78,71 @@ On Debian/Ubuntu, the Linux dependencies are typically: sudo apt install golang gcc libgl1-mesa-dev xorg-dev ``` -## Build +### Repository scripts + +| Script | Purpose | +| --- | --- | +| `scripts/test.bat`, `scripts/test.sh` | `go vet ./...` then `go test -race ./...` | +| `scripts/build-windows.bat` | Windows amd64 executable | +| `scripts/build-linux.sh` | Linux amd64 executable | +| `scripts/build-linux-docker.sh` | Linux amd64 executable, built in Docker | +| `scripts/build-release-linux.sh` | Multi-target release artifacts from one Linux/Docker workflow | +| `scripts/package-windows.bat`, `scripts/package-linux.sh` | Wrap a built binary into a distributable archive | +| `scripts/ci-build-release.sh` | Entry point used by both CI workflows | + +Build outputs are written to `dist/`. The package layout is documented in +[ARCHITECTURE.md](ARCHITECTURE.md). + +## 2. External Libraries + +GoSentry keeps the direct dependency list intentionally small. GoSentry itself +is distributed under the [MIT License](../LICENSE). + +| Dependency | Version | Repository | License | +| --- | --- | --- | --- | +| Go toolchain | 1.22+ | https://go.googlesource.com/go | BSD 3-Clause | +| `fyne.io/fyne/v2` | v2.7.4 | https://github.com/fyne-io/fyne | BSD 3-Clause | +| `github.com/robfig/cron/v3` | v3.0.1 | https://github.com/robfig/cron | MIT | + +The remaining entries in `go.mod` are indirect dependencies pulled in by Fyne +and the Go module resolver. To list every direct and indirect module used by the +current checkout: + +```bash +go list -m all +``` + +## 3. Run From Source + +Windows: + +```powershell +# Fyne requires CGO on Windows. MSYS2 UCRT64 provides the C compiler and native +# libraries used by the desktop backend. +$env:Path = 'C:\msys64\ucrt64\bin;' + $env:Path +$env:CGO_ENABLED = '1' + +# go run starts the app from source. Use scripts\build-windows.bat when you need +# a standalone .exe without a console window. +& 'C:\Program Files\Go\bin\go.exe' run ./cmd/gosentry +``` + +Linux: + +```bash +# CGO must stay enabled because the Fyne GUI links against native Linux desktop +# libraries. +CGO_ENABLED=1 go run ./cmd/gosentry +``` + +The same environment is required for the test suite — see +[TESTS.md](TESTS.md): + +```powershell +scripts\test.bat +``` + +## 4. Building the Executable ### Windows @@ -59,9 +155,8 @@ sudo apt install golang gcc libgl1-mesa-dev xorg-dev .\scripts\build-windows.bat ``` -The Windows build is created as a GUI application, so it does not open a terminal window. - -The binary is written to: +The Windows build is created as a GUI application, so it does not open a +terminal window. The binary is written to: ```text dist\windows\gosentry--windows-amd64.exe @@ -97,7 +192,9 @@ The binary is copied to: dist/linux/gosentry--linux-amd64 ``` -### Release build from Linux +## 5. Building a Release + +### All targets from Linux ```bash # Interactively choose Linux amd64, Linux arm64, Windows amd64, or all artifacts @@ -123,7 +220,29 @@ dist/linux/gosentry--linux-arm64 dist/windows/gosentry--windows-amd64.exe ``` -### Automated release builds (CI) +### Packaging + +The `package-*` scripts build the binary for their platform and wrap it in a +distributable archive together with `README.md` and `CHANGELOG.md`: + +```powershell +scripts\package-windows.bat +``` + +```bash +./scripts/package-linux.sh +``` + +```text +dist/linux/gosentry--linux-amd64.tar.gz +dist/linux/gosentry--linux-arm64.tar.gz +dist\windows\gosentry--windows-amd64.zip +``` + +The version stamped into the file names and into the binary comes from +`src/app/version.go`. + +## 6. CI Tagged releases are built automatically on both GitHub and Codeberg: @@ -144,9 +263,11 @@ The Windows binary is cross-compiled with MinGW-w64 from the Linux job, so no Windows runner is required. Each archive contains the executable plus `README.md` and `CHANGELOG.md`, matching the local `package-*` scripts. -To cut a release, bump `src/app/version.go`, then create and publish a release -with a matching `v` tag on the forge (GitHub Releases / Codeberg releases). You -can do that from the web UI or the CLI, e.g.: +### Cutting a release + +Bump `src/app/version.go`, then create and publish a release with a matching `v` +tag on the forge (GitHub Releases / Codeberg releases). You can do that from the +web UI or the CLI, e.g.: ```bash git tag v0.11.5 @@ -162,65 +283,3 @@ also allows a manual, upload-free build to smoke-test the pipeline. Codeberg publishing needs a repository secret named `RELEASE_TOKEN` (a Codeberg access token with the `write:repository` scope) under **Settings → Actions → Secrets**. GitHub uses the built-in `GITHUB_TOKEN`. - -## Run From Source - -Windows: - -```powershell -# Fyne requires CGO on Windows. MSYS2 UCRT64 provides the C compiler and native -# libraries used by the desktop backend. -$env:Path = 'C:\msys64\ucrt64\bin;' + $env:Path -$env:CGO_ENABLED = '1' - -# go run starts the app from source. Use scripts\build-windows.bat when you need -# a standalone .exe without a console window. -& 'C:\Program Files\Go\bin\go.exe' run ./cmd/gosentry -``` - -Linux: - -```bash -# CGO must stay enabled because the Fyne GUI links against native Linux desktop -# libraries. -CGO_ENABLED=1 go run ./cmd/gosentry -``` - -## Project Layout - -- `cmd/gosentry` — entry point; starts the desktop app. -- `src/domain` — pure value types: `Job`, `Config`, `RunRecord`, `Schedule`, `JobRuntime`. -- `src/app` — `Service`: sole owner of job and runtime state; emits typed events to the UI. -- `src/scheduler` — pure timing loop; calls `Service.RunDue` on every tick. -- `src/runner` — shell command execution, log file writing, and log cleanup. -- `src/storage` — JSON persistence (`gosentry.json`, `jobs.json`). -- `src/platform/autostart` — `Manager` interface with Windows (shortcut) and Linux (XDG) implementations. -- `src/platform/desktop` — desktop entry and icon under XDG data home (Linux only). -- `src/platform/winproc` — hidden-window startup flags (Windows only). -- `src/ui` — Fyne windows, tabs, and dialogs; reads service state through events. -- `assets` — app icons embedded into the application binary. -- `scripts` — build helpers. -- `docs` — architecture notes, changelog, and roadmap. - -Build outputs are written to `dist/`. - -## Dependencies - -GoSentry keeps the direct dependency list intentionally small: - -- [`fyne.io/fyne/v2`](https://fyne.io/) for the native GUI. -- `github.com/robfig/cron/v3` for cron schedule parsing. - -The remaining entries in `go.mod` are indirect dependencies pulled by Fyne and the Go module resolver. - -Source repositories for mirroring: - -- Go toolchain: https://go.googlesource.com/go -- Fyne: https://github.com/fyne-io/fyne -- robfig/cron: https://github.com/robfig/cron - -To list every direct and indirect Go module used by the current checkout: - -```bash -go list -m all -```