Installation and Building

Purpose and Scope

This document provides detailed instructions for building StableNet from source. It covers the build system architecture, available build targets, and cross-compilation options.

For information on configuring a built node, see Node Configuration.
For initializing a new network with a genesis file, see Genesis Setup and Network Initialization.

Prerequisites

Building StableNet from source requires Go 1.22 or later.

Additional dependencies required for building:

• C compiler (gcc or clang) — required for CGO-enabled packages
• Git — required for embedding version metadata
• Make (optional, for convenience targets)

Build System Architecture

The StableNet build system is centered around Go-based build scripts that generate node executables, handle build environment detection, and apply shared build logic.

Build System Components

File Path	Purpose
build/ci.go	Main build orchestrator with subcommands
Makefile	Convenience wrapper for common tasks
internal/build/util.go	Build utility functions
internal/build/gotool.go	Go toolchain management
internal/build/env.go	Environment detection (CI/local)
build/checksums.txt	Dependency checksums for verification

Building from Source

Using Make

StableNet can be built easily using Makefile targets.

git clone https://github.com/stable-net/go-stablenet
cd go-stablenet

# Build only the gstable client
make gstable

# Build only genesis_generator
make genesis_generator

# Build all executables (gstable, abigen, bootnode, evm, rlpdump, clef, genesis_generator, etc.)
make all

# Verify the build
./build/bin/gstable version

All built binaries are created in the build/bin/ directory.

Using build/ci.go Directly

For finer-grained control, you can invoke the build script directly:

# Build only gstable
go run build/ci.go install ./cmd/gstable

# Build for a specific architecture (e.g. ARM64)
go run build/ci.go install -arch arm64 ./cmd/gstable

# Create a statically linked binary (Linux)
go run build/ci.go install -static ./cmd/gstable

# Automatically download the Go version specified in checksums.txt and build
go run build/ci.go install -dlgo ./cmd/gstable

# Build all executables
go run build/ci.go install

Flags available for the install command:

Flag	Description
-dlgo	Download and use a specific Go version from checksums.txt
-arch	Target architecture (amd64, 386, arm, arm64)
-cc	C compiler for cross-compilation
-static	Create a statically linked executable (Linux)

Available Build Targets

All executables are built into build/bin/:

Executable	Purpose	Source Path
gstable	Main StableNet client	cmd/gstable/
genesis_generator	Genesis file generator	cmd/genesis_generator/
abigen	Solidity ABI to Go binding generator	cmd/abigen/
bootnode	Lightweight bootstrap node	cmd/bootnode/
evm	EVM testing tool	cmd/evm/
rlpdump	RLP data structure inspector	cmd/rlpdump/
clef	External account signer	cmd/clef/
devp2p	P2P network utilities	cmd/devp2p/

Cross-Compilation

The build system supports cross-compilation for multiple architectures and operating systems using Go’s built-in cross-compilation features and external C toolchains.

Supported Platforms

The CI system builds for the following platforms:

Platform	Architecture	Notes
Linux	amd64	Default, full support
Linux	386	32-bit Intel/AMD
Linux	arm	ARMv5, ARMv6, ARMv7 (GOARM variants)
Linux	arm64	64-bit ARM
macOS	amd64	Intel Macs
macOS	arm64	Apple Silicon (M1/M2)
Windows	amd64	64-bit Windows
Windows	386	32-bit Windows

Build Verification

After building, run tests to verify correct operation:

# Run quick tests
make test-short

# Run full test suite
make test

# Run lint checks
make lint

The build/ci.go test command supports the following options:

# Coverage report
go run build/ci.go test -coverage ./...

# Race detection
go run build/ci.go test -race ./...

# Verbose output
go run build/ci.go test -v ./...