Documentation Index
Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
Use this file to discover all available pages before exploring further.
Purpose and Scope
This document describes the overall build system and CI/CD pipeline of go-stablenet.
It covers how to build binaries in a local environment, the structure of the CI/CD pipeline, and the process for generating release artifacts, with a focus on pre-built binaries as the primary distribution method.
For information on installing pre-built binaries or configuring a running node, see Installation and Building and Node Configuration.
Build System Architecture
The go-stablenet project uses a dual-layer build system.
- Makefile
An interface for developers to quickly build binaries or run tests locally.
- build/ci.go
An integrated build tool responsible for CI/CD execution, cross-compilation, and release archive generation.
The Makefile internally invokes build/ci.go and is designed so that local builds and CI builds produce results that are as identical as possible.
Build System Components
Makefile: Developer-facing entry pointbuild/ci.go: Core logic for CI/CD and release automationbuild/bin/: Output directory for local build artifactsinternal/build/: Checksum, download, and verification logicparams/version.go: Version definition
Version Management
Version information is centrally managed in params/version.go and is embedded into all binaries at build time.
Version Structure
| Component | Source | Example |
|---|
| Major | params.VersionMajor | 0 |
| Minor | params.VersionMinor | 1 |
| Patch | params.VersionPatch | 0 |
| Meta | params.VersionMeta | stable |
| Git Commit | Injected at build time | a1b2c3d4 |
| Git Date | Derived from commit | 20240115 |
- Version:
0.1.0
- VersionWithMeta:
0.1.0-stable
- ArchiveVersion:
0.1.0-a1b2c3d4
- VersionWithCommit:
0.1.0-stable-a1b2c3d4-20240115
Version metadata is injected at compile time using linker flags.
-X github.com/ethereum/go-ethereum/internal/version.gitCommit=<commit>
-X github.com/ethereum/go-ethereum/internal/version.gitDate=<date>
Local Builds
Makefile-Based Builds
The Makefile simplifies the most common build tasks.
| Target | Command | Output |
|---|
| gstable | make gstable | Main node binary |
| genesis_generator | make genesis_generator | Genesis generation tool |
| all | make all | All executables |
| test | make test | Run tests |
| lint | make lint | Run linting |
| clean | make clean | Clean build artifacts |
build/bin/ directory.
build/ci.go-Based Builds
build/ci.go is a tool for reproducing the same build conditions locally as in the CI environment.
Primary responsibilities:
- Cross-compilation
- Release archive generation
- Checksum verification
- Application of CI-specific build flags
Cross Compilation
The build system supports the following architectures:
amd64386arm (GOARM v5/v6/v7)arm64
ARM64 Example
GOOS=linux GOARCH=arm64 make gstable
ARM v7 Example
GOOS=linux GOARCH=arm GOARM=7 make gstable
CI/CD Pipeline Architecture
go-stablenet uses a multi-platform CI environment.
| Platform | OS | Architectures | Purpose |
|---|
| Travis CI | Linux | amd64, arm64, 386, arm | Main builds and tests |
| Travis CI | macOS | amd64, arm64 | macOS binaries |
| AppVeyor | Windows | amd64, 386 | Windows builds |
Travis CI
- Triggers: master branch, tags, pull requests
- Multi-Go-version testing
- Docker image builds
- Release archive generation
AppVeyor
- Windows-only builds
- ZIP archive generation
- Signed binary outputs
Release Artifacts
Archive Generation
Release archives include executables and license files.
| Archive | Platform |
|---|
| tar.gz | Linux / macOS |
| zip | Windows |
gstable-{platform}-{arch}-{version}.{ext}
Signing and Upload
- Optional PGP or Signify signatures
- Upload to Azure Blob Storage
- Performed only for master or tagged builds
CI Tests and Linting
Tests
CI tests are executed with the following conditions:
- Timeout: 20 minutes
- Limited parallelism (
-p 1)
- Integration test tags enabled
- Optional race detection
Linting
golangci-lint is used, with the following linters enabled:
- goimports
- govet
- staticcheck
- ineffassign
- misspell
- unused
- whitespace
Dependency Management
All external dependencies are managed via build/checksums.txt.
- SHA256 verification before download
- Reproducible builds
- Identical behavior in CI and local builds
Build Flags and Linker Settings
| Tag | Purpose |
|---|
| urfave_cli_no_docs | Disable CLI documentation generation |
| ckzg | Enable KZG cryptography |
| integrationtests | Integration tests |
| netgo | Pure Go networking |
| osusergo | Pure Go user lookup |
Linker Flags
-ldflags "-X ...gitCommit -X ...gitDate -s -trimpath"
Summary
The key characteristics of the go-stablenet build and CI/CD system are:
- Dual-layer structure using Makefile and build/ci.go
- Multi-platform CI
- Cross-compilation support
- Reproducible release artifacts
- Checksum-based dependency verification
- Embedded version metadata in all binaries
This architecture provides StableNet with a consistent and predictable build and deployment environment.
