> ## 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.

# Build and CI/CD

## 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](/en/getting-started/2.1-installation-and-building) and [Node Configuration](/en/getting-started/2.2-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

| 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 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.

```text theme={null}
-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   |

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

```bash theme={null}
GOOS=linux GOARCH=arm64 make gstable
```

### ARM v7 Example

```bash theme={null}
GOOS=linux GOARCH=arm GOARM=7 make gstable
```

## CI/CD Pipeline Architecture

go-stablenet uses a **multi-platform CI environment**.

### CI Platform Matrix

| 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       |

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

| 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

```text theme={null}
-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.