第4章 開発環境の構築#
本章では、Solana プログラム開発の環境を、クリーンなマシンから再現可能な形で構築します。第6章以降で扱うリファレンス実装を、読者自身の手元でビルド・テストできる状態にすることが目標です。
環境構築は、手順書の中でも最も「手元では動くのに読者の環境では動かない」が起きやすい箇所です。そこで本章は、次の方針で執筆しています。
- 全コマンドと出力例を、クリーンな Linux コンテナで実際に実行して確認した。 掲載する出力は、その実行結果からの転記です。
- バージョンは第1章のバージョン表と一致させ、固定する。 本文中で「最新版」を入れる指示はしません。
- 実際に遭遇した詰まりを、トラブルシューティング(4.9)に記録した。 想像上のエラーではなく、再現作業中に本当に発生した事象を扱います。
4.1 前提と検証環境#
4.1.1 対象OS#
本章の手順は Linux または macOS を対象とします。Windows の場合は WSL2(Windows Subsystem for Linux 2)経由で Linux 環境を用意してください。以降は WSL2 上の Linux として実施します。
4.1.2 本章の検証方法(クリーン環境からの再現)#
「クリーンなマシンからの再現」を保証するため、本章は既存の開発機ではなく、まっさらな Linux コンテナの中で全手順を実行して検証しました。使用したのは Docker です。
検証環境は次のとおりです。
| 項目 | 値 |
|---|---|
| ベースイメージ | Debian 13 (trixie) slim |
| アーキテクチャ | x86_64(linux/amd64) |
| GLIBC | 2.41 |
| 検証所要時間 | 約7分28秒(後述のアーキテクチャ注記あり) |
アーキテクチャに関する注記(重要): 本章の検証は、Apple Silicon(arm64)のマシン上で linux/amd64 をエミュレーション実行して行いました。読者の多数派である x86_64 環境に合わせるためです。したがって、掲載する所要時間はエミュレーション込みの目安であり、ネイティブ環境ではより短くなります。なお、x86_64 でのビルド・全テスト成功は CI(GitHub Actions、第9章9.7)でも確認済みです。arm64 ネイティブでの動作確認は本書のスコープ外とします。
4.1.3 目標とするバージョン#
本章で導入するツールのバージョンは、第1章のバージョン表(および docs/versions.md)と一致させます。
| ツール | 固定バージョン |
|---|---|
| Rust(rustc / cargo) | 1.89.0 |
| Agave CLI(Solana) | 3.1.13 |
| Anchor CLI | 1.1.2 |
| Node.js | 24.15.0 |
補足: 本章の検証コンテナでは、Node.js は NodeSource の
setup_24.xにより 24.18.0 が入りました。バージョン表の固定値は 24.15.0 です。Node のマイナー差はビルド結果に影響しませんが、厳密に固定したい場合は.nvmrc等で 24.15.0 を指定してください。
4.2 クリーンな Linux 環境を用意する#
再現性の土台として、まずクリーンな Linux 環境を用意します。本章では Docker コンテナを使いますが、読者が新規の Linux マシンや WSL2 を使う場合は、この節を読み飛ばして 4.3 から始めても構いません。
Docker が利用できる環境で、次のコマンドでクリーンな Debian を起動します。
起動後、環境が想定どおりかを確認します。GLIBC のバージョンは、後述するバイナリ配布物の動作可否に関わるため、ここで見ておきます。
検証環境での実際の出力は次のとおりです。
続いて、以降の手順で必要になる基本パッケージを導入します。
apt-get update
apt-get install -y curl ca-certificates build-essential pkg-config libssl-dev git bzip2
GLIBC についての先出し注意: この後 4.5 で導入する Anchor CLI のビルド済みバイナリは、GLIBC 2.39 以上を要求します。Debian 12 (bookworm) の GLIBC は 2.36 のため、bookworm では Anchor バイナリが動きません(4.9 の TS-4 で詳述)。本章が Debian 13 (trixie、GLIBC 2.41)を使うのはこのためです。古いディストロを使う場合は、先に GLIBC のバージョンを確認してください。
4.3 Rust ツールチェーン#
Rust は rustup で導入します。バージョンは 1.89.0 に固定します(Anchor 1.1.2 の MSRV に一致)。
導入後、現在のシェルに PATH を反映してバージョンを確認します。
実際の出力は次のとおりです。
なお、本リファレンス実装のリポジトリには rust-toolchain.toml(channel = "1.89.0")が含まれており、リポジトリ内での作業時はシステムの Rust より優先して 1.89.0 が使われます。手元のシステム Rust が新しくても、リポジトリのビルドは 1.89.0 に固定されます。
4.4 Agave CLI(Solana)#
Solana のコマンドラインツールは、現在 Agave(クライアント実装名)として anza-xyz org から配布されています。公式インストーラでバージョンを固定して導入します。
sh -c "$(curl -sSfL https://release.anza.xyz/v3.1.13/install)"
export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"
solana --version
実際の出力は次のとおりです。
4.4.1 devnet への切り替えと鍵の生成#
開発中は devnet(開発用ネットワーク)を使います。接続先を devnet に切り替え、テスト用のキーペアを生成します。
solana config set --url devnet
solana-keygen new --no-bip39-passphrase -o "$HOME/.config/solana/id.json"
solana config get
solana config get の実際の出力は次のとおりです。
Config File: /root/.config/solana/cli/config.yml
RPC URL: https://api.devnet.solana.com
WebSocket URL: wss://api.devnet.solana.com/ (computed)
Keypair Path: /root/.config/solana/id.json
Commitment: confirmed
ネットワークの取り違えに注意:
--urlに指定する値は、devnet/mainnet-beta/localhost/testnetを切り替えます。devnet と mainnet を取り違えると、意図しないネットワークに接続します。作業前に必ずsolana config getで RPC URL を確認してください。鍵の扱い: ここで生成するのはローカルのテスト用キーペアです。本番の秘密鍵・シードフレーズは扱いません(第5章の統制)。devnet の残高が必要な場合は
solana airdropを使いますが、devnet の faucet はレート制限があります(第9章9.6で詳述)。
4.5 Anchor(AVM 経由)#
Anchor は AVM(Anchor Version Manager)で導入し、バージョンを 1.1.2 に固定します。
4.5.1 配布元について#
Anchor 公式のインストール手順が示す AVM 導入コマンドは、次の URL を使います。
ここで solana-foundation/anchor は現在 otter-sec/anchor へ 301 リダイレクトします(確認日: 2026-07-24)。Anchor 本体の正リポジトリが otter-sec org へ移管されたためです(経緯は設計書 v1.2「Anchor リポジトリ移管の確認記録」)。git はリダイレクトに透過的に追従するため、公式コマンドのままで移管後のリポジトリから取得されます。両 URL とも同一コミットに解決されることは git ls-remote で確認済みです。
4.5.2 バージョンを固定した導入#
クリーン環境で 1.1.2 を固定して導入する手順は次のとおりです。バージョンを固定するため、--tag v1.1.2 を明示します。
# --- 省略 ---(下記の TS-2 の回避を適用したうえで avm をインストールする)
avm --version
avm install 1.1.2
avm use 1.1.2
anchor --version
重要(クリーン環境で実際に詰まった箇所): 上記をそのまま実行すると、本書の固定バージョン(Rust 1.89.0)では AVM のソースビルドが失敗します。これは AVM の間接依存が新しい Rust を要求するためで、回避策があります。手順の詳細は 4.9 の TS-2 を参照してください。回避策を適用した後は、次の出力が得られます。
回避策を適用したうえでの実際の出力は次のとおりです。
avm useの挙動:avm use 1.1.2は、Anchor 1.1.2 が推奨する Solana バージョン(3.1.10)をagave-installで用意しようとします。本書の固定運用(Agave 3.1.13)とは別に 3.1.10 も取得される点、およびネットワークの一時失敗で止まることがある点に注意してください(4.9 の TS-3)。
4.6 Node.js と TypeScript クライアント#
TypeScript クライアント(第6章のミント作成スクリプト等)のために Node.js を導入します。本書では 24 系を使います。
curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/nodesource_setup.sh
bash /tmp/nodesource_setup.sh
apt-get install -y nodejs
node --version
npm --version
実際の出力は次のとおりです(検証コンテナでは NodeSource の setup_24.x により 24.18.0 が入りました)。
リポジトリの TypeScript 依存は、package-lock.json のとおりに厳密インストールします。これによりバージョンが固定されます。
npm run typecheck(tsc --noEmit)が型エラーなしで完了すれば、TypeScript 環境は正常です。
本書の TypeScript クライアントの構成: 本書のクライアントは
@solana/kitを直接利用し、プログラム連携には生成した IDL 型を用います。Anchor の TypeScript クライアントパッケージ(Anchor v1 の@anchor-lang/core、および旧 0.3x 系の@coral-xyz/anchor)は使用しません。 したがって、これらの Anchor TS パッケージの導入は本書の対象外です。使用する npm パッケージ(@solana/kitほか)とバージョンは第1章のバージョン表を正とします(詳細は第6章 6.3.1)。
4.7 プロジェクトの雛形と構造#
新規にワークスペースを作る場合は anchor init を使います。
本リファレンス実装は、anchor init(Anchor 1.1.2 の v1 テンプレート)で生成したワークスペースを基に構築されています。主要な構成は次のとおりです。
.
├── Anchor.toml # Anchor のワークスペース設定(プログラムID・クラスタ等)
├── Cargo.toml # Rust ワークスペース(members = ["programs/*"])
├── rust-toolchain.toml # Rust を 1.89.0 に固定
├── package.json # TypeScript クライアントの依存
├── programs/
│ ├── registry/ # レジストリ(投資家許可リスト)プログラム
│ └── transfer_hook/ # Transfer Hook プログラム
├── scripts/ # TypeScript スクリプト(ミント作成等)
└── docs/ # 手順書原稿・バージョン表・セッションログ
AI 開発環境の導入(第5章へ誘導):
anchor initには、公式 Agent Skills を同時に導入する--install-agent-skillsオプションがあります。AI コーディングエージェントを使う場合の導入と統制は、第5章で扱います。
v1 テンプレートは、旧 0.3x 系と構成が異なります(テスト基盤の既定が LiteSVM/Surfpool、TS パッケージの移行など)。旧バージョンの手順を流用しないよう注意してください。
4.8 動作確認#
環境が正しく整ったかを、リファレンス実装のビルドと全テストの実行で確認します。
transfer_hook はネイティブ実装で IDL を持たないため、ビルドは --no-idl を付けます(理由は第7章7.1)。
クリーン環境での anchor build --no-idl は、依存のコンパイルを含めて完了します(検証環境では約52秒)。続く cargo test の実際の出力(抜粋)は次のとおりです。
running 3 tests
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.84s
running 6 tests
test result: ok. 6 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 1.82s
running 15 tests
test result: ok. 15 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 3.57s
レジストリ単体(3件)+ lib unit(各1件)+ Hook 統合(15件)+ 攻撃系(6件)の合計26件が全て成功すれば、環境構築は完了です(各テストの内容は第9章)。
4.8.1 所要時間の目安#
クリーン環境からここまでの全工程(ツール導入からテスト完了まで)の所要時間は、検証環境で約7分28秒でした。これは arm64 マシン上で linux/amd64 をエミュレーション実行した値です。ネイティブの x86_64 環境ではより短くなります。内訳の目安は、ツール群の導入が約3分、AVM のソースビルドが約1分、anchor build が約1分、テストが約1分です。
4.9 トラブルシューティング#
本節の事例は、本章の検証(クリーン環境からの再現)で実際に遭遇したものです。想定ではなく、再現作業中に発生した実際のエラーを扱います。
TS-1: Docker のイメージ取得が認証ヘルパ不在で失敗する(macOS ホスト)#
症状: docker run 実行時に次のエラーで停止する。
error getting credentials - err: exec: "docker-credential-desktop":
executable file not found in $PATH
原因: ~/.docker/config.json の "credsStore": "desktop" が指す認証ヘルパが PATH 上に見つからない。
対処: 公開イメージの取得だけなら認証は不要です。恒久的には Docker Desktop の PATH 設定を修正します。一時的には、credsStore を含まない設定を用意し、DOCKER_CONFIG 環境変数でそれを指定して回避できます。
TS-2: AVM のソースビルドが Rust 1.89 で失敗する#
症状: AVM をソースからインストールしようとすると、次のエラーで失敗する。
原因: AVM の間接依存 cargo_metadata が引き込む cargo-platform 0.3.3 が rustc 1.91 を要求します。本書は Rust を 1.89.0 に固定しているため、crates.io の最新解決では非互換になります。
対処: ソースを取得し、問題の依存を 1.89 互換のバージョン(cargo-platform 0.3.2、rustc 1.88 要求)へ明示的に降格してからインストールします。
git clone --depth 1 --branch v1.1.2 https://github.com/solana-foundation/anchor /tmp/anchor
cd /tmp/anchor/avm
cargo generate-lockfile
cargo update -p cargo-platform@0.3.3 --precise 0.3.2
cargo install --path . --locked --force
この手順により、検証環境では AVM 1.1.2 が正常にビルド・インストールされました。
TS-3: avm use が推奨 Solana のダウンロードで止まる#
症状: avm use 1.1.2 が次のエラーで止まることがある。
原因: AVM は Anchor のバージョンごとに「推奨 Solana」を持ち、use の際に agave-install でそれを取得します。ネットワークの一時的な失敗で止まることがあり、また本書の固定運用(3.1.13)とは別に 3.1.10 を取得しようとします。
対処: 再実行(リトライ)で解消することが多いです。固定運用の Agave は 4.4 で 3.1.13 を導入済みのため、PATH 上はそちらが優先されます。
TS-4: Anchor バイナリが GLIBC 不足で動かない(GLIBC 問題)#
症状: anchor build 実行時に次のエラーで失敗する。
/root/.avm/bin/anchor-1.1.2: /lib/x86_64-linux-gnu/libc.so.6:
version `GLIBC_2.39' not found (required by /root/.avm/bin/anchor-1.1.2)
原因: AVM が取得する Anchor 1.1.2 のビルド済みバイナリは GLIBC 2.39 以上を前提にビルドされています。Debian 12 (bookworm) の GLIBC は 2.36 のため、必要なバージョンが不足します。
対処: GLIBC 2.39 以上のベース環境を使います。Debian 13 (trixie) は GLIBC 2.41、Ubuntu 24.04 も 2.39 以上です。本章が trixie を採用したのはこの理由です。
一般化: 新しめのバイナリ配布物は、古いディストリビューションで GLIBC 不足になりがちです。macOS は GLIBC 非依存のため手元では顕在化せず、Linux の CI・本番環境で初めて出ることがあります。ベース環境の GLIBC バージョンを先に確認する習慣が有効です。
TS-5: anchor build(無印)が IDL 生成で失敗する#
症状: anchor build(オプションなし)が末尾で Error: IDL doesn't exist になる。
原因: transfer_hook はネイティブ実装で IDL を持たないため、ビルド末尾の IDL 生成が失敗します(両プログラムの .so 自体は生成済み)。
対処: anchor build --no-idl を使うか、IDL が必要なプログラムのみ anchor build -p registry を使います。
4.10 本章の自己チェック表#
| 観点 | 結果 |
|---|---|
| スタイル規則違反 | なし(です・ます調、一文概ね80字以内、コードブロックに言語指定を付与、省略は // --- 省略 --- で明示、相互参照は番号、価格・投資リターン・マーケティング語彙・法的判断示唆なし) |
[要検証] の残数 |
0件(全コマンド・出力例をクリーン Debian trixie コンテナで実行し、その実出力を転記。未実行の手順は掲載していない) |
| バージョン表との不一致 | なし(Rust 1.89.0 / Agave 3.1.13 / Anchor 1.1.2 は第1章バージョン表・docs/versions.md と一致。バージョン指定に「latest」「最新版」を使っていない(ツールは全て具体的な固定バージョンを明示)。Node は検証コンテナで 24.18.0 が入った旨と固定値 24.15.0 の差を4.1.3・4.6で明示) |
| コマンド・出力例の出所 | すべてクリーン環境(Debian 13 trixie、linux/amd64)での実行結果からの転記。再現ログはセッションログ 2026-07-24 セッション2-D |
| 配布元確認 | Anchor CLI(otter-sec/anchor。旧URLは301リダイレクト)/ Agave(anza-xyz)を確認(確認日 2026-07-24)。移管の詳細は設計書 v1.2 |
| クリーン再現 | 実演済み。ツール導入 → ビルド → 全26テスト成功までを1つのクリーンコンテナで通し、所要 約7分28秒(amd64 エミュレーション)。x86_64 は CI でも確認済み |