Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

開発者ガイド

How to build, test, lint and run big-code-analysis from a checkout. It is for contributors; the repository-level rules (stability contract, validation gates, review conventions) live in AGENTS.md and CONTRIBUTING.md at the repository root.

You need a current stable Rust toolchain; the minimum supported version is declared in the root Cargo.toml.

リポジトリのクローン

Clone through HTTPS

git clone -j8 https://github.com/dekobon/big-code-analysis.git

または SSH を使う方法

git clone -j8 git@github.com:dekobon/big-code-analysis.git

Make が正式なエントリポイント

The repository ships a Makefile that wraps every common build, test, lint, format, and docs task. Run make help to see the full list of targets. Run make check-tools to list the optional tools and check which are installed.

最もよく使うことになる 2 つの複合ターゲットは次のとおりです。

  • make pre-commit: the recommended local gate before committing. It runs formatting, both clippy configurations, tests, documentation checks, dependency checks, and the lint families. It also runs repository consistency checks, both self-scan tiers, and the Python validation stages, in one parallel pass. The membership comparison (make check-test-lang-gates-compare) requires COMPARE_REF and runs separately in CI. See _pc-all in the Makefile for the complete stage list. The gate ends with a single BCA_GATE: pass or BCA_GATE: fail (…) line; read the verdict from that line and nothing else.
  • make ci: the same checks in the order CI runs them, with no auto-fixing. Use this to reproduce a failing CI run locally.

If GNU Make 4 or any of the optional tools are unavailable, fall back to the raw cargo commands shown below; they are equivalent to the corresponding Make targets.

ビルド

big-code-analysis ライブラリ、CLI、Web サーバーを一括でビルドするには、次を実行します。

make build           # cargo build --workspace --all-targets
make build-release   # cargo build --workspace --release

個別のクレートに対しては、cargo を直接呼び出します。

cargo build                              # library only
cargo build -p big-code-analysis-ast     # parse + classification layer only
cargo build -p big-code-analysis-cli     # CLI only
cargo build -p big-code-analysis-web     # web server only

make check は cargo check --workspace --all-targets を実行し、反復作業中の高速な型チェックを行います。

テスト

すべてのテストが通ることを確認するには、次を実行します。

make test       # cargo nextest run --workspace --all-features
make test-doc   # cargo test --workspace --all-features --doc

make test は cargo-nextest を優先します。CI が実行しているのもこちらです。素の cargo test は各テストバイナリを終えてから次を開始するため、並列性はバイナリ内にしか存在しません。nextest はすべてのバイナリのテストを 1 つのグローバルなプールにスケジュールします。cargo install --locked cargo-nextest でインストールできます。

Without it, make test falls back to cargo test --workspace --all-features --lib --bins --tests, which runs the same set of tests. The two runners are not quite interchangeable, though: nextest runs each test in its own process, so anything sharing state across tests within a binary (a OnceLock cache, an environment variable, the working directory) is isolated under nextest and shared under cargo test. Preferring nextest locally means local runs match CI on that axis.

NEXTEST= を設定すると、何もアンインストールせずにフォールバックを強制できます（make test NEXTEST=）。特定のバイナリを指すこともできます（make test NEXTEST=/path/to/cargo-nextest）。

doctest は nextest が実行できないため、別のターゲットになっています。make pre-commit と make ci はその両方を実行します。

cargo コマンドだけを自分で実行したい場合は、次のとおりです。

cargo test --workspace --all-features --verbose

insta テストの更新

本プロジェクトでは insta を使用しています。スナップショットを管理するには cargo insta をインストールしてください。必要になる 2 つの操作は Makefile がラップしています。

make insta-review   # cargo insta test --review (interactive)
make insta-accept   # cargo insta test --accept (use with care)

make insta-review はテストを実行して新しいスナップショット参照を生成し、各差分をレビューできるようにします。make insta-accept は、差分のパターンが一様であることを確認済みの、メトリクス値のみが変わる一括更新（文法のバージョンアップ、Halstead 演算子の再分類など）に限って使用してください。

コードフォーマット

Format before opening a pull request. The make fmt target runs every formatter in the project (Rust, Markdown, TOML, Bash) in one shot; make fmt-check verifies formatting without modifying files.

make fmt         # cargo fmt + rumdl check --fix + shfmt -w + taplo fmt
make fmt-check   # the equivalent --check variants

Rustfmt

rustfmt formats Rust code to the project style.

インストールするには、次を実行します。

rustup component add rustfmt

コードをフォーマットするには、次を実行します（make fmt が自動的に処理します）。

cargo fmt

Clippy

Clippy catches common mistakes. The warnings it reports must be fixed before making a pull request.

make clippy は、プロジェクトが強制する 2 種類の clippy 実行（デフォルトフィーチャと --all-features）を実行します。make lint はさらに Markdown、シェル、TOML、Makefile のリンターも実行します。

インストールするには、次を実行します。

rustup component add clippy

エラーと警告を検出するには、次を実行します。

make clippy
# or, manually:
cargo clippy --workspace --all-targets -- -D warnings
cargo clippy --workspace --all-targets --all-features -- -D warnings

未使用の依存関係

make udeps runs cargo +nightly udeps --workspace --all-targets to catch dependencies declared in Cargo.toml but never referenced. Requires the nightly toolchain (rustup toolchain install nightly) and cargo-udeps.

コードドキュメント

make doc        # cargo doc --no-deps --workspace --all-features  (warning-tolerant)
make doc-open   # same, then open in a browser
make doc-check  # strict gate: appends -D warnings to RUSTDOCFLAGS, fails on any rustdoc warning

make doc and make doc-open are the interactive viewers: they build whatever they can so you can still inspect rendered output mid-refactor. make doc-check is the strict gate that runs as part of make pre-commit and CI (cargo doc --no-deps --workspace --all-features with RUSTDOCFLAGS extended by -D warnings); it catches broken intra-doc links, links into private items, and other rustdoc regressions.

big-code-analysis が使用する各依存関係のドキュメントもビルドしたい場合は、基になる cargo 呼び出しから --no-deps オプションを削除してください。

本書のビルド

The book you are reading is an mdBook under big-code-analysis-book/:

make book        # mdbook build
make book-serve  # mdbook serve with live reload

コードの実行

Run bca:

cargo run -p big-code-analysis-cli -- [bca-parameters]

List its parameters:

cargo run -p big-code-analysis-cli -- --help

Run bca-web:

cargo run -p big-code-analysis-web -- [bca-web-parameters]

List its parameters:

cargo run -p big-code-analysis-web -- --help

make install、make install-cli、make install-web は、それぞれ対応するバイナリクレートに対して cargo install --path を呼び出します。

実践的なアドバイス

  • Add at least one unit or integration test with every new feature.
  • Document the public API.
  • Do not add dead code.
  • Comment intricate code so others can follow it.
  • Run make pre-commit before pushing; it is the same gate CI runs.