Building Go Overlay¶

This guide covers how to build Go Overlay from source and set up your development environment.

Prerequisites¶

Before building Go Overlay, ensure you have the following installed:

Go: Version 1.21 or later
Make: For using the Makefile commands
Git: For cloning the repository

Installing Go¶

If you don't have Go installed:

LinuxmacOSWindows

# Download and install Go
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz

# Add to PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Verify installation
go version

# Using Homebrew
brew install go

# Verify installation
go version

Download the installer from golang.org and follow the installation wizard.

Getting the Source Code¶

Clone the repository:

git clone https://github.com/srelabz/go-entrypoint.git
cd go-entrypoint

Development Dependencies¶

Install development dependencies:

# Install Go dependencies
go mod download

# Verify dependencies
go mod verify

Optional Development Tools¶

These tools can improve your development experience:

# Install golangci-lint for linting
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

# Install gofumpt for stricter formatting
go install mvdan.cc/gofumpt@latest

# Install staticcheck for static analysis
go install honnef.co/go/tools/cmd/staticcheck@latest

Building the Project¶

Using Make Commands¶

The project includes a Makefile with convenient commands:

Build¶

Build the binary:

make build

This creates the go-overlay binary in the current directory.

Install¶

Install Go Overlay to your system:

make install

This installs the binary to /go-overlay (requires sudo on Linux/macOS).

Default installation path: - Linux/macOS: /go-overlay - Windows: C:\Program Files\go-overlay\go-overlay.exe

Uninstall¶

Remove the installed binary:

make uninstall

This removes the binary from /usr/local/bin/ (requires sudo on Linux/macOS).

Clean¶

Remove build artifacts:

make clean

This removes the compiled binary and any temporary files.

Manual Build Commands¶

If you prefer not to use Make, you can build manually:

# Build for current platform
go build -o go-overlay .

# Build with optimizations
go build -ldflags="-s -w" -o go-overlay .

# Build for specific platform
GOOS=linux GOARCH=amd64 go build -o go-overlay-linux-amd64 .

Build Flags¶

Common build flags:

-ldflags="-s -w": Strip debug information (smaller binary)
-ldflags="-X main.version=1.0.0": Set version at build time
-tags=netgo: Use pure Go network stack
-trimpath: Remove file system paths from binary

Example with all flags:

go build -ldflags="-s -w -X main.version=1.0.0" -trimpath -o go-overlay .

Cross-Compilation¶

Build for different platforms:

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o go-overlay-linux-amd64 .

# Linux ARM64
GOOS=linux GOARCH=arm64 go build -o go-overlay-linux-arm64 .

# macOS AMD64
GOOS=darwin GOARCH=amd64 go build -o go-overlay-darwin-amd64 .

# macOS ARM64 (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o go-overlay-darwin-arm64 .

# Windows AMD64
GOOS=windows GOARCH=amd64 go build -o go-overlay-windows-amd64.exe .

Local Testing¶

Running Tests¶

Run the test suite:

# Run all tests
make test

# Or manually
go test ./...

# Run tests with verbose output
go test -v ./...

# Run tests with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Running Locally¶

Test your build locally:

# Build the binary
make build

# Create a test configuration
cat > services.toml << EOF
[[services]]
name = "test-service"
command = "echo"
args = ["Hello from Go Overlay"]
enabled = true
EOF

# Run in daemon mode
./go-overlay

# In another terminal, check status
./go-overlay status

Testing with Docker¶

Test the binary in a Docker container:

# Dockerfile.test
FROM alpine:latest

# Copy the binary
COPY go-overlay /go-overlay

# Copy test configuration
COPY services.toml /services.toml

# Run
ENTRYPOINT ["/go-overlay"]

Build and run:

# Build the binary
make build

# Build Docker image
docker build -f Dockerfile.test -t go-overlay-test .

# Run container
docker run --rm go-overlay-test

Development Workflow¶

1. Make Changes¶

Edit the source code using your preferred editor.

2. Format Code¶

Format your code before committing:

# Using gofmt
gofmt -w .

# Or using gofumpt (stricter)
gofumpt -w .

3. Run Linters¶

Check code quality:

# Using golangci-lint
golangci-lint run

# Using staticcheck
staticcheck ./...

# Using go vet
go vet ./...

4. Run Tests¶

Ensure all tests pass:

make test

5. Build and Test¶

Build and test locally:

make build
./go-overlay --help

Debugging¶

Using Delve Debugger¶

Install Delve:

go install github.com/go-delve/delve/cmd/dlv@latest

Debug your code:

# Debug the main package
dlv debug

# Debug with arguments
dlv debug -- --config=/path/to/config.toml

# Debug tests
dlv test ./pkg/service

Adding Debug Logs¶

Add debug logging during development:

import "log"

log.Printf("Debug: service state = %v", service.State)

Using pprof for Profiling¶

Profile your application:

import (
    "net/http"
    _ "net/http/pprof"
)

// In main or init
go func() {
    log.Println(http.ListenAndServe("localhost:6060", nil))
}()

Access profiles at http://localhost:6060/debug/pprof/

Troubleshooting¶

Build Fails¶

If the build fails:

# Clean and rebuild
make clean
go mod tidy
make build

Dependency Issues¶

If you encounter dependency issues:

# Update dependencies
go get -u ./...
go mod tidy

# Verify dependencies
go mod verify

Permission Issues¶

If you get permission errors during install:

# Use sudo on Linux/macOS
sudo make install

# Or install to user directory
go install .

IDE Setup¶

VS Code¶

Recommended extensions: - Go (golang.go) - Go Test Explorer

Settings (.vscode/settings.json):

{
    "go.useLanguageServer": true,
    "go.lintTool": "golangci-lint",
    "go.lintOnSave": "package",
    "go.formatTool": "gofumpt"
}

GoLand¶

GoLand has built-in Go support. Configure:

Go to Settings → Go → Build Tags & Vendoring
Enable Go Modules integration
Set GOROOT to your Go installation

Next Steps¶

Read the Contributing Guide to learn how to contribute
Check the Roadmap to see planned features
Explore the codebase and documentation

Happy coding! 🚀