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

# 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](/en/getting-started/2.2-node-configuration).\
For initializing a new network with a genesis file, see [Genesis Setup and Network Initialization](/en/getting-started/2.3-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`](https://github.com/stable-net/go-stablenet/blob/master/build/ci.go)                           | Main build orchestrator with subcommands |
| [`Makefile`](https://github.com/stable-net/go-stablenet/blob/master/Makefile)                                 | Convenience wrapper for common tasks     |
| [`internal/build/util.go`](https://github.com/stable-net/go-stablenet/blob/master/internal/build/util.go)     | Build utility functions                  |
| [`internal/build/gotool.go`](https://github.com/stable-net/go-stablenet/blob/master/internal/build/gotool.go) | Go toolchain management                  |
| [`internal/build/env.go`](https://github.com/stable-net/go-stablenet/blob/master/internal/build/env.go)       | Environment detection (CI/local)         |
| [`build/checksums.txt`](https://github.com/stable-net/go-stablenet/blob/master/build/checksums.txt)           | Dependency checksums for verification    |

## Building from Source

### Using Make

StableNet can be built easily using Makefile targets.

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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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 ./...
```