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

# 설치 및 빌드

## 목적 및 범위

이 문서는 소스에서 StableNet을 빌드하는 방법에 대한 상세 지침을 제공합니다. 빌드 시스템 아키텍처, 사용 가능한 빌드 타겟, 크로스 컴파일 옵션을 다룹니다.

빌드된 노드 구성에 대한 정보는 [노드 구성](/ko/getting-started/2.2-node-configuration)을 참조하세요. 제네시스 파일로 새 네트워크를 초기화하는 방법은 [제네시스 설정 및 네트워크 초기화](/ko/getting-started/2.3-genesis-setup-and-network-initialization)를 참조하세요.

## 사전 요구사항

StableNet은 소스에서 빌드하려면 **Go 1.22 이상**이 필요합니다.

빌드에 필요한 추가 의존성:

* **C 컴파일러** (gcc 또는 clang) - CGO 활성화 패키지용
* **Git** - 버전 메타데이터 임베딩용
* **Make** (선택사항, 편의 타겟용)

## 빌드 시스템 아키텍처

StableNet 빌드 시스템은 노드 실행 바이너리를 생성하기 위한 Go 기반 빌드 스크립트를 중심으로 구성되며, 빌드 환경 감지와 공통 빌드 로직을 담당합니다.

### 빌드 시스템 컴포넌트

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

## 소스에서 빌드

### Make 사용

StableNet은 Makefile 타겟을 사용해 쉽게 빌드할 수 있습니다.

```bash theme={null}
git clone https://github.com/stable-net/go-stablenet
cd go-stablenet

# gstable 클라이언트만 빌드
make gstable

# genesis_generator만 빌드
make genesis_generator

# 모든 실행 파일 빌드 (gstable, abigen, bootnode, evm, rlpdump, clef, genesis_generator 등)
make all

# 빌드 확인
./build/bin/gstable version
```

빌드된 바이너리는 모두 `build/bin/` 디렉터리에 생성됩니다.

### build/ci.go 직접 사용

더 세밀한 제어가 필요한 경우 빌드 스크립트를 직접 호출할 수 있습니다:

```bash theme={null}
# gstable만 빌드
go run build/ci.go install ./cmd/gstable

# 특정 아키텍처로 빌드 (예: ARM64)
go run build/ci.go install -arch arm64 ./cmd/gstable

# 정적 링크 바이너리 생성 (Linux)
go run build/ci.go install -static ./cmd/gstable

# checksums.txt에 명시된 Go 버전을 자동 다운로드하여 빌드
go run build/ci.go install -dlgo ./cmd/gstable

# 모든 실행 파일 빌드
go run build/ci.go install
```

`install` 명령에서 사용할 수 있는 플래그:

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

### 사용 가능한 빌드 타겟

모든 실행 파일은 `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/`            |

## 크로스 컴파일

빌드 시스템은 Go의 내장 크로스 컴파일과 외부 C 툴체인을 사용하여 여러 아키텍처 및 운영 체제에 대한 크로스 컴파일을 지원합니다.

### 지원 플랫폼

CI 시스템은 다음 플랫폼에 대해 빌드합니다:

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

## 빌드 검증

빌드 후 테스트를 실행하여 정상 동작을 확인합니다:

```bash theme={null}
# 빠른 테스트 실행
make test-short

# 전체 테스트 실행
make test

# 린트 검사
make lint
```

`build/ci.go test` 명령은 다음 옵션을 지원합니다:

```bash theme={null}
# 커버리지 보고
go run build/ci.go test -coverage ./...

# 레이스 감지
go run build/ci.go test -race ./...

# 상세 출력
go run build/ci.go test -v ./...
```