1# Building from source
  2
  3## Prerequisites
  4
  5- Go 1.21 or later
  6- `git` (for fetching dependencies)
  7
  8## Standard build
  9
 10```bash
 11# Clone the repository
 12git clone https://codeberg.org/maxwelljensen/llm_aggregator.git
 13cd llm_aggregator
 14
 15# Download dependencies
 16go mod tidy
 17
 18# Build the binary
 19go build .
 20
 21# Run
 22./llm_aggregator --help
 23```
 24
 25The binary is placed in the repository root as `llm_aggregator`.
 26
 27## Development build with version info
 28
 29During development builds, version information is injected via ldflags:
 30
 31```bash
 32go build -ldflags "
 33  -s -w
 34  -X main.version=$(git describe --tags --always --dirty 2>/dev/null || echo 'dev')
 35  -X main.buildDate=$(date -u +%Y-%m-%d)
 36.
 37```
 38
 39The `--version` flag will then report the current git tag + commit hash.
 40
 41## Release builds (goreleaser)
 42
 43The project uses [goreleaser](https://goreleaser.com/) for cross-platform
 44release builds. The `.goreleaser.yaml` configuration builds for:
 45
 46| OS | Architectures |
 47|----|---------------|
 48| Linux | `386`, `amd64`, `arm64` |
 49| Windows | `386`, `amd64`, `arm64` |
 50| Darwin (macOS) | `amd64`, `arm64` |
 51
 52```bash
 53# Install goreleaser (once)
 54go install github.com/goreleaser/goreleaser/v2@latest
 55
 56# Build release binaries locally
 57goreleaser build --clean
 58```
 59
 60Release artifacts are written to `dist/`.
 61
 62## Cross-compilation
 63
 64Go makes cross-compilation straightforward:
 65
 66```bash
 67# Linux on macOS (or vice versa)
 68GOOS=linux GOARCH=amd64 go build .
 69
 70# Windows
 71GOOS=windows GOARCH=amd64 go build -o llm_aggregator.exe .
 72
 73# ARM64 Linux
 74GOOS=linux GOARCH=arm64 go build .
 75```
 76
 77## Running tests
 78
 79```bash
 80# All tests
 81go test ./...
 82
 83# With race detector
 84go test ./... -race
 85
 86# With coverage
 87go test ./... -cover
 88```
 89
 90## Linting
 91
 92The project uses [golangci-lint](https://golangci-lint.run/):
 93
 94```bash
 95# Run linter
 96golangci-lint run
 97
 98# Auto-fix formatting issues
 99gofmt -w .
100```
101
102## Man pages
103
104`man` pages are in `docs/`:
105
106- `docs/llm_aggregator.1` — command reference
107- `docs/llm_aggregator.5` — configuration file reference
108
109To install them system-wide:
110
111```bash
112# Copy man pages to your man directory
113cp docs/llm_aggregator.1 /usr/local/share/man/man1/
114cp docs/llm_aggregator.5 /usr/local/share/man/man5/
115
116# Rebuild the whatis database (if needed)
117mandb
118
119# View the man page
120man llm_aggregator
121```
122
123To add them to your personal `$MANPATH`:
124
125```bash
126# Add to shell profile (~/.bashrc, ~/.zshrc, etc.)
127export MANPATH="$MANPATH:$HOME/.local/share/man"
128
129# Create the directories and copy man pages
130mkdir -p ~/.local/share/man/man1
131mkdir -p ~/.local/share/man/man5
132cp docs/llm_aggregator.1 ~/.local/share/man/man1/
133cp docs/llm_aggregator.5 ~/.local/share/man/man5/
134
135# Now you can run:
136man llm_aggregator     # section 1 (commands)
137man 5 llm_aggregator   # section 5 (config file)
138```
139
140## Verifying the build
141
142After building, verify the binary works:
143
144```bash
145# Show version and default config
146./llm_aggregator --version
147
148# Run a dry-run (no API key needed)
149./llm_aggregator -f feeds.txt -p "test" -D --verbose
150```
151
152Where `feeds.txt` is a real feeds file to test end-to-end.
153
154## Dependencies
155
156| Library | Purpose |
157|---------|---------|
158| [`gofeed`](https://github.com/mmcdole/gofeed) | RSS/Atom/JSON feed parsing |
159| [`openai-go`](https://github.com/openai/openai-go) | OpenAI-compatible API calls |
160| [`bubbletea`](https://github.com/charmbracelet/bubbletea) | TUI framework |
161| [`lipgloss`](https://github.com/charmbracelet/lipgloss) | Terminal styling |
162| [`glamour`](https://github.com/charmbracelet/glamour) | Markdown rendering (TUI) |
163| [`go-arg`](https://github.com/alexflint/go-arg) | CLI argument parsing |
164| [`tiktoken-go`](https://github.com/pkoukk/tiktoken-go) | BPE token counting |
165| [`viper`](https://github.com/spf13/viper) | Configuration management |
166| [`goquery`](https://github.com/PuerkitoBio/goquery) | HTML scraping for article content |