---
url: https://nsh.dev/ja/docs/layerfs
description: "Native Shell のチェックアウトにある Linux 版 LayerFS トライアルを使用して、Cargo のビルド出力をキャプチャし、ワークスペースをフォークして、スナップショットの再利用を検証します。"
---

# LayerFS を使ったローカル開発

Native Shell のリポジトリには、再利用可能なビルドワークスペースをテストするためのローカル LayerFS ワークフローが含まれています。このワークフローは、コミット済みのソースツリーをインポートし、Linux Sandbox 内で Cargo を実行し、生成されたファイルを保存し、その保存状態から作成したフォークでテストを再度実行します。ソースの編集と Git コミットは、既存の NSH チェックアウトで行います。

> [!IMPORTANT]
> このワークフローには Docker Engine と Linux FUSE が必要です。Docker は制御プロセスと Sandbox を実行し、FUSE は Sandbox 内にワークスペースをマウントします。macOS では、開発用コマンドが OrbStack などのローカル Docker エンジンを通じて、この Linux デプロイメントを準備します。

<a id="what-the-snapshot-saves"></a>

## スナップショットが保存するもの

LayerFS はファイルシステムツリーを保存します。対象は、ソースファイル、Git メタデータ、無視されたファイル、そしてワークスペース内で生成されたビルド成果物です。フォークは保存されたツリーから開始され、独自の変更を記録します。これにより、複数のタスクが同じビルド済みの状態から開始しつつ、それぞれの変更を分離しておけます。

NSH のローカルトライアルでは、最初のブランチが `nsh-package` のテストを実行し、`target/` と無視されるプローブファイルを保存します。2 番目のブランチはそのコミットから開始し、それらのファイルを確認して、オフラインでテストを繰り返します。3 番目のブランチは元のソース状態から開始し、分離が保たれていることを検証します。

| フェーズ | 内容 |
| --- | --- |
| Init | チェックアウトの `HEAD` コミットのエクスポートと、新しい `.git` ディレクトリをインポートします |
| Build | ワークスペースをフォークし、`cargo +1.98.1 test --locked -p nsh-package` を実行します |
| Commit | 生成された `target/` とプローブファイルを LayerFS の履歴に保存します |
| Reuse | 保存されたブランチをフォークしてマウントし、`--offline` でテストを繰り返します |
| Verify | コミット履歴を読み取り、元のソースブランチがクリーンなままであることを確認します |

呼び出しのたびに新しい Store が作成され、この一連のシーケンスがすべて実行されます。スナップショットの再利用は、その呼び出し内のブランチ間で行われます。このトライアルで測定すべき効果は、マウント、コミット、アンマウントの時間を含め、テスト済みで利用可能な別のワークスペースに到達するまでのコストです。

<a id="prepare-the-development-environment"></a>

## 開発環境を準備する

次の条件を満たす [NSH リポジトリ](https://github.com/longbridge/nsh)のチェックアウトを使用します。

- Store ボリュームに ext4、XFS、Btrfs のいずれかを使用する、ローカルの Linux Docker エンジン。Linux 上、または OrbStack などの macOS 環境経由で実行します。
- API 1.54 以降を提供する Docker Engine。検証済みのローカル環境では Engine 29.7.2 を使用しています。
- `/dev/fuse`。Docker がそのデバイスと `CAP_SYS_ADMIN` を Sandbox に公開できるようにしておく必要があります。
- Git と Python 3.12 以降。Linux では、rustup と C/C++ コンパイラも必要です。
- 固定された LayerFS ソース、Cargo の依存関係、ランタイムイメージを取得するためのネットワークアクセス。

このトライアルは、ソースコミット `2aaf2552ce21154928b9f9c83582e41a637f5910` に固定された LayerFS **1.0.0** をビルドします。ランタイムイメージは、Linux プロセス用に Rust 1.98.1、Node、clang を提供します。[アップストリームの SDK ガイド](https://github.com/Ephemeral-AI-Lab/layerfs/blob/v1.0.0/sdk/js/README.md)では、Store と Sandbox のライフサイクルを説明しています。

NSH チェックアウトのルートで次のコマンドを実行します。

```sh
./scripts/layerfs prepare
./scripts/layerfs smoke
./scripts/layerfs status
```

この実行ファイルは、macOS 上の Homebrew のインストールを含め、Python 3.12 以降を選択し、アクティブな Docker コンテキストからソケットを検出します。ローカルソケットを明示的に選択するには `--docker-socket PATH` を使用します。

`prepare` は Docker API を確認し、Rust 1.85.1 をインストールして、固定されたデーモン、Node アドオン、ランタイムイメージをビルドします。macOS では、これらを一時的な Linux ビルドコンテナ内で準備します。通常の Cargo レジストリと `target/` を再利用し、既存の `CARGO_TARGET_DIR` 設定も引き継ぎます。正確なランタイムイメージ ID とデーモンのパスは `.nsh/layerfs/deployment.json` に記録されます。`status` は、保存されたビルド成果物とイメージを確認し、最新の検証結果を表示します。

`smoke` は、チェックアウトの**コミット済みの `HEAD`** から `.nsh/layerfs/nsh-<id>/input` を作成し、その入力を新しい Store にインポートします。ソースの編集内容を含めるには、実行前にトピックブランチへコミットしてください。生成される入力は新しい Git リポジトリから始まり、ビルド成果物は Sandbox 内で取得されます。

制御プロセスは、名前付きのローカル Docker ボリューム内で Store を開きます。Sandbox デーモンは同じ Store を開き、ブランチのファイルシステムビューをマウントします。Cargo はそのマウントされたワークスペース内で実行されます。通常のチェックアウトは、引き続きソースの変更を編集してコミットする場所です。

<a id="read-the-result"></a>

## 結果を読み取る

コマンドは、レシートディレクトリと Store ボリューム名を出力します。生成された `result.json` を開いて、`"ok": true` と各フェーズの経過時間を確認してください。同じディレクトリには、ソースコミットとイメージを識別する `settings.json` と、SDK 呼び出しを記録する `trace.jsonl` があります。

ローカル検証では、ビルドフェーズと再利用フェーズのそれぞれで 22 件のパッケージテストを実行しました。最初のビルドとテストのフェーズには依存関係のダウンロードが含まれていました。オフラインフェーズでは、保存された `target/` と同じ Sandbox の Cargo レジストリを使用しました。その価値を評価する際は、ご自身のワークロードで、サイクル全体を通常の Cargo ビルドと比較してください。

ビルド済みの状態を再利用する場合は、オペレーティングシステム、アーキテクチャ、ツールチェーン、依存関係を一致させてください。このガイドのワークロードは Linux の `nsh-package` テストスイートです。プラットフォーム UI のチェックには、それぞれのプラットフォーム環境を使用します([Testing](https://nsh.dev/translations/ja/docs/testing-and-trace.md))。

<a id="keep-useful-work-and-manage-the-store"></a>

## 有用な成果を残し、Store を管理する

ソースの変更は Git で管理し、プルリクエストで提出してください。このトライアルでは、再構築可能なワークスペース履歴のために、LayerFS の **Disposable** Store プロファイルを使用します。測定結果を記録する場合は、有用なレシートを別途保管してください。

生成される入力では、LayerFS がインポートする間オブジェクトデータベースを安定させるため、最初のコミット時に Git の自動メンテナンスを無効にしています。トライアル内の Git ステータスチェックでは `--no-optional-locks` を使用し、ステータスの読み取りで元のインデックスが保持されるようにしています。カスタムスクリプトでは、ツリーをインポートまたはコミットする前に、バックグラウンドの書き込み処理を完了させてください。

アンマウントに成功した Sandbox は、LayerFS のアイドルタイムアウト後に停止します。各トライアルは Store ボリュームを保持します。そのボリュームとコンテナは、レシートにある識別子を使って個別に管理してください。失敗した操作は、診断のために記録された状態を保持します。スクリプト、レシート、リソースのクリーンアップについては、[メンテナ向けリファレンス](https://nsh.dev/translations/docs/dev/layerfs.md)を参照してください。