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 <noreply@anthropic.com>
This commit is contained in:
mixeme
+143
-84
@@ -1,18 +1,50 @@
|
|||||||
# GoSentry — Development
|
# 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.
|
- [Go](https://go.dev/) 1.22 or newer.
|
||||||
|
- MSYS2 with UCRT64 GCC in `C:\msys64\ucrt64\bin` (plus `windres` for the icon
|
||||||
Windows:
|
resource).
|
||||||
|
|
||||||
- MSYS2 with UCRT64 GCC in `C:\msys64\ucrt64\bin`.
|
|
||||||
|
|
||||||
Install these dependencies on Windows:
|
|
||||||
|
|
||||||
```powershell
|
```powershell
|
||||||
# 1. Install Go 1.22 or newer from https://go.dev/dl/.
|
# 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
|
Test-Path C:\msys64\ucrt64\bin\windres.exe
|
||||||
```
|
```
|
||||||
|
|
||||||
Linux:
|
### Toolchain — Linux
|
||||||
|
|
||||||
|
- [Go](https://go.dev/) 1.22 or newer.
|
||||||
- A C compiler.
|
- A C compiler.
|
||||||
- [Fyne](https://fyne.io/) native build dependencies, including OpenGL/X11 development packages.
|
- [Fyne](https://fyne.io/) native build dependencies, including OpenGL/X11
|
||||||
|
development packages.
|
||||||
On Debian/Ubuntu, the Linux dependencies are typically:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Go builds the application, gcc is required by CGO/Fyne, and the OpenGL/X11
|
# 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
|
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
|
### Windows
|
||||||
|
|
||||||
@@ -59,9 +155,8 @@ sudo apt install golang gcc libgl1-mesa-dev xorg-dev
|
|||||||
.\scripts\build-windows.bat
|
.\scripts\build-windows.bat
|
||||||
```
|
```
|
||||||
|
|
||||||
The Windows build is created as a GUI application, so it does not open a terminal window.
|
The Windows build is created as a GUI application, so it does not open a
|
||||||
|
terminal window. The binary is written to:
|
||||||
The binary is written to:
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
dist\windows\gosentry-<version>-windows-amd64.exe
|
dist\windows\gosentry-<version>-windows-amd64.exe
|
||||||
@@ -97,7 +192,9 @@ The binary is copied to:
|
|||||||
dist/linux/gosentry-<version>-linux-amd64
|
dist/linux/gosentry-<version>-linux-amd64
|
||||||
```
|
```
|
||||||
|
|
||||||
### Release build from Linux
|
## 5. Building a Release
|
||||||
|
|
||||||
|
### All targets from Linux
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Interactively choose Linux amd64, Linux arm64, Windows amd64, or all artifacts
|
# 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
|
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:
|
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`
|
Windows runner is required. Each archive contains the executable plus `README.md`
|
||||||
and `CHANGELOG.md`, matching the local `package-*` scripts.
|
and `CHANGELOG.md`, matching the local `package-*` scripts.
|
||||||
|
|
||||||
To cut a release, bump `src/app/version.go`, then create and publish a release
|
### Cutting 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.:
|
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
|
```bash
|
||||||
git tag v0.11.5
|
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
|
Codeberg publishing needs a repository secret named `RELEASE_TOKEN` (a Codeberg
|
||||||
access token with the `write:repository` scope) under
|
access token with the `write:repository` scope) under
|
||||||
**Settings → Actions → Secrets**. GitHub uses the built-in `GITHUB_TOKEN`.
|
**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
|
|
||||||
```
|
|
||||||
|
|||||||
Reference in New Issue
Block a user