mix/gosentry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reorder DEVELOPMENT.md and give it a table of contents

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
mixeme
2026-07-27 22:08:03 +03:00
parent 9a45a7be6f
commit 0f171edd75
1 changed files with 143 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DEVELOPMENT.md
+143 -84
View File
@@ -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-<version>-windows-amd64.exe
@@ -97,7 +192,9 @@ The binary is copied to:
dist/linux/gosentry-<version>-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-<version>-linux-arm64
dist/windows/gosentry-<version>-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-<version>-linux-amd64.tar.gz
dist/linux/gosentry-<version>-linux-arm64.tar.gz
dist\windows\gosentry-<version>-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
```