GopherTrunk is a single, pure-Go static binary with no system-library dependencies, which makes building it from source unusually painless. This guide walks the whole loop — clone, pick a version, build, verify — and shows how to grab a fix that hasn’t shipped in a release yet by building a specific branch.
In this post
- The fastest path — three commands to go from nothing to a working binary.
- How to pick a version —
main, a release tag, or an unmerged branch (this is how you test a fix before it lands in a release). - The full walkthrough — prerequisites, cloning, building, verifying, and
installing on your
PATH. - Keeping a clone current — the fetch / pull / rebuild loop.
- Controls and optimizations — version stamping, cross-compiling for another CPU, reproducible builds, and the Go build cache.
Quick facts
If you already know your way around a terminal, this is the whole thing:
# 1. Get the code
git clone https://github.com/MattCheramie/GopherTrunk.git
cd GopherTrunk
# 2. Build the binary (output: ./bin/gophertrunk)
make build
# 3. Confirm it works
./bin/gophertrunk version
To build a specific branch instead of the default main — for example a
bug-fix that hasn’t been released yet:
git fetch origin some-branch-name
git checkout some-branch-name
make build
Prerequisites: Go 1.25+,
git, andmake. Nothing else — GopherTrunk isCGO_ENABLED=0pure Go, so there are no C libraries, DLLs, orapt-get installsteps to chase.
The short version
GopherTrunk lives in one Git repository on GitHub. Building it is the standard
Go loop, wrapped in a Makefile:
- Clone the repository so you have a local copy with full history.
- Check out the version you want — the tip of
main, a tagged release likev0.4.8, or any branch. - Build with
make build, which compiles./cmd/gophertrunkinto./bin/gophertrunkwith the version string stamped in. - Verify with
gophertrunk versionandgophertrunk sdr list. - Optionally install the binary onto your
PATH.
Because the project is pure Go, the same source cross-compiles to Linux, macOS, and Windows on any of those hosts without a cross-toolchain. The rest of this post is the detailed version of those five steps, plus how to keep your clone current and a few build knobs worth knowing.
New to Git itself? This post assumes you can run
git cloneandgit checkout. If those aren’t second nature yet, the free Git & GitHub learning path starts from “what is version control?” and builds up to branches, remotes, and pull requests.
Prerequisites
You need three tools on your machine:
| Tool | Why | Check |
|---|---|---|
| Go 1.25 or newer | Compiles the daemon. | go version |
| Git | Clones the repo and switches versions. | git --version |
| make | Runs the build recipe (optional — you can call go build directly). |
make --version |
That is the entire list. GopherTrunk uses purego for every system call it makes
(USB, audio) and a pure-Go SQLite for its call log, so it builds with
CGO_ENABLED=0 and ships as one
static binary. There is no
libusb, no librtlsdr, no compiler toolchain to install.
On Linux and want to actually receive with an SDR after building? USB device permissions are a separate, one-time setup step. See Installing on Linux for the udev rule and
modprobeblacklist that let GopherTrunk claim your dongle withoutsudo.
If you don’t have Go yet, grab it from go.dev/dl (or your package manager), and see Installing Git if you need Git.
1. Get the code
Clone the repository over HTTPS:
git clone https://github.com/MattCheramie/GopherTrunk.git
cd GopherTrunk
This downloads the full project and its history into a GopherTrunk/ directory
and leaves you on the default branch, main. If you have SSH keys set up with
GitHub, you can use the SSH URL instead
(git@github.com:MattCheramie/GopherTrunk.git); see
Authentication for the
difference.
2. Choose your version
A fresh clone leaves you on main — the latest development tip. Most of the time
that’s exactly what you want. But there are three things you can check out, and
the difference matters:
The latest development code (main). Already where a fresh clone lands.
Newest features and fixes, but it moves between releases:
git checkout main
git pull origin main # fast-forward to the newest commits
A tagged release — a frozen, named snapshot like v0.4.8. Pick this when you
want the exact code behind a published version:
git fetch --tags
git checkout v0.4.8
A specific branch — this is the important one. When a fix or feature is still
being worked on, it lives on its own branch and is not in main or any
release yet. Building that branch is how you test the change early:
git fetch origin the-branch-name
git checkout the-branch-name
If a maintainer points you at a branch to try a fix — say
claude/some-fix-branch— those last two commands are the whole story: fetch it, check it out, then build. When the fix later merges tomainand ships in a release, you switch back withgit checkout main.
Not sure what you’re on? git status shows the current branch, and
git log --oneline -5 shows the latest commits. The
Branches lesson covers this in
depth.
3. Build it
From the repository root:
make build
That compiles ./cmd/gophertrunk and writes the binary to ./bin/gophertrunk,
stamping in the version, commit, and build time so gophertrunk version can
report exactly what you built. Under the hood it’s a plain go build — if you’d
rather not use make:
go build -o bin/gophertrunk ./cmd/gophertrunk
Want the web console too? make build produces the daemon and the terminal
UI, but the in-browser operator console is a separate bundle. To get a single
binary that also serves the web UI at /, use:
make dist
make dist builds the web front-ends first and embeds them, then builds the Go
binary. It needs Node.js/npm; plain make build does not.
4. Verify
Confirm the binary runs and reports the version you expect:
./bin/gophertrunk version
If you built a branch with a custom label, you’ll see it here — handy for confirming you’re running the right code. Then check that GopherTrunk can see your hardware:
./bin/gophertrunk sdr list
That enumerates attached SDR devices. (On Linux, if nothing shows up, revisit the USB permissions in Installing on Linux.) For a guided first run, the Launcher and the TUI walkthrough take it from here.
5. Install on your PATH
./bin/gophertrunk works fine in place. To run it as just gophertrunk from
anywhere, copy it onto your PATH:
sudo install -m 0755 bin/gophertrunk /usr/local/bin/gophertrunk
gophertrunk version
To update later, rebuild and re-run that install command — it overwrites the
old binary.
Updating an existing clone
Already have the repository cloned from a previous build? You don’t re-clone — you pull the new commits and rebuild:
cd GopherTrunk
git checkout main # make sure you're on the branch you want
git pull origin main # fetch + merge the latest commits
make build # rebuild with the new code
./bin/gophertrunk version # confirm the new version
If git pull complains about local changes, you either have edits in your
working tree or you’re on a different branch than you think. git status tells
you which; Status and diffs
explains how to read it, and Stashing
shows how to shelve local edits before pulling.
Controls and optimizations
A few build knobs worth knowing once the basics work:
Stamp a custom version label. Pass ldflags to mark a build — useful when
you’re testing a branch and want gophertrunk version to say so:
go build -trimpath \
-ldflags "-X github.com/MattCheramie/GopherTrunk/internal/version.Version=v0.4.8-mytest" \
-o bin/gophertrunk ./cmd/gophertrunk
-trimpath for reproducible builds. It strips absolute filesystem paths from
the binary so the same source produces the same bytes regardless of where you
built it. The official release pipeline uses it; you can too.
Cross-compile for another CPU or OS. Because the build is CGO_ENABLED=0,
you can target any platform from your current one just by setting GOOS and
GOARCH — no cross-toolchain required:
# A Linux arm64 binary (e.g. for a Raspberry Pi) built on an amd64 laptop
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 \
go build -o bin/gophertrunk-arm64 ./cmd/gophertrunk
The repo ships a make cross-build target that produces binaries for every
common OS/arch pair at once.
The build cache. Go caches compiled packages, so the first build of a fresh
clone is the slow one (a minute or two); subsequent rebuilds after a git pull
only recompile what changed and finish in seconds. There’s nothing to configure —
just don’t be alarmed by the first build’s time.
Clean rebuild. If a build ever behaves strangely, make clean removes
bin/ and dist/, and go clean -cache empties the compile cache for a
from-scratch rebuild.
Troubleshooting
go: command not found — Go isn’t installed or isn’t on your PATH. Install
it from go.dev/dl and reopen your terminal.
go.mod requires go >= 1.25 — your Go is too old. Check with go version
and upgrade.
make: command not found — install make (sudo apt install make,
sudo dnf install make, or Xcode command-line tools on macOS), or skip it and
run the go build command directly.
git pull says “Already up to date” but you expected changes — you’re
probably on the wrong branch, or the fix is on a branch you haven’t fetched. Run
git branch to see where you are and git fetch origin the-branch-name to pull
a specific branch down.
The binary builds but sdr list is empty — that’s a USB permissions issue,
not a build problem. See Installing on Linux.
FAQ
Do I need a compiler or system libraries to build GopherTrunk?
No. GopherTrunk is pure Go (CGO_ENABLED=0) and links no C libraries. You need
Go, Git, and optionally make — nothing else.
How do I get a fix that isn’t in a release yet?
Build the branch it’s on. git fetch origin <branch>, git checkout <branch>,
then make build. When the fix merges to main and ships in a release, switch
back with git checkout main.
What’s the difference between make build and make dist?
make build produces the daemon and terminal UI binary. make dist additionally
builds and embeds the in-browser web console, so the single binary serves the web
UI at /. make dist needs Node.js; make build does not.
Can I build a Windows or macOS binary on Linux (or vice versa)?
Yes. Set GOOS and GOARCH on a normal go build — no cross-toolchain needed,
because the build uses no cgo.
How do I update a binary I already built?
cd into your clone, git pull origin main, make build, and re-run the
install step if you copied it onto your PATH.
I’m new to Git — where do I start? The free Git & GitHub learning path takes you from your first commit through branching, remotes, and pull requests.