Building

Building

This guide covers all build options for PrivUtil across Linux, macOS, and Windows.

Note

go install ./cmd/privutil is disabled via build tags to prevent incomplete builds. This project requires a two-step process (build web then build Go) which is automated by the Makefile.

Prerequisites

Platform	Requirements
Linux	go, node, npm, make, gcc
macOS	go, node, npm, make (via Xcode Command Line Tools)
Windows	go, node, npm, make (via Chocolatey or WSL2)

Quick Build

make build

This runs:

1. make clean - Remove old artifacts
2. make build-web - Build React frontend
3. make build-go - Build Go binary with embedded assets

Build Targets

make build

Full clean build of frontend and backend.

make build
# Output: ./privutil binary (~25MB)

make build-web

Build only the frontend.

make build-web
# Output: web/dist/

make build-go

Build only the backend (requires web/dist to exist).

make build-go
# Output: ./privutil

make clean

Remove all build artifacts.

make clean
# Removes: privutil, web/dist, internal/server/dist, web/node_modules

Production Build

For production deployments, use ldflags to set version info:

VERSION=$(git describe --tags --always)
BUILD_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

go build -tags=manual -ldflags "-X main.Version=$VERSION -X main.BuildTime=$BUILD_TIME" \
  -o privutil ./cmd/privutil/main.go

Check version:

./privutil --version
# PrivUtil v1.0.0 (built 2026-01-23T22:00:00Z)

Cross-Compilation

Build for different platforms:

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -tags=manual -o privutil-linux-amd64 ./cmd/privutil/main.go

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -tags=manual -o privutil-darwin-arm64 ./cmd/privutil/main.go

# Windows
GOOS=windows GOARCH=amd64 go build -tags=manual -o privutil.exe ./cmd/privutil/main.go

Regenerate Protobuf

If you modify proto/privutil.proto:

make proto

This regenerates:

• proto/*.pb.go - Go server stubs
• web/src/proto/*.ts - TypeScript client

Troubleshooting

Frontend build fails

cd web && npm install

Missing dependencies

go mod tidy

Proto regeneration fails

Ensure protoc is installed:

# macOS
brew install protobuf

# Ubuntu
apt install protobuf-compiler