diff --git a/README.md b/README.md index c3733dab2a..aeded442b6 100644 --- a/README.md +++ b/README.md @@ -81,9 +81,9 @@ Generation or repair completing does not mean every candidate passes. Inspect bo | --- | --- | | [brinfo](brinfo/README.md) | Extract function condition chains from HIR and MIR. | | [focxt](focxt/README.md) | Construct code context for each focal function. | -| `focxt/call_chain/` | Extract calls and type dependencies through `cargo call-chain`. | +| [focxt/call_chain](focxt/call_chain/README.md) | Extract calls and type dependencies through `cargo call-chain`. | | [utgen](utgen/README.md) | Generate tests, check compilation, repair tests, and collect coverage. | -| `build-utils/` | Configure the compiler library search path during builds. | +| [build-utils](build-utils/README.md) | Configure the compiler library search path during builds. | | [examples](examples/README.md) | The minimal fixture, bundled bytes target, and usage instructions. | | `docker/` | Container build and run scripts. | | [docs](docs/README.md) | Technical guide, validation guides, and ASE 2025 materials. | diff --git a/brinfo/README.md b/brinfo/README.md index 8c3f24b6a9..02c7a75b7f 100644 --- a/brinfo/README.md +++ b/brinfo/README.md @@ -1,19 +1,41 @@ # brinfo -This tool is used to extract the condition chains of functions or methods in a specified project. +brinfo extracts condition chains for Rust functions and methods using the compiler's HIR and MIR. In [PALM](../README.md), these chains supply path constraints for test generation. -## Build +## Build and install -To build brinfo, run `cargo build` in the `brinfo` directory. +Follow the [project prerequisites](../README.md#prerequisites), including the pinned `nightly-2025-03-19` toolchain. From the PALM repository root: + +```sh +cargo build -p brinfo --locked +cargo install --path brinfo --locked +``` + +Installation places `cargo-brinfo` and its companion compiler driver `brinfo` in Cargo's binary directory. Ensure that directory is in `PATH`; invoke analysis through `cargo brinfo`. No model configuration is needed. ## Usage -Navigate to the directory of the project or subproject you want to analyze. In the root directory of the project being analyzed, you need to add a file named `rust-toolchain.toml` : +Use a working copy of a standalone crate with the same pinned toolchain. For the test-generation workflow, [preprocess and analyze with utgen](../utgen/README.md#analysis): it runs brinfo and focxt and checks that their outputs agree. -```toml -[toolchain] -channel = "nightly-2025-03-19" -components = ["rust-src", "rustc-dev", "llvm-tools-preview"] +To run only condition-chain extraction, enter the prepared target crate: + +```sh +cd /absolute/path/to/target-crate +cargo clean +cargo brinfo ``` -You can start by running `cargo clean` to clear the existing build cache, and then run `cargo brinfo` in that directory to start the analysis. +The wrapper analyzes the crate's `lib` and `bin` targets through `cargo check`. Clearing the build cache ensures the compiler analysis runs even if the crate was previously checked. Use a fresh working copy without previous analysis output when repeating an experiment; `cargo clean` does not remove PALM's output files. + +## Output + +Paths are relative to the target crate: + +| Path | Contents | +| --- | --- | +| `brinfo/name_map.json` | Full function names mapped to encoded artifact identifiers. | +| `brinfo/brdata/.json` | Function source and location, condition chains, and representative-chain selection. | + +Use the index to locate artifacts. Pass its full function names to `utgen gen --functions-file` or `utgen fix --functions-file` to select functions. Generation also needs [focxt](../focxt/README.md) output from the same prepared source. + +For an offline check on the bundled fixture, see [minimal pipeline validation](../docs/minimal-pipeline.md). The [technical guide](../docs/palm-rust-unit-test-generation.md) explains condition-chain extraction in more detail. diff --git a/build-utils/README.md b/build-utils/README.md new file mode 100644 index 0000000000..98d6dce5b7 --- /dev/null +++ b/build-utils/README.md @@ -0,0 +1,15 @@ +# build-utils + +build-utils is an internal build dependency of [PALM](../README.md). The tool crates call `build_utils::setup_build()` from their `build.rs` scripts to configure the runtime search path for Rust compiler libraries. + +`setup_build()` reads `rustc --print sysroot` and emits a linker rpath pointing to that toolchain's `lib` directory. Use the [pinned toolchain and components](../README.md#prerequisites) when building PALM. + +## Build + +From the PALM repository root: + +```sh +cargo build -p build-utils --locked +``` + +This crate is built automatically with the tools. It has no CLI or separate installation step. To check its effect on the tool binaries, build the workspace with `cargo build --workspace --locked` and run the [development checks](../README.md#development-checks). diff --git a/focxt/README.md b/focxt/README.md index 17e9030c54..4e1bf1eeeb 100644 --- a/focxt/README.md +++ b/focxt/README.md @@ -1,26 +1,46 @@ # focxt -This tool is capable of analyzing the context for a specified Rust crate. +focxt constructs the source context for each focal function in [PALM](../README.md). It combines compiler-derived calls and types with source-level modules, declarations, and implementations to produce context for test-generation prompts. -## Build +## Build and install + +Follow the [project prerequisites](../README.md#prerequisites), including the pinned `nightly-2025-03-19` toolchain. From the PALM repository root: ```sh -cargo build +cargo build -p call_chain -p focxt --locked +cargo install --path focxt/call_chain --locked +cargo install --path focxt --locked ``` +focxt invokes `cargo call-chain` at runtime, so install [call_chain](call_chain/README.md) as well as focxt and keep Cargo's binary directory in `PATH`. Rebuild and install both together after changes to their shared analysis data. No model configuration is needed. + ## Usage -```bash -A rust program to get focal context for a crate. +Use a working copy of a standalone crate with the same pinned toolchain. For the test-generation workflow, [preprocess and analyze with utgen](../utgen/README.md#analysis): it runs both brinfo and focxt and validates their outputs. -Usage: focxt --crate +To construct context directly from prepared source: -Options: - -c, --crate Sets crate path - -h, --help Print help - -V, --version Print version +```sh +focxt --crate /absolute/path/to/target-crate ``` -`focxt -c crate_path` or `focxt --crate crate_path` +`-c` is the short form of `--crate`. focxt runs `cargo clean` and `cargo call-chain` inside the target before building context; running call-chain separately is unnecessary for this command. Start with a fresh working copy when repeating analysis, since build-cache cleanup does not remove previous context artifacts. + +## Output + +Paths are relative to the target crate: + +| Path | Contents | +| --- | --- | +| `focxt/impl_informations.json` | Function identities, source locations, and encoded artifact identifiers from call-chain. | +| `focxt/.rs` | Per-function context used by utgen. | +| `focxt/callsandtypes/.json` | Direct calls and type dependencies from call-chain. | +| `focxt/new_callsandtypes/.json` | Calls and types expanded during context construction. | + +Additional text files under `focxt/` describe parsed declarations and module trees for debugging. Generation also requires [brinfo](../brinfo/README.md) output from the same prepared source. + +## Scope and checks + +Function contexts use call-chain's compiler identities and source positions, including distinct generic trait impls and reference receivers. Recoverable macro-generated method bodies are associated with their enclosing source impl; this is not general macro expansion. -Function contexts use call-chain's compiler identities and source positions, including distinct generic trait impls and reference receivers. Recoverable macro-generated method bodies are associated with their enclosing source impl; this is not general macro expansion. Rebuild focxt and call-chain together. See the [bytes analysis validation](../docs/bytes-analysis.md) for release builds, reproducible checks, and current limits. +See [minimal pipeline validation](../docs/minimal-pipeline.md) for an offline fixture check and [bytes analysis validation](../docs/bytes-analysis.md) for release builds, reproducible checks, and current limits. The [technical guide](../docs/palm-rust-unit-test-generation.md) explains context selection in more detail. diff --git a/focxt/call_chain/README.md b/focxt/call_chain/README.md new file mode 100644 index 0000000000..dacc87979d --- /dev/null +++ b/focxt/call_chain/README.md @@ -0,0 +1,40 @@ +# call_chain + +call_chain extracts function identities, direct calls, and type dependencies for [focxt](../README.md). It is a compiler-analysis component of [PALM](../../README.md), with the Cargo command `cargo call-chain` and a library shared with focxt. + +## Build and install + +Follow the [project prerequisites](../../README.md#prerequisites), including the pinned `nightly-2025-03-19` toolchain. From the PALM repository root: + +```sh +cargo build -p call_chain --locked +cargo install --path focxt/call_chain --locked +``` + +Installation provides `cargo-call-chain` and its companion compiler driver `call-chain`. Keep Cargo's binary directory in `PATH` and invoke the tool through `cargo call-chain`. No model configuration is needed. + +## Usage + +focxt runs call-chain automatically. Use [utgen analysis](../../utgen/README.md#analysis) for the complete analysis stage, or [focxt](../README.md#usage) to construct context directly. + +To inspect only compiler-derived calls and types, enter a fresh working copy of a prepared standalone crate using the same pinned toolchain: + +```sh +cd /absolute/path/to/target-crate +cargo clean +cargo call-chain +``` + +The wrapper analyzes `lib` and `bin` targets through `cargo check`. Clearing the build cache ensures analysis executes after an earlier check; it does not remove previous `focxt/` output. + +## Output + +Paths are relative to the target crate: + +| Path | Contents | +| --- | --- | +| `focxt/impl_informations.json` | Function and impl identities, source locations, and encoded artifact identifiers. | +| `focxt/callsandtypes/.json` | Direct calls and type dependencies for each function. | +| `focxt/basic_blocks/.txt` | MIR basic blocks and locals for debugging. | + +call-chain supplies compiler data; focxt produces the per-function `.rs` context files used by generation. Changes to shared data should be checked with both tools. See [minimal pipeline validation](../../docs/minimal-pipeline.md) and [bytes analysis validation](../../docs/bytes-analysis.md). diff --git a/utgen/README.md b/utgen/README.md index 7783ded216..6322390659 100644 --- a/utgen/README.md +++ b/utgen/README.md @@ -2,6 +2,8 @@ utgen generates Rust tests from condition chains and focal context, checks compilation, repairs compilation errors, and collects coverage and execution statistics. +For a first run, start with [PALM's offline quick start](../README.md#quick-start), then follow the [two-function model trial](../examples/README.md#prepare-a-small-model-trial). This page is the detailed command reference. + ## Prerequisites Model configuration is loaded at runtime, once per `gen` or `fix` command. Building, installing, running help, `pre-process`, `analyze`, and `coverage` do not require it. @@ -60,6 +62,8 @@ cargo build -p utgen --locked cargo install --path utgen --locked ``` +The `analyze` command also requires [brinfo](../brinfo/README.md), [focxt](../focxt/README.md), and [call_chain](../focxt/call_chain/README.md) on `PATH`. Use the [root installer](../README.md#installation) to install all tools. Installing utgen alone does not install these companion executables. + ## Testing ```sh