hikari ビルド (`hikari build`) 仕様

本書は hikari build の仕様を定める。起動ディスパッチ全体と終了コードの共通表は hikari-command.md、静的検査は static-analysis.md、third-party パッケージは packages.md を参照。

エントリ .hikari とその import 依存を go:embed で同梱した単体 Go バイナリを生成する。生成バイナリはホストに hikari 処理系をインストールしなくても動く。

構文

hikari build [-o <output>] [--target <os>/<arch>]... [--strict] <entry.hikari>

引数の並びは フラグ → エントリ の順。Go の flag パッケージの規約に従い、positional 引数 (エントリ) より後ろのフラグは解釈されない。

オプション

フラグ	既定値	意味
`-o <output>`	エントリの basename から `.hikari` を除いたもの	出力ファイル名のベース
`--target <os>/<arch>`	ホストの `GOOS`/`GOARCH`	ビルドターゲット。複数指定可
`--strict`	off	ビルド前に strict 型検査 (後述「strict 型検査」) を適用する

出力名

ターゲットが 1 個: <output> をそのまま使う。
ターゲットが複数: <output>-<os>-<arch> の形に展開。
ターゲット OS が windows の場合は .exe を付与。

対応ターゲット

go build がサポートする任意の GOOS/GOARCH ペア。検証済みの組合せ:

darwin/arm64
darwin/amd64
linux/amd64
linux/arm64
windows/amd64

import の静的解決

ビルドはまず entry を起点に 静的検査 (static-analysis.md §1) を行う。構文エラー (動的 import を含む) や import 先不在があればビルドを中止し exit code 1。検査を通過した場合のみ、import <対象> := "<path>" のリテラルパスを再帰収集して embed する。embed ルート (相対 slash パスの 0 点) は、プロジェクトに package.hikari (packages.md) があれば その manifest dir、無ければ エントリの所属ディレクトリ。

構文エラー / import 先不在 → 静的エラーで停止 (ファイル実行 (hikari-command.md §5)・hikari check (check.md) と同一規則)。
embed ルートより外 (../...) に出る相対 import は エラー で停止する (embed FS の制約)。
pkg: 依存 (third-party、packages.md) は lockfile で解決したグラフを別名前空間 pkg/<source>@<version>/... に embed する。path dep は embed ルート相対の元位置に embed し、embed ルート外 (../...) を指す path dep は embed 不可として エラー で停止する (git dep 化を案内)。path dep は commit 固定が無いため embed 時に再現性警告を stderr に出す。std: モジュールは従来どおり host コンパイル同梱 (embed FS とは独立)。

ホスト要件

ホストに go ツールチェーン (Go 1.26+) が必要。exec.LookPath("go") で確認し、無ければ「go toolchain not found in PATH」を stderr に出して exit code 2。
内部で go mod tidy および go build -ldflags="-s -w" を実行する。
生成バイナリ自体の実行には Go ツールチェーンは不要。

hikari リポジトリの位置解決

生成プロジェクトは replace github.com/bluegreenhq/hikari => <path> で本体ソースを参照する。<path> は次の順で決定する:

環境変数 HIKARI_REPO の値 (絶対化)
os.Executable() の親から最大 6 階層上向きに go.mod を含むディレクトリを探索
os.Getwd() から最大 6 階層上向きに go.mod を含むディレクトリを探索

いずれも見つからなければエラーで exit code 2。

進捗出力

go mod tidy / go build の stdout/stderr はそのまま stderr に流す。

strict 型検査 (`--strict`)

hikari build --strict は、「import の静的解決」の構文層静的検査 (static-analysis.md §1) の通過後・go build の起動前に、entry を起点とした strict 型検査 (static-analysis.md §3) を走らせる。型エラーが 1 件でもあれば診断を stderr に出してビルドを中止し exit code 1 で停止する (バイナリは生成しない)。検査がクリーンなときのみ通常どおりビルドを続行する。

strict 規則はファイル実行 hikari <path> --strict (hikari-command.md §5.5) と同じ (static-analysis.md §3 の 6 規則)。
実効 strict はファイル単位。entry ファイルが header #{hikari strict} / #[hikari strict] (language-spec.md §13.1) を宣言していれば --strict 無しでもその entry は strict として検査される。実効 strict = 「CLI --strict」OR「entry header の strict 属性」。
フラグ無し・header に strict 無しの hikari build は従来どおり構文層検査のみで、型検査は行わない (通常モードの hikari <path> と揃う。実行時照合が backstop、check.md「検査内容」)。

hikari ビルド (hikari build) 仕様

構文