Complete guide to building Cadence from source, development setup, and using Make for common tasks.

For end-user installation only? See Installation Guide instead.

Prerequisites

Required

Go 1.24 or later - Download Go
Git 2.20 or later - Usually pre-installed

Verify installation:

Bash

go version
git --version

Optional

golangci-lint - For linting
make - For convenient build targets (cross-platform)

Building from Source

Method 1: Using Make (Recommended)

Make automatically handles cross-platform build with version injection:

Bash

git clone https://github.com/TryCadence/Cadence.git
cd Cadence
make build

Automatically detects your OS and:

Injects version from Git tags
Injects commit hash
Injects build timestamp

Output:

Linux/macOS: bin/cadence
Windows: bin/cadence.exe

Method 2: Using Platform Scripts

Linux/macOS:

Bash

git clone https://github.com/TryCadence/Cadence.git
cd Cadence
./scripts/build.sh

Windows (PowerShell):

PowerShell

git clone https://github.com/TryCadence/Cadence.git
cd Cadence
.\scripts\build.ps1

Method 3: Direct Go (No Version Injection)

Bash

git clone https://github.com/TryCadence/Cadence.git
cd Cadence
go build -o cadence ./cmd/cadence

Note: This builds without version information.

Verify Build

Test that Cadence built correctly:

Bash

# Linux/macOS
./bin/cadence version

# Windows
.\cadence.exe version

Should display version, commit, and build time.

Make Convenience Targets

Cadence provides Make targets for common development tasks.

View All Targets

Bash

make help

Available Targets

build

Build binary with version injection:

Bash

make build

Creates bin/cadence (Linux/macOS) or bin/cadence.exe (Windows).

Features:

Cross-platform support
Automatic version detection from Git tags
Commit hash injection
Build timestamp injection

install

Install to system $GOPATH/bin:

Bash

make install

After installation, run cadence from anywhere:

Bash

cadence --help

test

Run all tests:

Bash

make test

Runs:

go test ./...

fmt

Format all code:

Bash

make fmt

Runs:

go fmt ./...

tidy

Tidy dependencies:

Bash

make tidy

Cleans up go.mod and go.sum.

lint

Run linter:

Bash

make lint

Uses golangci-lint if installed, otherwise prints message.

vet

Run go vet:

Bash

make vet

Checks for common mistakes.

run

Run Cadence directly:

Bash

make run

Runs without building binary (useful for testing).

clean

Remove build artifacts:

Bash

make clean

Removes bin/ directory.

Development Workflow

1. Clone Repository

Bash

git clone https://github.com/TryCadence/Cadence.git
cd Cadence

2. Create Feature Branch

Bash

git checkout -b feature/your-feature

3. Make Changes

Edit code in cmd/, internal/ directories.

4. Run Tests

Bash

make test

5. Format Code

Bash

make fmt
make vet

6. Lint Code

Bash

make lint

7. Build

Bash

make build

8. Test Binary

Bash

./bin/cadence --help
./bin/cadence version

9. Commit and Push

Bash

git add .
git commit -m "Feature: description"
git push origin feature/your-feature

Build Details

Version Injection

The Makefile automatically injects version information at build time:

On Linux/macOS:

makefile

VERSION := $(shell git describe --tags --always --dirty)
COMMIT := $(shell git rev-parse --short HEAD)
BUILD_TIME := $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')
LDFLAGS := -ldflags="-X github.com/TryCadence/Cadence/internal/version.Version=$(VERSION) ..."

On Windows:

PowerShell

$VERSION = & git describe --tags --always --dirty
$COMMIT = & git rev-parse --short HEAD
$BUILD_TIME = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
$LDFLAGS = "-ldflags=`"-X ... `""

Version Information

Cadence embeds version info in internal/version/version.go:

var (
	Version   = "development"
	GitCommit = "unknown"
	BuildTime = "unknown"
)

func Full() string {
	return fmt.Sprintf("Cadence version %s\nGit Commit: %s\nBuild Time: %s", 
		Version, GitCommit, BuildTime)
}

View with:

Bash

cadence version

Project Structure

Cadence/
├── cmd/cadence/              # CLI commands
│   ├── analyze.go            # Repository analysis
│   ├── web.go                # Website analysis
│   ├── webhook.go            # Webhook server
│   ├── config.go             # Configuration
│   └── main.go               # Entry point
│
├── internal/                 # Core functionality
│   ├── ai/                   # OpenAI integration
│   ├── analyzer/             # Repository analysis
│   ├── detector/             # Detection strategies
│   ├── git/                  # Git operations
│   ├── metrics/              # Metrics calculation
│   ├── reporter/             # Report generation
│   ├── web/                  # Web analysis
│   └── webhook/              # Webhook server
│
├── scripts/                  # Build scripts
│   ├── build.sh              # Linux/macOS build
│   └── build.ps1             # Windows build
│
├── Makefile                  # Build targets
├── go.mod                    # Go modules
└── go.sum                    # Module checksums

Dependencies

Key dependencies (from go.mod):

cobra - CLI framework
viper - Configuration management
go-git - Git operations
goquery - HTML parsing
openai - OpenAI API client
fiber - Web framework (webhooks)

View all with:

Bash

go mod graph

Testing

Run All Tests

Bash

make test

Or directly:

Bash

go test ./...

Run Specific Test

Bash

go test ./internal/detector -v

Test Coverage

Bash

go test ./... -cover

With Coverage Report

Bash

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

Code Quality

Format Code

Bash

make fmt

Vet Code

Bash

make vet

Lint Code

Bash

make lint

(Requires golangci-lint)

Troubleshooting Build

"go: command not found"

Install Go from golang.org/dl.

Build fails with version injection

Ensure Git is installed and repository has commits:

Bash

git log --oneline

Module errors

Clean module cache:

Bash

go clean -modcache
go mod tidy

Tests fail

Try:

Bash

go mod download
go test ./...

Contributing

For contributing to Cadence:

Fork the repository
Create feature branch: git checkout -b feature/your-feature
Make changes - follow existing code style
Run tests: make test
Format code: make fmt
Lint code: make lint
Commit: git commit -m "Feature: description"
Push: git push origin feature/your-feature
Open PR on GitHub

Next Steps

Advanced Configuration - Config options
Troubleshooting - Common issues
GitHub Repository - Source code

Development Guide