Go Commands & Documentation — Optimization Exercises¶

#!/bin/bash
# build.sh — fast incremental build

# The build cache is safe to use — it's keyed by content hash
# Only clean when debugging cache-related issues
go build -o ./bin/app .

# If you specifically need to verify no stale state:
# go build -a ./bin/app  # -a forces rebuild of all packages
# (rarely needed — the cache handles this correctly)

# After a Go version upgrade
go clean -cache

# When debugging unusual build behavior
go clean -cache

# In CI, sometimes useful to start fresh (but cache the result!)

#!/bin/bash
# build-all-platforms-parallel.sh
set -e

mkdir -p dist

declare -A builds=(
    ["dist/app-linux-amd64"]="linux/amd64"
    ["dist/app-darwin-amd64"]="darwin/amd64"
    ["dist/app-darwin-arm64"]="darwin/arm64"
    ["dist/app-windows.exe"]="windows/amd64"
)

pids=()
for output in "${!builds[@]}"; do
    IFS='/' read -r GOOS GOARCH <<< "${builds[$output]}"
    GOOS=$GOOS GOARCH=$GOARCH go build -o "$output" . &
    pids+=($!)
    echo "Started build for $output (pid $!)"
done

# Wait for all parallel builds and collect exit codes
failed=0
for pid in "${pids[@]}"; do
    if ! wait "$pid"; then
        echo "Build failed (pid $pid)"
        failed=1
    fi
done

if [ $failed -eq 1 ]; then
    echo "One or more builds failed!"
    exit 1
fi

echo "All builds completed!"
ls -la dist/

#!/bin/bash
set -e

# Let go vet handle all packages at once (it's parallel internally)
echo "Running vet..."
go vet ./...

# Let go test run all packages with proper parallelism
echo "Running tests..."
go test -parallel=8 -count=1 ./...

# For even faster feedback on large codebases:
# Only test changed packages
CHANGED_PACKAGES=$(go list $(git diff --name-only HEAD~1 | grep '\.go$' | xargs -I{} dirname {} | sort -u | sed 's|^|./|'))
if [ -n "$CHANGED_PACKAGES" ]; then
    go test -parallel=8 $CHANGED_PACKAGES
fi

#!/bin/bash
# Only run tests for packages affected by changes

# Find changed files
CHANGED_FILES=$(git diff --name-only origin/main...HEAD)

# Get packages containing changed files
CHANGED_PKGS=$(echo "$CHANGED_FILES" | \
    grep '\.go$' | \
    xargs -I{} dirname {} | \
    sort -u | \
    xargs -I{} go list ./{} 2>/dev/null)

if [ -z "$CHANGED_PKGS" ]; then
    echo "No Go packages changed"
    exit 0
fi

echo "Testing changed packages:"
echo "$CHANGED_PKGS"

go test -parallel=8 $CHANGED_PKGS

#!/bin/bash
# generate-docs.sh — efficient documentation

set -e

# Check if documentation source has changed
# Only regenerate if .go files changed since last docs generation
LAST_DOCS_TIME=$(git log --format="%ct" -1 -- docs/ 2>/dev/null || echo 0)
LAST_CODE_TIME=$(git log --format="%ct" -1 -- '*.go' 2>/dev/null || echo 1)

if [ "$LAST_CODE_TIME" -le "$LAST_DOCS_TIME" ]; then
    echo "Documentation is up to date, skipping generation"
    exit 0
fi

echo "Generating documentation..."

# Option 1: Use pkgsite for static HTML (correct approach)
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite -open=false &
PKGSITE_PID=$!
sleep 2  # wait for server to start

# Fetch all package pages
mkdir -p docs
packages=$(go list ./...)
for pkg in $packages; do
    pkg_path=$(echo $pkg | sed 's|github.com/||')
    curl -s "http://localhost:8080/$pkg" > "docs/${pkg_path//\//_}.html" 2>/dev/null || true
done

kill $PKGSITE_PID

# Option 2: Use go doc for each package (simpler, terminal-friendly)
mkdir -p docs/text
for pkg in $(go list ./...); do
    pkg_name=$(echo $pkg | tr '/' '_')
    go doc -all "$pkg" > "docs/text/${pkg_name}.txt"
done

echo "Documentation generated in docs/"

# For most projects, the best "documentation" is:
# 1. Well-written doc comments (checked by CI)
# 2. Running example tests
# 3. pkg.go.dev (automatic for public packages)

# CI check: verify all exported symbols are documented
go list -json ./... | jq -r '.GoFiles[]' | xargs -I{} sh -c 'go doc ./$(dirname {}) 2>&1' | grep -c "missing doc"

#!/bin/bash
# incremental-docs.sh

set -e

DOCS_DIR="docs/api"
LAST_BUILD_FILE=".last-docs-build"

mkdir -p "$DOCS_DIR"

# Get the last documentation build commit
LAST_BUILD=""
if [ -f "$LAST_BUILD_FILE" ]; then
    LAST_BUILD=$(cat "$LAST_BUILD_FILE")
fi

# Find packages with changed .go files since last build
if [ -n "$LAST_BUILD" ]; then
    # Get files changed since last docs build
    CHANGED_FILES=$(git diff --name-only "$LAST_BUILD" HEAD -- '*.go' 2>/dev/null || echo "")

    if [ -z "$CHANGED_FILES" ]; then
        echo "No Go files changed since last docs build. Skipping."
        exit 0
    fi

    # Get unique package directories
    CHANGED_DIRS=$(echo "$CHANGED_FILES" | xargs -I{} dirname {} | sort -u)

    # Convert to Go package paths
    CHANGED_PKGS=""
    for dir in $CHANGED_DIRS; do
        pkg=$(go list "./$dir" 2>/dev/null || true)
        if [ -n "$pkg" ]; then
            CHANGED_PKGS="$CHANGED_PKGS $pkg"
        fi
    done
else
    # First run: build docs for all packages
    CHANGED_PKGS=$(go list ./...)
fi

if [ -z "$CHANGED_PKGS" ]; then
    echo "No packages to document"
    exit 0
fi

echo "Generating docs for changed packages:"
for pkg in $CHANGED_PKGS; do
    echo "  $pkg"
    # Safe filename from package path
    filename=$(echo "$pkg" | tr '/' '_' | tr ':' '_')
    go doc -all "$pkg" > "$DOCS_DIR/${filename}.txt" 2>/dev/null || \
        echo "  WARNING: Could not generate docs for $pkg"
done

# Update last build marker
git rev-parse HEAD > "$LAST_BUILD_FILE"

echo "Documentation updated in $DOCS_DIR"
echo "Packages documented: $(echo $CHANGED_PKGS | wc -w)"

# Strategy 1: Run only the package you're working on
go test ./internal/auth/...  # just auth package

# Strategy 2: Use test caching
go test ./...  # first run: 3 minutes
go test ./...  # second run (no changes): 0.1 seconds (cached!)

# Strategy 3: Fail fast — stop on first failure
go test -failfast ./...

# Strategy 4: Run tests in parallel within packages
go test -parallel=8 ./...

# Strategy 5: Separate fast unit tests from slow integration tests
# Use build tags:

# fast_test.go (runs by default)
func TestUserLogin(t *testing.T) { ... }

// slow_test.go (only with -tags integration)
//go:build integration
func TestUserLoginDatabase(t *testing.T) { ... }

# In development: run only unit tests
go test ./...

# In CI: run all
go test -tags integration ./...

# Run only tests matching a pattern
go test -run TestUserLogin ./internal/auth

# Run benchmark tests
go test -bench=. -benchmem ./...

# Run with verbose output for debugging
go test -v -run TestSpecific ./pkg/...

# Run with timeout
go test -timeout 30s ./...

# Step 1: Strip debug symbols and DWARF
go build -ldflags="-s -w" -o app ./cmd/server
# Binary size: ~9MB (40% reduction)

# Step 2: Use UPX compression (optional, adds startup latency)
# upx --best --lzma app
# Binary size: ~4MB (but slower startup)

# Step 3: Static binary for minimal Docker image
CGO_ENABLED=0 GOOS=linux go build \
    -ldflags="-s -w" \
    -o app \
    ./cmd/server
# Now you can use scratch or distroless image!

# Dockerfile for minimal image:
cat > Dockerfile << 'EOF'
# Build stage
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o app ./cmd/server

# Final stage — scratch or distroless
FROM gcr.io/distroless/static:nonroot
# or: FROM scratch (no shell, no utilities)
COPY --from=builder /app/app /app
ENTRYPOINT ["/app"]
EOF

# Docker image size comparison:
# golang:1.21 + binary:   ~900MB
# alpine + binary:        ~20MB
# distroless + binary:    ~11MB
# scratch + binary:       ~9MB

# Step 4: Check what's making your binary large
go tool nm app | sort -k 2 -r | head -20  # largest symbols
go tool nm app | grep "\.strtab\|\.symtab"  # debug data

# Use gosize to get a breakdown by package:
go install github.com/bradfitz/gosize@latest
gosize app