Skip to main content
This guide covers building Aceplay from source, including prerequisites, build commands, and cross-compilation.

​
Prerequisites

1

Install Go

Aceplay requires Go 1.22 or higher (Go 1.25.0 is used in development).
# Check your Go version
go version
Download from go.dev if needed.
2

Install Make

The build system uses Make for task automation.
# Debian/Ubuntu
sudo apt install build-essential

# Fedora/RHEL
sudo dnf install make

# Arch Linux
sudo pacman -S make
3

Clone the repository

git clone https://github.com/crstian19/aceplay.git
cd aceplay

​
Quick Build

The fastest way to build for your current platform: 
make build
This creates the binary at build/aceplay.

​
Build Commands

​
Standard Build

Build with version information embedded from Git: 
make build
What it does:
  • Compiles for your current platform (OS/architecture)
  • Injects version from Git tags
  • Injects commit hash and build date
  • Outputs to build/aceplay
Version information: 
VERSION := $(shell git describe --tags --always --dirty)
COMMIT := $(shell git rev-parse --short HEAD)
DATE := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
These are injected via ldflags: 
-ldflags "-X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)"

​
Build for All Platforms

Cross-compile for Linux AMD64 and ARM64: 
make build-all
Output: Creates binaries in dist/:
  • dist/aceplay-linux-amd64
  • dist/aceplay-linux-arm64

​
Manual Build

Build directly with Go (without version info): 
go build -o build/aceplay ./cmd

​
Cross-Compilation

Build for a specific platform: 
# For Linux AMD64
GOOS=linux GOARCH=amd64 go build -o build/aceplay-linux-amd64 ./cmd

# For Linux ARM64 (e.g., Raspberry Pi)
GOOS=linux GOARCH=arm64 go build -o build/aceplay-linux-arm64 ./cmd

​
Installation

​
Install to System

Install the built binary to /usr/bin: 
sudo make install
What it does:
  • Builds the binary (if not already built)
  • Installs to /usr/bin/aceplay with executable permissions
  • Installs desktop file to /usr/share/applications/aceplay.desktop
Custom install location: 
sudo make install DESTDIR=/usr/local

​
Install for Development

Install to $GOPATH/bin for local development: 
make dev-install
This is useful when you want the binary in your PATH without sudo.

​
Uninstall

Remove installed files: 
sudo make uninstall

​
Dependency Management

​
Download Dependencies

make deps
This runs:
  • go mod download - Downloads all dependencies
  • go mod tidy - Cleans up unused dependencies

​
Update Dependencies

# Update specific dependency
go get -u github.com/spf13/cobra@latest

# Update all dependencies
go get -u ./...

# Clean up
make tidy

​
Verify Dependencies

make tidy
Runs go mod tidy and go mod verify to ensure integrity.

​
Build Flags and Options

​
Version Information

The Makefile automatically injects version information: 
VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
COMMIT := $(shell git rev-parse --short HEAD 2>/dev/null || echo "unknown")
DATE := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
LDFLAGS := -ldflags "-X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)"

​
Build Directories

  • build/ - Single platform builds (make build)
  • dist/ - Cross-platform builds (make build-all)

​
Clean Build Artifacts

make clean
Removes:
  • build/ directory
  • dist/ directory
  • Go build cache

​
Running Without Installing

​
Run Directly

make run
Builds and runs with version info. Equivalent to: 
go run -ldflags "..." ./cmd

​
Run with Hot Reload

For active development with automatic rebuilds: 
make run-live
Requires air: 
go install github.com/cosmtrek/air@latest

​
Watch for Changes

Auto-rebuild on file changes (requires entr): 
make watch

​
Troubleshooting

​
Go Version Too Old

go: module requires Go 1.22
Solution: Update Go from go.dev/dl

​
Missing Dependencies

package X is not in GOROOT
Solution: Download dependencies: 
make deps

​
Permission Denied During Install

install: cannot create /usr/bin/aceplay: Permission denied
Solution: Use sudo: 
sudo make install

​
Cross-Compilation Errors

If cross-compilation fails, ensure you have the target toolchain: 
# For ARM64 on AMD64 system
sudo apt install gcc-aarch64-linux-gnu

​
Next Steps

Testing

Learn how to run tests and ensure code quality

Contributing

Guidelines for contributing to the project

Build docs developers (and LLMs) love

Get started for freeTalk to us