diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 32833d9..20d11f1 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -27,3 +27,4 @@ - [How to Model an RPL Pattern](ch05-01-how-to-model-an-rpl-pattern.md) - [How to Test an RPL Pattern](ch05-02-how-to-test-an-rpl-pattern.md) +- [Pattern Distribution](ch06-00-pattern-distribution.md) diff --git a/src/ch01-00-getting-started-with-rpl.md b/src/ch01-00-getting-started-with-rpl.md index c99195c..bd39cf0 100644 --- a/src/ch01-00-getting-started-with-rpl.md +++ b/src/ch01-00-getting-started-with-rpl.md @@ -11,7 +11,5 @@ - `RPL_PATS=/path/to/RPL/docs/patterns-pest cargo +nightly-2025-02-14 rpl` (using built-in RPL pattern definitions based on inline MIR) - `RUSTFLAGS="-Zinline-mir=false" RPL_PATS=/path/to/RPL/docs/patterns-pest cargo +nightly-2025-02-14 rpl` (using built-in RPL pattern definitions based on MIR) -> We have the following plans for easing the usage of RPL: -> -> - Integration of standard patterns: Provide a set of commonly used patterns as part of RPL’s standard library. -> - Configuration-based pattern management: Introduce a `rpl.toml` configuration file to manage RPL patterns in a structured and centralized manner. \ No newline at end of file +RPL also supports configuration-based pattern management and Cargo-distributed pattern sets. +See [Pattern Distribution](ch06-00-pattern-distribution.md) for design details and usage. diff --git a/src/ch06-00-pattern-distribution.md b/src/ch06-00-pattern-distribution.md new file mode 100644 index 0000000..c906745 --- /dev/null +++ b/src/ch06-00-pattern-distribution.md @@ -0,0 +1,107 @@ +# Pattern Distribution + +RPL patterns can be distributed and consumed through Cargo’s existing infrastructure. +This keeps pattern sharing lightweight: patterns live in ordinary crates, are discovered through `cargo metadata`, +and can be composed locally with project-specific patterns. + +This chapter covers the design intent, the on-disk configuration format, and the CLI workflow. + +## Design Overview + +RPL resolves pattern paths from two sources: + +- Local groups declared in `rpl.toml`, with paths relative to the file’s directory. +- Remote groups published by a crate via `package.metadata.rpl` in its `Cargo.toml`. + +Remote groups are referenced with the `crate::group` syntax. +When a remote group is selected, RPL runs `cargo metadata` for the current workspace, +locates the named crate, and resolves the group entries relative to the crate root. +No additional registry or RPL-specific package index is required. +Consumers can freely compose imported groups with local groups and with other remote groups +by selecting multiple groups in the desired order. + +## Publishing Patterns in a Crate + +To publish patterns, add metadata to the pattern crate’s `Cargo.toml`: + +```toml +[package] +name = "rpl-patterns" +version = "0.1.0" + +[package.metadata.rpl] +path = ["patterns"] + +[package.metadata.rpl.groups] +all = ["."] +``` + +The fields mean: + +- `path`: optional list containing exactly one base directory, relative to the crate root. If omitted, `"."` is used. +- `groups`: map from group name to a list of pattern paths, each relative to every base directory in `path`. + +In this example, `rpl-patterns::all` expands to `patterns/.` inside the crate. + +## Consuming Patterns with `rpl.toml` + +Place a `rpl.toml` file next to your project’s `Cargo.toml`: + +```toml +[patterns] + +[[patterns.local]] +name = "project" +path = ["rpl/patterns", "rpl/extra"] + +[[patterns.remote]] +name = "security" +groups = ["rpl-patterns::all"] +``` + +Local groups are lists of paths relative to the directory that contains `rpl.toml`. +Remote groups are lists of `crate::group` references from published crates. + +If you run `cargo rpl` with no `--patterns`, RPL will select `project` and then `security` +in that order and set `RPL_PATS` accordingly. + +## Selecting Groups at Runtime + +You can override the default selection with `--patterns`: + +```bash +cargo rpl --patterns project +cargo rpl --patterns security +cargo rpl --patterns rpl-patterns::all +cargo rpl --patterns project --patterns rpl-patterns::all +``` + +Notes: + +- `--patterns` accepts a group name defined in `rpl.toml`, or a remote spec like `crate::group`. +- Remote specs can be used even if `rpl.toml` is missing, as long as the crate is in the Cargo metadata graph. +- If a selected group is unknown (and not a remote spec), RPL reports an error. + +## Cargo Integration Requirements + +Remote groups are resolved through `cargo metadata`, so the crate must be visible to Cargo. +In practice, add the pattern crate as a dependency (often `dev-dependency`) of the workspace: + +```toml +[dev-dependencies] +rpl-patterns = "0.1" +``` + +If multiple crates share the same name in the metadata graph, RPL will refuse to guess. +Keep the dependency graph unambiguous for pattern crates. + +## Environment Variable Interactions + +`RPL_PATS` is still supported and may be set manually: + +```bash +RPL_PATS=path/to/patterns cargo rpl +``` + +If `RPL_PATS` is already set and you do not pass `--patterns`, RPL will not override it. +Passing `--patterns` always recomputes and replaces the pattern list.