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

# 빌드 및 CI/CD

## 목적 및 범위

이 문서는 go-stablenet의 빌드 시스템과 CI/CD 파이프라인 전반을 설명합니다.\
로컬 환경에서의 바이너리 빌드 방법, CI/CD 파이프라인 구조, 릴리스 아티팩트 생성 과정을 다루며, **패키지 배포는 사전 빌드 바이너리를 중심**으로 설명합니다.

사전 빌드된 바이너리 설치 또는 실행 중인 노드 구성에 대한 내용은 [설치 및 빌드](/ko/getting-started/2.1-installation-and-building) 및 [노드 구성](/ko/getting-started/2.2-node-configuration)을 참고하세요.

## 빌드 시스템 아키텍처

go-stablenet 프로젝트는 **이중 레이어 빌드 시스템**을 사용합니다.

1. **Makefile**\
   개발자가 로컬에서 빠르게 바이너리를 빌드하거나 테스트를 수행하기 위한 인터페이스입니다.
2. **build/ci.go**\
   CI/CD 환경, 크로스 컴파일, 릴리스 아카이브 생성을 담당하는 통합 빌드 도구입니다.

Makefile은 내부적으로 `build/ci.go`를 호출하며, CI 환경과 로컬 빌드 결과가 최대한 동일하도록 설계되어 있습니다.

### 빌드 시스템 구성 요소

* `Makefile`: 개발자용 진입점
* `build/ci.go`: CI/CD 및 릴리스 자동화 핵심 로직
* `build/bin/`: 로컬 빌드 산출물 디렉터리
* `internal/build/`: 체크섬, 다운로드, 검증 로직
* `params/version.go`: 버전 정보 정의

## 버전 관리

버전 정보는 `params/version.go`에서 중앙 관리되며, 빌드 시 모든 바이너리에 포함됩니다.

### 버전 구조

| Component  | Source                | Example    |
| ---------- | --------------------- | ---------- |
| Major      | `params.VersionMajor` | `0`        |
| Minor      | `params.VersionMinor` | `1`        |
| Patch      | `params.VersionPatch` | `0`        |
| Meta       | `params.VersionMeta`  | `stable`   |
| Git Commit | 빌드 시 주입               | `a1b2c3d4` |
| Git Date   | 커밋 기준 생성              | `20240115` |

### 버전 문자열 형식

* **Version**: `0.1.0`
* **VersionWithMeta**: `0.1.0-stable`
* **ArchiveVersion**: `0.1.0-a1b2c3d4`
* **VersionWithCommit**: `0.1.0-stable-a1b2c3d4-20240115`

버전 정보는 컴파일 시 링커 플래그로 주입됩니다.

```text theme={null}
-X github.com/ethereum/go-ethereum/internal/version.gitCommit=<commit>
-X github.com/ethereum/go-ethereum/internal/version.gitDate=<date>
```

## 로컬 빌드

### Makefile 기반 빌드

Makefile은 가장 일반적인 빌드 작업을 단순화합니다.

| Target             | Command                  | Output     |
| ------------------ | ------------------------ | ---------- |
| gstable            | `make gstable`           | 메인 노드 바이너리 |
| genesis\_generator | `make genesis_generator` | 제네시스 생성 도구 |
| all                | `make all`               | 전체 실행 파일   |
| test               | `make test`              | 테스트 실행     |
| lint               | `make lint`              | 린트 실행      |
| clean              | `make clean`             | 빌드 산출물 정리  |

모든 결과물은 `build/bin/` 디렉터리에 생성됩니다.

### build/ci.go 기반 빌드

`build/ci.go`는 CI 환경과 동일한 빌드 조건을 로컬에서 재현하기 위한 도구입니다.

주요 역할:

* 크로스 컴파일
* 릴리스 아카이브 생성
* 체크섬 검증
* CI 전용 빌드 플래그 적용

## 크로스 컴파일

빌드 시스템은 다음 아키텍처를 지원합니다.

* `amd64`
* `386`
* `arm` (GOARM v5/v6/v7)
* `arm64`

### ARM64 예제

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

### ARM v7 예제

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

## CI/CD 파이프라인 아키텍처

go-stablenet은 **멀티 플랫폼 CI 환경**을 사용합니다.

### CI 플랫폼 매트릭스

| Platform  | OS      | Architectures          | Purpose    |
| --------- | ------- | ---------------------- | ---------- |
| Travis CI | Linux   | amd64, arm64, 386, arm | 메인 빌드, 테스트 |
| Travis CI | macOS   | amd64, arm64           | macOS 바이너리 |
| AppVeyor  | Windows | amd64, 386             | Windows 빌드 |

### Travis CI

* 트리거: master 브랜치, 태그, PR
* 멀티 Go 버전 테스트
* Docker 이미지 빌드
* 릴리스 아카이브 생성

### AppVeyor

* Windows 빌드 전용
* ZIP 아카이브 생성
* 서명된 바이너리 산출

## 릴리스 아티팩트

### 아카이브 생성

릴리스 아카이브에는 실행 파일과 라이선스가 포함됩니다.

| Archive | Platform      |
| ------- | ------------- |
| tar.gz  | Linux / macOS |
| zip     | Windows       |

파일명 형식:\
`gstable-{platform}-{arch}-{version}.{ext}`

### 서명 및 업로드

* 선택적 PGP 또는 Signify 서명
* Azure Blob Storage 업로드
* master 또는 태그 빌드에서만 수행

## CI 테스트 및 린팅

### 테스트

CI 테스트는 다음 조건으로 실행됩니다.

* 타임아웃: 20분
* 병렬성 제한(`-p 1`)
* 통합 테스트 태그 활성화
* 선택적 레이스 감지

### 린팅

`golangci-lint`를 사용하며, 주요 활성 린터는 다음과 같습니다.

* goimports
* govet
* staticcheck
* ineffassign
* misspell
* unused
* whitespace

## 종속성 관리

모든 외부 종속성은 `build/checksums.txt`로 관리됩니다.

* 다운로드 전 SHA256 검증
* 재현 가능한 빌드 보장
* CI 및 로컬 빌드 동일 동작

## 빌드 플래그 및 링커 설정

### 빌드 태그

| Tag                   | Purpose        |
| --------------------- | -------------- |
| urfave\_cli\_no\_docs | CLI 문서 생성 비활성화 |
| ckzg                  | KZG 암호화 활성화    |
| integrationtests      | 통합 테스트         |
| netgo                 | 순수 Go 네트워크     |
| osusergo              | 순수 Go 사용자 조회   |

### 링커 플래그

```text theme={null}
-ldflags "-X ...gitCommit -X ...gitDate -s -trimpath"
```

## 요약

go-stablenet 빌드 및 CI/CD 시스템의 핵심 특징은 다음과 같습니다.

1. Makefile + build/ci.go 이중 레이어 구조
2. 멀티 플랫폼 CI
3. 크로스 컴파일 지원
4. 재현 가능한 릴리스 아티팩트
5. 체크섬 기반 종속성 검증
6. 모든 바이너리에 버전 메타데이터 포함

이 구조를 통해 StableNet은 일관되고 예측 가능한 빌드 및 배포 환경을 제공합니다.