Skip to main content

​
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.
  1. Makefile
    An interface for developers to quickly build binaries or run tests locally.
  2. 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 point
  • build/ci.go: Core logic for CI/CD and release automation
  • build/bin/: Output directory for local build artifacts
  • internal/build/: Checksum, download, and verification logic
  • params/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

ComponentSourceExample
Majorparams.VersionMajor0
Minorparams.VersionMinor1
Patchparams.VersionPatch0
Metaparams.VersionMetastable
Git CommitInjected at build timea1b2c3d4
Git DateDerived from commit20240115

​
Version String Formats

  • 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.
TargetCommandOutput
gstablemake gstableMain node binary
genesis_generatormake genesis_generatorGenesis generation tool
allmake allAll executables
testmake testRun tests
lintmake lintRun linting
cleanmake cleanClean build artifacts
All outputs are generated in the 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:
  • amd64
  • 386
  • arm (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.

​
CI Platform Matrix

PlatformOSArchitecturesPurpose
Travis CILinuxamd64, arm64, 386, armMain builds and tests
Travis CImacOSamd64, arm64macOS binaries
AppVeyorWindowsamd64, 386Windows 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.
ArchivePlatform
tar.gzLinux / macOS
zipWindows
Filename format:
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

​
Build Tags

TagPurpose
urfave_cli_no_docsDisable CLI documentation generation
ckzgEnable KZG cryptography
integrationtestsIntegration tests
netgoPure Go networking
osusergoPure 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:
  1. Dual-layer structure using Makefile and build/ci.go
  2. Multi-platform CI
  3. Cross-compilation support
  4. Reproducible release artifacts
  5. Checksum-based dependency verification
  6. Embedded version metadata in all binaries
This architecture provides StableNet with a consistent and predictable build and deployment environment.