onvif-go/.claude/BUILDING.md

Building and Releasing onvif-go

This document describes how to build binaries for multiple platforms and create releases.

Quick Start

Build for Your Current Platform

make build-cli

This builds all CLI tools for your current OS/architecture in the bin/ directory.

Build for All Platforms

make build-all

This creates binaries for:

• Linux: amd64, arm64, arm (32-bit)
• Windows: amd64, arm64
• macOS: amd64 (Intel), arm64 (Apple Silicon)

Binaries are output to bin/ directory.

Create Release Archives

make release

This:

1. Builds for all platforms
2. Creates .tar.gz archives (Linux/macOS) and .zip files (Windows)
3. Generates SHA256 checksums
4. Places everything in releases/ directory

Manual Building

Using the Build Script

# Build with automatic version detection
./build-release.sh

# Build with specific version
./build-release.sh v1.0.1

Using Go Directly

# Set platform and architecture
export GOOS=linux
export GOARCH=amd64

# Build a specific tool
go build -o bin/onvif-cli-linux-amd64 ./cmd/onvif-cli

Supported Platforms

OS	Architecture	Binary Suffix	Notes
Linux	amd64	linux-amd64	64-bit Intel/AMD
Linux	arm64	linux-arm64	64-bit ARM (Raspberry Pi 4)
Linux	arm	linux-arm	32-bit ARM (Raspberry Pi 3)
Windows	amd64	windows-amd64.exe	64-bit Windows
Windows	arm64	windows-arm64.exe	ARM Windows (Surface Pro X)
macOS	amd64	darwin-amd64	Intel Macs
macOS	arm64	darwin-arm64	Apple Silicon (M1/M2/M3)

CLI Tools

The following binaries are built:

1. onvif-cli - Comprehensive ONVIF client with full feature set
2. onvif-quick - Quick tool for common operations
3. onvif-server - ONVIF mock server for testing
4. onvif-diagnostics - Diagnostic and debugging tools

Automated Releases via GitHub Actions

Releases are automatically created when you push a tag:

# Create and push a new version tag
git tag -a v1.0.1 -m "Release version 1.0.1"
git push origin v1.0.1

The GitHub Actions workflow will:

1. Build binaries for all platforms
2. Create release archives
3. Generate checksums
4. Create a GitHub release with all artifacts
5. Build and push Docker images (multi-arch)

Release Workflow Features

• ✅ Builds for 7 platform/architecture combinations
• ✅ Creates compressed archives (.tar.gz and .zip)
• ✅ Generates SHA256 checksums for verification
• ✅ Auto-generates release notes from commits
• ✅ Supports pre-releases (tags with -rc, -beta, -alpha)
• ✅ Builds multi-architecture Docker images
• ✅ Pushes to GitHub Container Registry

Docker Images

Docker images are automatically built for:

• linux/amd64
• linux/arm64
• linux/arm/v7

Available at:

ghcr.io/0x524a/onvif-go:latest
ghcr.io/0x524a/onvif-go:v1.0.0

Manual GitHub Release

If you prefer to create releases manually:

# Build release archives
make release

# Create GitHub release using gh CLI
gh release create v1.0.1 releases/* \
  --title "Release v1.0.1" \
  --notes "Release notes here"

Version Numbering

Follow Semantic Versioning:

• v1.0.0 - Major release (breaking changes)
• v1.1.0 - Minor release (new features, backward compatible)
• v1.1.1 - Patch release (bug fixes)
• v1.0.0-rc1 - Release candidate
• v1.0.0-beta1 - Beta release
• v1.0.0-alpha1 - Alpha release

Build Flags

The build process uses the following flags:

-ldflags="-s -w -X main.Version=<version> -X main.Commit=<sha>"

• -s - Omit symbol table (smaller binary)
• -w - Omit DWARF debug info (smaller binary)
• -X main.Version - Inject version string
• -X main.Commit - Inject git commit SHA

Size Optimization

Binaries are built with CGO_ENABLED=0 and stripped flags, resulting in:

• Smaller binary sizes
• No external dependencies
• Portable across systems

Typical sizes:

• onvif-cli: ~10-15 MB
• onvif-quick: ~8-12 MB
• onvif-server: ~10-14 MB

Troubleshooting

Build Fails for Specific Platform

Some platforms may not be supported by all dependencies. Check:

go tool dist list  # List all supported platforms

Large Binary Sizes

Ensure you're using the build flags:

go build -ldflags="-s -w" -o binary ./cmd/tool

Missing Dependencies

go mod download
go mod tidy

Distribution

Once built, binaries can be distributed via:

1. GitHub Releases (automatic)
2. Package managers (homebrew, apt, etc.)
3. Container registries (Docker Hub, GHCR)
4. Direct download from your server

Verification

Users can verify downloads using checksums:

# Download binary and checksum
wget https://github.com/0x524a/onvif-go/releases/download/v1.0.0/onvif-go-v1.0.0-linux-amd64.tar.gz
wget https://github.com/0x524a/onvif-go/releases/download/v1.0.0/checksums.txt

# Verify
sha256sum -c checksums.txt --ignore-missing

Next Steps

After building:

1. Test binaries on target platforms
2. Update CHANGELOG.md with release notes
3. Create GitHub release
4. Announce on relevant channels
5. Update documentation with new features