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

# 개발 도구

## 목적 및 범위

이 문서는 go-stablenet 코드베이스에서 사용 가능한 **개발 도구 전반에 대한 개요**를 제공합니다.\
여기서 다루는 도구들은 StableNet 노드 및 네트워크를 **빌드, 테스트, 디버깅, 운영·유지보수**하는 전 과정을 지원합니다.

개발 도구는 네 가지 주요 카테고리로 구성되며, 각 항목은 하위 문서에서 상세히 설명됩니다.

* **Building and CI/CD**\
  빌드 시스템, 크로스 컴파일, CI/CD 파이프라인에 대한 내용
* **devp2p CLI Tools**\
  DNS 기반 발견(discovery), P2P 네트워크 진단 및 테스트 도구
* **Data Import and Export Utilities**\
  블록체인 데이터(체인, 히스토리, 스냅샷) 관리 도구
* **Testing and Debugging**\
  테스트 프레임워크, 프로토콜 검증, 정적 분석 도구

이 문서는 개별 도구의 사용법보다는 **도구 생태계의 전체 구조와 상호 관계를 이해하기 위한 상위 가이드** 역할을 합니다.

## 도구 카테고리

개발 도구는 코드베이스 전반에 분산되어 있으며, 주요 진입점은 다음과 같습니다.

| Category         | Entry Point                                         | Primary Use Cases               |
| ---------------- | --------------------------------------------------- | ------------------------------- |
| Build Automation | `build/ci.go`, `Makefile`                           | Executable 빌드, 크로스 컴파일, 릴리스 패키징 |
| CI/CD Pipelines  | `.travis.yml`, `appveyor.yml`                       | 자동 테스트, 빌드, 배포                  |
| Network Tools    | `cmd/devp2p/`                                       | P2P 네트워크 진단, DNS 발견 관리          |
| Chain Management | `cmd/utils/cmd.go`                                  | 체인 Import/Export, Era1, 스냅샷 관리  |
| Code Quality     | `.golangci.yml`, `build/ci.go`                      | 정적 분석, 린팅                       |
| Testing          | `internal/utesting/`, `cmd/devp2p/internal/v4test/` | 유닛 테스트, P2P 프로토콜 테스트            |

## 빌드 시스템 아키텍처

빌드 시스템의 중심은 `build/ci.go`이며, 이는 **모든 빌드·테스트·릴리스 작업의 단일 제어 지점** 역할을 합니다.

### 주요 컴포넌트

* `build/ci.go`\
  빌드·테스트·아카이브·업로드를 담당하는 메인 오케스트레이터
* `build.GoToolchain`\
  크로스 컴파일을 포함한 Go 컴파일러 설정 관리
* `build.Environment`\
  CI 또는 로컬 Git 환경에서 커밋, 날짜, 브랜치, 태그 메타데이터 수집
* `build.ChecksumDB`\
  `build/checksums.txt`를 기반으로 외부 종속성 무결성 검증

이 빌드 시스템은 `-arch`, `-cc` 플래그를 통해 다음을 지원합니다.

* 아키텍처: `amd64`, `386`, `arm`, `arm64`
* 플랫폼: `linux`, `darwin`, `windows`, `freebsd`

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

지속적 통합(CI)은 **플랫폼별 특성에 따라 분리**되어 운영됩니다.

* **Travis CI**: Linux / macOS
* **AppVeyor**: Windows

이를 통해 동일한 코드베이스에 대해 멀티 플랫폼 릴리스 품질을 보장합니다.

### 파이프라인 단계

1. **코드 푸시 트리거**\
   master 브랜치 또는 버전 태그 푸시 시 실행
2. **병렬 빌드**\
   플랫폼 및 아키텍처별 병렬 작업 수행
3. **테스트 실행**\
   모든 빌드에서 기본 테스트 실행, cron 작업에서 레이스 디텍션 수행
4. **아티팩트 생성**\
   zip / tar.gz 형식의 서명된 바이너리 아카이브 생성

## 개발 도구 호출 흐름

다음은 일반적인 개발자가 로컬 및 CI 환경에서 도구를 사용하는 흐름입니다.

| Command                  | Purpose     | Implementation                                       |
| ------------------------ | ----------- | ---------------------------------------------------- |
| `make gstable`           | 메인 노드 빌드    | `go run build/ci.go install ./cmd/gstable`           |
| `make genesis_generator` | 제네시스 생성기 빌드 | `go run build/ci.go install ./cmd/genesis_generator` |
| `make all`               | 전체 실행 파일 빌드 | `go run build/ci.go install`                         |
| `make test`              | 테스트 실행      | `go run build/ci.go test`                            |
| `make lint`              | 정적 분석       | `golangci-lint` 실행                                   |
| `make devtools`          | 개발 도구 설치    | stringer, gencodec, abigen 등                         |

## 빠른 참조: 사용 가능한 도구

### 빌드 및 릴리스 도구

| Tool              | Location      | Command                    | Description |
| ----------------- | ------------- | -------------------------- | ----------- |
| Main build script | `build/ci.go` | `go run build/ci.go <cmd>` | 빌드 오케스트레이션  |
| Makefile          | `Makefile`    | `make <target>`            | 개발자 편의 래퍼   |

### 네트워크 및 발견 도구

| Tool            | Location                                  | Description        |
| --------------- | ----------------------------------------- | ------------------ |
| devp2p          | `cmd/devp2p/`                             | P2P 네트워크 진단        |
| DNS discovery   | `cmd/devp2p/dnscmd.go`                    | DNS 기반 노드 발견 관리    |
| Discovery v4/v5 | `cmd/devp2p/discv4cmd.go`, `discv5cmd.go` | DHT 기반 발견 프로토콜 테스트 |
| Node crawler    | `cmd/devp2p/crawl.go`                     | 네트워크 토폴로지 수집       |

### 체인 관리 도구

| Tool                | Location           | Description  |
| ------------------- | ------------------ | ------------ |
| Chain import/export | `cmd/utils/cmd.go` | 체인 데이터 이동    |
| Era1 archive        | `cmd/utils/cmd.go` | 히스토리 블록 관리   |
| Preimage tools      | `cmd/utils/cmd.go` | 해시 프리이미지 관리  |
| Snapshot export     | `cmd/utils/cmd.go` | 상태 스냅샷 프리이미지 |

### 테스트 및 검증 도구

| Tool               | Location                      | Description            |
| ------------------ | ----------------------------- | ---------------------- |
| Unit tests         | 전체 코드베이스                      | Go 표준 테스트              |
| P2P protocol tests | `cmd/devp2p/internal/v4test/` | Discovery v4 규격 검증     |
| Test utilities     | `internal/utesting/`          | TAP 호환 테스트 러너          |
| Linter             | `.golangci.yml`               | golangci-lint 기반 정적 분석 |

## 빌드 플래그 및 구성

### 크로스 컴파일 플래그

| Flag      | Description   |
| --------- | ------------- |
| `-arch`   | 대상 아키텍처 지정    |
| `-cc`     | cgo용 C 컴파일러   |
| `-static` | 정적 링크 바이너리    |
| `-dlgo`   | 지정 Go 버전 다운로드 |

### CI 환경 변수

CI 환경에서는 커밋 정보, 서명 키, 업로드 토큰 등이 환경 변수로 주입됩니다.

* `TRAVIS_COMMIT`, `APPVEYOR_REPO_COMMIT`
* `AZURE_BLOBSTORE_TOKEN`
* `LINUX_SIGNING_KEY`, `OSX_SIGNING_KEY`
* `AWS_ACCESS_KEY_ID` (DNS 관리용)

## 도구 종속성 및 버전

모든 외부 도구 종속성은 `build/checksums.txt`에 **버전과 SHA256 체크섬이 고정**되어 있습니다.

| Tool                 | Version | Purpose   |
| -------------------- | ------- | --------- |
| Go compiler          | 1.21.6  | 빌드 도구체인   |
| golangci-lint        | 1.55.2  | 린팅        |
| execution-spec-tests | 2.1.0   | 실행 스펙 테스트 |

필요 시 `build.ChecksumDB`를 통해 자동 다운로드 및 검증이 수행됩니다.

***

개별 도구의 실제 사용법과 예제는 다음 하위 문서를 참고하세요.

* Building and CI/CD
* devp2p CLI Tools
* Data Import and Export Utilities
* Testing and Debugging