diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_zh_CN/pages/advanced/1-completion.md | 19 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/other/features.md | 64 | ||||
| -rw-r--r-- | docs/dev/pages/abouts/code-verify-system.md | 7 | ||||
| -rw-r--r-- | docs/example-pages/examples.json | 11 | ||||
| -rw-r--r-- | docs/pages/advanced/1-completion.md | 19 | ||||
| -rw-r--r-- | docs/pages/other/features.md | 64 |
6 files changed, 33 insertions, 151 deletions
diff --git a/docs/_zh_CN/pages/advanced/1-completion.md b/docs/_zh_CN/pages/advanced/1-completion.md index d70786e..290fab0 100644 --- a/docs/_zh_CN/pages/advanced/1-completion.md +++ b/docs/_zh_CN/pages/advanced/1-completion.md @@ -11,13 +11,6 @@ Mingling 的补全是**完全动态**的——没有静态的补全文件,而 # Cargo.toml [dependencies.mingling] features = ["comp"] - -[build-dependencies.mingling] -features = [ - "comp", - # 启用 `build` 特性以提供构建期支持 - "build" -] ``` ## 工作原理 @@ -72,8 +65,18 @@ suggest! { ## 生成补全脚本 -在 `build.rs` 中调用 `build_comp_scripts` 生成补全脚本(需要 `builds` + `comp` 特性)。 +开启 `comp` 特性后,`gen_program!()` 会在编译期自动调用 `build_comp!()`,生成以 `CARGO_PKG_NAME` 命名的补全脚本到 `target/mingling/`。 + +如果你的二进制名与 crate 名不同,可以手动调用 `build_comp!()` 并指定二进制名: +```rust +// Features: ["comp"] +@@@use mingling::macros::build_comp; +@@@fn example() { +build_comp!("mybin"); +@@@} +``` + 详见 [example-completion](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion)。 <p align="center" style="font-size: 0.85em; color: gray;"> diff --git a/docs/_zh_CN/pages/other/features.md b/docs/_zh_CN/pages/other/features.md index 5fa7c86..f8753e5 100644 --- a/docs/_zh_CN/pages/other/features.md +++ b/docs/_zh_CN/pages/other/features.md @@ -25,42 +25,6 @@ Mingling 提供了一系列**预设特性组**,方便用户按需组合启用 **定位:** 完整模式,启用 Mingling 的全部核心功能。在 `advanced` 的基础上额外包含 clap 集成、完整的结构化渲染器(含所有序列化格式)以及实验性的路径分析器,适合大型、功能全面的命令行应用。 -## `build_advanced` - -**启用特性:** `build`、`comp` - -**定位:** 构建期增强配置,用于在项目构建时生成补全脚本等构建辅助材料(`comp` 特性提供补全脚本生成能力)。 - -> [!NOTE] -> -> 此特性组为**构建依赖**专用,需配合 `advanced` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用: - -```toml -[dependencies.mingling] -features = ["advanced"] - -[build-dependencies.mingling] -features = ["build_advanced"] -``` - -## `build_full` - -**启用特性:** `build`、`comp`、`pathf`、`dispatch_tree` - -**定位:** 完整的构建期配置,在 `build_advanced` 的基础上额外包含路径分析器(`pathf`)以自动解析类型模块路径,适合结构复杂、需要自动化构建期分析的项目。 - -> [!NOTE] -> -> 此特性组为**构建依赖**专用,需配合 `full` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用: - -```toml -[dependencies.mingling] -features = ["full"] - -[build-dependencies.mingling] -features = ["build_full"] -``` - # 特性详解 ## 特性 `all_serde_fmt` @@ -91,23 +55,6 @@ async fn handle_state_foo(foo: StateFoo) -> Next { 详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-async-support) -## 特性 `builds` - -**介绍:** - -启用部分需要在 `build.rs` 使用的脚本,目前包含: - -1. `comp` 特性下的补全脚本生成: - -```rust -// BUILD TIME -// Features: ["builds", "comp"] -use mingling::build::build_comp_scripts; - -// 为 `myprogram` 生成补全脚本 -build_comp_scripts("myprogram").unwrap(); -``` - ## 特性 `clap` **介绍:** @@ -318,17 +265,10 @@ pub struct ErrorNotDir(PathBuf); # Cargo.toml [dependencies.mingling] features = ["pathf"] - -[build-dependencies.mingling] -features = ["builds", "pathf"] -``` - -```rust -// BUILD TIME -// Features: ["pathf"] -analyze_and_build_type_mapping().unwrap(); ``` +开启 `pathf` 特性后,`gen_program!()` 会在编译期自动调用 `build_pathf!()` 执行类型映射分析。 + 详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-pathfinder) ## 特性 `picker` diff --git a/docs/dev/pages/abouts/code-verify-system.md b/docs/dev/pages/abouts/code-verify-system.md index 929b337..20da045 100644 --- a/docs/dev/pages/abouts/code-verify-system.md +++ b/docs/dev/pages/abouts/code-verify-system.md @@ -125,8 +125,11 @@ Marks the block as a `build.rs` script instead of `src/main.rs`. The block code ```rust // BUILD TIME -// Features: ["builds", "pathf"] -analyze_and_build_type_mapping().unwrap(); +// Dependencies: +// serde = "1" +fn main() { + // build-time work, e.g. writing generated sources into OUT_DIR +} ``` ### `// Features: [...]` diff --git a/docs/example-pages/examples.json b/docs/example-pages/examples.json index 38f73cd..dd5b65b 100644 --- a/docs/example-pages/examples.json +++ b/docs/example-pages/examples.json @@ -69,13 +69,11 @@ "tags": [ "pathf", "dispatch_tree", - "extras", - "build.rs" + "extras" ], "files": [ "src/main.rs", "src/sub/mod.rs", - "build.rs", "Cargo.toml" ] }, @@ -87,13 +85,11 @@ "desc": "Combines the `pathf` feature with entry metadata. The metadata `DataType` and the entry `BindType` are defined inside a submodule, and `pathf` resolves them for `gen_program!()` at build time.\n", "tags": [ "pathf", - "metadata", - "build.rs" + "metadata" ], "files": [ "src/main.rs", "src/sub/mod.rs", - "build.rs", "Cargo.toml" ] }, @@ -124,7 +120,6 @@ ], "files": [ "src/main.rs", - "build.rs", "Cargo.toml" ] }, @@ -294,12 +289,10 @@ "desc": "Demonstrates the `pathf` feature, which automatically resolves type module paths at build time. Types can be defined in submodules without explicit `use` in the main module.\n", "tags": [ "pathf", - "build.rs", "architecture" ], "files": [ "Cargo.toml", - "build.rs", "src/main.rs", "src/sub/mod.rs" ] diff --git a/docs/pages/advanced/1-completion.md b/docs/pages/advanced/1-completion.md index 20bd59e..ca1f621 100644 --- a/docs/pages/advanced/1-completion.md +++ b/docs/pages/advanced/1-completion.md @@ -11,13 +11,6 @@ Mingling's completion is **fully dynamic** — no static completion files, sugge # Cargo.toml [dependencies.mingling] features = ["comp"] - -[build-dependencies.mingling] -features = [ - "comp", - # Enable `build` for build-time support - "build" -] ``` ## How it works @@ -72,8 +65,18 @@ suggest! { ## Generate completion scripts -Call `build_comp_scripts` in `build.rs` to generate completion scripts (requires `builds` + `comp` features). +When the `comp` feature is enabled, `gen_program!()` automatically invokes `build_comp!()` at compile time, which generates the completion scripts (named after `CARGO_PKG_NAME`) into `target/mingling/`. + +If your binary name differs from the crate name, call `build_comp!()` manually with the binary name: +```rust +// Features: ["comp"] +@@@use mingling::macros::build_comp; +@@@fn example() { +build_comp!("mybin"); +@@@} +``` + See [example-completion](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-completion). <p align="center" style="font-size: 0.85em; color: gray;"> diff --git a/docs/pages/other/features.md b/docs/pages/other/features.md index b2c0ea5..858e556 100644 --- a/docs/pages/other/features.md +++ b/docs/pages/other/features.md @@ -25,42 +25,6 @@ Mingling provides a set of **preset feature groups** that make it easy to enable **Positioning:** Full mode, enables all of Mingling's core functionality. In addition to `advanced`, it includes clap integration, the full structural renderer (with all serialization formats), and the experimental path analyzer. Suitable for large, feature-complete command-line applications. -## `build_advanced` - -**Enables features:** `build`, `comp` - -**Positioning:** Build-time enhanced configuration, used to generate build helpers such as completion scripts at build time (the `comp` feature provides completion script generation). - -> [!NOTE] -> -> This feature group is intended for **build dependencies** only and must be used alongside the `advanced` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: - -```toml -[dependencies.mingling] -features = ["advanced"] - -[build-dependencies.mingling] -features = ["build_advanced"] -``` - -## `build_full` - -**Enables features:** `build`, `comp`, `pathf`, `dispatch_tree` - -**Positioning:** Full build-time configuration, extends `build_advanced` with the path analyzer (`pathf`) to automatically resolve type module paths, suitable for projects with complex structures that require automated build-time analysis. - -> [!NOTE] -> -> This feature group is intended for **build dependencies** only and must be used alongside the `full` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: - -```toml -[dependencies.mingling] -features = ["full"] - -[build-dependencies.mingling] -features = ["build_full"] -``` - # Feature Details ## Feature `all_serde_fmt` @@ -91,23 +55,6 @@ async fn handle_state_foo(foo: StateFoo) -> Next { See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-async-support) -## Feature `builds` - -**Description:** - -Enables scripts needed for use in `build.rs`, currently including: - -1. Completion script generation under the `comp` feature: - -```rust -// BUILD TIME -// Features: ["builds", "comp"] -use mingling::build::build_comp_scripts; - -// Generate completion scripts for `myprogram` -build_comp_scripts("myprogram").unwrap(); -``` - ## Feature `clap` **Description:** @@ -318,17 +265,10 @@ When enabled, types can be defined in any submodule, and `gen_program!()` can au # Cargo.toml [dependencies.mingling] features = ["pathf"] - -[build-dependencies.mingling] -features = ["builds", "pathf"] -``` - -```rust -// BUILD TIME -// Features: ["pathf"] -analyze_and_build_type_mapping().unwrap(); ``` +With the `pathf` feature enabled, `gen_program!()` automatically invokes `build_pathf!()` at compile time to run the type mapping analysis. + See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-pathfinder) ## Feature `picker` |
