From ca5ab4c12765301c1f371622039940cf35a83021 Mon Sep 17 00:00:00 2001 From: sunface Date: Mon, 21 Feb 2022 10:57:12 +0800 Subject: [PATCH] add manifest.md --- contents/SUMMARY.md | 7 +- .../reference/{manifest => }/cargo-target.md | 2 + contents/cargo/reference/manifest.md | 82 +++++++++++++++++++ contents/cargo/reference/manifest/intro.md | 1 - contents/cargo/reference/profiles.md | 1 + .../reference/publishing-on-crates.io.md | 1 + contents/cargo/reference/specify-deps.md | 2 +- contents/cargo/reference/workspaces.md | 1 + 8 files changed, 93 insertions(+), 4 deletions(-) rename contents/cargo/reference/{manifest => }/cargo-target.md (65%) create mode 100644 contents/cargo/reference/manifest.md delete mode 100644 contents/cargo/reference/manifest/intro.md create mode 100644 contents/cargo/reference/profiles.md create mode 100644 contents/cargo/reference/publishing-on-crates.io.md create mode 100644 contents/cargo/reference/workspaces.md diff --git a/contents/SUMMARY.md b/contents/SUMMARY.md index 3c130172..98a0b027 100644 --- a/contents/SUMMARY.md +++ b/contents/SUMMARY.md @@ -138,14 +138,17 @@ - [进阶指南 doing](cargo/reference/intro.md) - [指定依赖项](cargo/reference/specify-deps.md) - [依赖覆盖](cargo/reference/deps-overriding.md) - - [Cargo.toml格式讲解 todo](cargo/reference/manifest/intro.md) - - [Cargo对象(Target) todo](cargo/reference/manifest/cargo-target.md) + - [Cargo.toml清单详解](cargo/reference/manifest.md) + - [Cargo对象(Target) todo](cargo/reference/cargo-target.md) + - [工作空间 todo](cargo/reference/workspaces.md) - [features todo](cargo/reference/features.md) + - [编译器设置和优化 todo](cargo/reference/profiles.md) - [发布配置profile todo](cargo/reference/profile.md) - [配置管理 todo](cargo/reference/configuration.md) - [环境变量 todo](cargo/reference/env.md) - [构建脚本 todo](cargo/reference/build-script/intro.md) - [构建脚本示例 todo](cargo/reference/build-script/examples.md) + - [发布到crates.io todo](cargo/reference/publishing-on-crates.io.md) - [Package ID说明 todo](cargo/reference/package-id.md) - [附录：Git鉴权](cargo/git-auth.md) diff --git a/contents/cargo/reference/manifest/cargo-target.md b/contents/cargo/reference/cargo-target.md similarity index 65% rename from contents/cargo/reference/manifest/cargo-target.md rename to contents/cargo/reference/cargo-target.md index 99f71c63..fefcc069 100644 --- a/contents/cargo/reference/manifest/cargo-target.md +++ b/contents/cargo/reference/cargo-target.md @@ -1 +1,3 @@ # 修改默认的文件目录 + +## Target配置 \ No newline at end of file diff --git a/contents/cargo/reference/manifest.md b/contents/cargo/reference/manifest.md new file mode 100644 index 00000000..44ea7f08 --- /dev/null +++ b/contents/cargo/reference/manifest.md @@ -0,0 +1,82 @@ +# Cargo.toml格式讲解 +`Cargo.toml` 又被称为清单( `manifest` )，文件格式是 `TOML`，每一个清单文件都由以下部分组成： + +* [`cargo-features`](unstable.md) — 只能用于 `nightly`版本的 `feature` +* [`[package]`](#package) — 定义项目( `package` )的元信息 + * [`name`](#name) — 名称 + * [`version`](#the-version-field) — 版本 + * [`authors`](#the-authors-field) — 开发作者 + * [`edition`](#the-edition-field) — Rust edition. + * [`rust-version`](#the-rust-version-field) — 支持的最小化 Rust 版本 + * [`description`](#the-description-field) — 描述 + * [`documentation`](#the-documentation-field) — 文档 URL + * [`readme`](#the-readme-field) — README 文件的路径 + * [`homepage`](#the-homepage-field) - 主页 URL + * [`repository`](#the-repository-field) — 源代码仓库的 URL + * [`license`](#the-license-and-license-file-fields) — 开源协议 License. + * [`license-file`](#the-license-and-license-file-fields) — License 文件的路径. + * [`keywords`](#the-keywords-field) — 项目的关键词 + * [`categories`](#the-categories-field) — 项目分类 + * [`workspace`](#the-workspace-field) — 工作空间 workspace 的路径 + * [`build`](#the-build-field) — 构建脚本的路径 + * [`links`](#the-links-field) — 本地链接库的名称 + * [`exclude`](#the-exclude-and-include-fields) — 发布时排除的文件 + * [`include`](#the-exclude-and-include-fields) — 发布时包含的文件 + * [`publish`](#the-publish-field) — 用于阻止项目的发布 + * [`metadata`](#the-metadata-table) — 额外的信息，用于提供给外部工具 + * [`default-run`](#the-default-run-field) — [`cargo run`] 所使用的默认可执行文件( binary ) + * [`autobins`](cargo-targets.md#target-auto-discovery) — 禁止可执行文件的自动发现 + * [`autoexamples`](cargo-targets.md#target-auto-discovery) — 禁止示例文件的自动发现 + * [`autotests`](cargo-targets.md#target-auto-discovery) — 禁止测试文件的自动发现 + * [`autobenches`](cargo-targets.md#target-auto-discovery) — 禁止 bench 文件的自动发现 + * [`resolver`](resolver.md#resolver-versions) — 设置依赖解析器( dependency resolver) +* Cargo Target 列表: (查看 [Target 配置](cargo-target.md#Target配置) 获取详细设置) + * [`[lib]`](./cargo-target.md#library) — Library target 设置. + * [`[[bin]]`](cargo-target.md#binaries) — Binary target 设置. + * [`[[example]]`](cargo-target.md#examples) — Example target 设置. + * [`[[test]]`](cargo-target.md#tests) — Test target 设置. + * [`[[bench]]`](cargo-target.md#benchmarks) — Benchmark target 设置. +* Dependency tables: + * [`[dependencies]`](specify-deps.md) — 项目依赖包 + * [`[dev-dependencies]`](specify-deps.md#dev-dependencies) — 用于 examples、tests 和 benchmarks 的依赖包 + * [`[build-dependencies]`](specify-deps.md#build-dependencies) — 用于构建脚本的依赖包 + * [`[target]`](specify-deps.md#根据平台引入依赖) — 平台特定的依赖包 +* [`[badges]`](#the-badges-section) — 用于在注册服务(例如 crates.io ) 上显示项目的当前维护状态 +* [`[features]`](features.md) — `features` 可以用于条件编译 +* [`[patch]`](deps-overriding.md) — 推荐使用的依赖覆盖方式 +* [`[replace]`](deps-overriding.md#不推荐的replace) — 不推荐使用的依赖覆盖方式 (deprecated). +* [`[profile]`](profiles.md) — 编译器设置和优化 +* [`[workspace]`](workspaces.md) — 工作空间的定义 + +下面，我们将对其中一些部分进行详细讲解。 + +## [package] +`Cargo.toml` 中第一个部分就是 `package`，用于设置项目的相关信息： +```toml +[package] +name = "hello_world" # the name of the package +version = "0.1.0" # the current version, obeying semver +authors = ["Alice ", "Bob "] +``` + +其中，只有 `name` 和 `version` 字段是**必须填写的**。当发布到注册服务时，可能会有额外的字段要求，具体参见[发布到crates.io](publishing-on-crates.io.md)。 + +#### name +项目名用于引用一个项目( `package` )，它有几个用途： + +- 其它项目引用我们的 `package` 时，会使用该 `name` +- 编译出的可执行文件(bin target)的默认名称 + +`name` 只能使用 [`alphanumeric`](https://doc.rust-lang.org/stable/std/primitive.char.html#method.is_alphanumeric) 字符、 `-` 和 `_`，并且不能为空。 + +事实上，`name` 的限制不止如此，例如: + +- **当使用 `cargo new` 或 `cargo init` 创建时**，`name` 还会被施加额外的限制，例如不能使用Rust 关键字名称作为 `name` +- **如果要发布到 `crates.io` ，那还有更多的限制**: `name` 使用 `ASCII` 码，不能使用已经被使用的名称，例如 `uuid` 已经在 `crates.io` 上被使用，因此我们只能使用类如 `uuid_v1` 的名称，才能将项目发布到 `crates.io` 上 + +#### version +Cargo 使用了[语义化版本控制](https://semver.org)的概念，例如字符串 `"0.1.12"` 是一个 `semver` 格式的版本号，符合 `"x.y.z"` 的形式，其中 `x` 被称为主版本(major), `y` 被称为小版本 `minor` ，而 `z` 被称为 补丁 `patch`，可以看出从左到右，版本的影响范围逐步降低，补丁的更新是无关痛痒的，并不会造成 API 的兼容性被破坏。 + +使用该规则，你还需要遵循一些基本规则: + +- 在版本到达 `1.0.0` 之前，怎么都行，但是如果有破坏性变更( breaking changes )，需要增加 `minor` 版本号。例如，为结构体新增字段或为枚举新增成员就是一种破坏性变更 \ No newline at end of file diff --git a/contents/cargo/reference/manifest/intro.md b/contents/cargo/reference/manifest/intro.md deleted file mode 100644 index e4629663..00000000 --- a/contents/cargo/reference/manifest/intro.md +++ /dev/null @@ -1 +0,0 @@ -# Cargo.toml格式讲解 diff --git a/contents/cargo/reference/profiles.md b/contents/cargo/reference/profiles.md new file mode 100644 index 00000000..0fb3f50f --- /dev/null +++ b/contents/cargo/reference/profiles.md @@ -0,0 +1 @@ +# profiles todo diff --git a/contents/cargo/reference/publishing-on-crates.io.md b/contents/cargo/reference/publishing-on-crates.io.md new file mode 100644 index 00000000..3f6dc5d3 --- /dev/null +++ b/contents/cargo/reference/publishing-on-crates.io.md @@ -0,0 +1 @@ +# 发布到crates.io todo diff --git a/contents/cargo/reference/specify-deps.md b/contents/cargo/reference/specify-deps.md index 58d50927..3ef14cda 100644 --- a/contents/cargo/reference/specify-deps.md +++ b/contents/cargo/reference/specify-deps.md @@ -252,7 +252,7 @@ mio = "0.0.1" > 注意，当发布包到 crates.io 时，`[dev-dependencies]` 中的依赖只有指定了 `version` 的才会被包含在发布包中。况且，再加上测试稳定性的考虑，我们建议为 `[dev-dependencies]` 中的包指定相应的版本号 -## 构建依赖 +## [build-dependencies] 我们还可以指定某些依赖仅用于构建脚本: ```toml [build-dependencies] diff --git a/contents/cargo/reference/workspaces.md b/contents/cargo/reference/workspaces.md new file mode 100644 index 00000000..29df92a3 --- /dev/null +++ b/contents/cargo/reference/workspaces.md @@ -0,0 +1 @@ +# 工作空间 todo