From e8b6d97124de39e4f2b73399495389d5c05a99c7 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Mon, 14 Oct 2024 07:25:36 -0700 Subject: [PATCH 1/4] docs: More information on what is and isn't included by cargo package --- src/doc/man/cargo-package.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/doc/man/cargo-package.md b/src/doc/man/cargo-package.md index 3d2fd1fbb6d..d076b741188 100644 --- a/src/doc/man/cargo-package.md +++ b/src/doc/man/cargo-package.md @@ -32,6 +32,16 @@ stored in the `target/package` directory. This performs the following steps: - A `.cargo_vcs_info.json` file is included that contains information about the current VCS checkout hash if available, as well as a flag if the worktree is dirty. + - Symlinks are flattened to their target files. + - Subdirectories containing `Cargo.toml` are excluded, as they are assumed + to be separate packages. + - A `target` directory in the root of the package is excluded. + - Files and directories matching the `[include]` and `[exclude]` fields in + the manifest are included or excluded. Include patterns can override the + following rules. + - Files that are ignored by VCS are excluded. + - Unix hidden files and directories (starting with `.`) are excluded. + 3. Extract the `.crate` file and build it to verify it can build. - This will rebuild your package from scratch to ensure that it can be built from a pristine state. The `--no-verify` flag can be used to skip From d07bd5bfddb69f9e70ef84a9f12151196f061050 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Mon, 14 Oct 2024 08:02:03 -0700 Subject: [PATCH 2/4] chore: cargo build-man --- src/doc/man/generated_txt/cargo-package.txt | 18 ++++++++++++++ src/doc/src/commands/cargo-package.md | 10 ++++++++ src/etc/man/cargo-package.1 | 27 +++++++++++++++++++++ 3 files changed, 55 insertions(+) diff --git a/src/doc/man/generated_txt/cargo-package.txt b/src/doc/man/generated_txt/cargo-package.txt index f25e55b52bb..fac84660fb1 100644 --- a/src/doc/man/generated_txt/cargo-package.txt +++ b/src/doc/man/generated_txt/cargo-package.txt @@ -14,11 +14,13 @@ DESCRIPTION following steps: 1. Load and check the current workspace, performing some basic checks. + o Path dependencies are not allowed unless they have a version key. Cargo will ignore the path key for dependencies in published packages. dev-dependencies do not have this restriction. 2. Create the compressed .crate file. + o The original Cargo.toml file is rewritten and normalized. o [patch], [replace], and [workspace] sections are removed from the @@ -32,7 +34,23 @@ DESCRIPTION about the current VCS checkout hash if available, as well as a flag if the worktree is dirty. + o Symlinks are flattened to their target files. + + o Subdirectories containing Cargo.toml are excluded, as they are + assumed to be separate packages. + + o A target directory in the root of the package is excluded. + + o Files and directories matching the [include] and [exclude] fields + in the manifest are included or excluded. Include patterns can + override the following rules. + + o Files that are ignored by VCS are excluded. + + o Unix hidden files and directories (starting with .) are excluded. + 3. Extract the .crate file and build it to verify it can build. + o This will rebuild your package from scratch to ensure that it can be built from a pristine state. The --no-verify flag can be used to skip this step. diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md index 38fc7f80b4e..5b02574f9e7 100644 --- a/src/doc/src/commands/cargo-package.md +++ b/src/doc/src/commands/cargo-package.md @@ -27,6 +27,16 @@ stored in the `target/package` directory. This performs the following steps: - A `.cargo_vcs_info.json` file is included that contains information about the current VCS checkout hash if available, as well as a flag if the worktree is dirty. + - Symlinks are flattened to their target files. + - Subdirectories containing `Cargo.toml` are excluded, as they are assumed + to be separate packages. + - A `target` directory in the root of the package is excluded. + - Files and directories matching the `[include]` and `[exclude]` fields in + the manifest are included or excluded. Include patterns can override the + following rules. + - Files that are ignored by VCS are excluded. + - Unix hidden files and directories (starting with `.`) are excluded. + 3. Extract the `.crate` file and build it to verify it can build. - This will rebuild your package from scratch to ensure that it can be built from a pristine state. The `--no-verify` flag can be used to skip diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index 691ebc7b633..4085c6bb684 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -45,6 +45,33 @@ packaged lock file if the \fB\-\-locked\fR flag is used. about the current VCS checkout hash if available, as well as a flag if the worktree is dirty. .RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Symlinks are flattened to their target files. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Subdirectories containing \fBCargo.toml\fR are excluded, as they are assumed +to be separate packages. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'A \fBtarget\fR directory in the root of the package is excluded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Files and directories matching the \fB[include]\fR and \fB[exclude]\fR fields in +the manifest are included or excluded. Include patterns can override the +following rules. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Files that are ignored by VCS are excluded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Unix hidden files and directories (starting with \fB\&.\fR) are excluded. +.RE .RE .sp .RS 4 From 83ae3b771ea5d2d8be0f4c6c28e9a6a913f02f35 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Tue, 15 Oct 2024 07:57:28 -0700 Subject: [PATCH 3/4] Point to existing docs about include/exclude fields Co-authored-by: Weihang Lo --- src/doc/man/cargo-package.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/src/doc/man/cargo-package.md b/src/doc/man/cargo-package.md index d076b741188..9d691c12b96 100644 --- a/src/doc/man/cargo-package.md +++ b/src/doc/man/cargo-package.md @@ -33,14 +33,8 @@ stored in the `target/package` directory. This performs the following steps: about the current VCS checkout hash if available, as well as a flag if the worktree is dirty. - Symlinks are flattened to their target files. - - Subdirectories containing `Cargo.toml` are excluded, as they are assumed - to be separate packages. - - A `target` directory in the root of the package is excluded. - - Files and directories matching the `[include]` and `[exclude]` fields in - the manifest are included or excluded. Include patterns can override the - following rules. - - Files that are ignored by VCS are excluded. - - Unix hidden files and directories (starting with `.`) are excluded. + - Files and directories are included or excluded based on rules mentioned in + [the `[include]` and `[exclude]` fields](../reference/manifest.html#the-exclude-and-include-fields). 3. Extract the `.crate` file and build it to verify it can build. - This will rebuild your package from scratch to ensure that it can be From b8125da4e833f45a59447e8b3e18b1b2282cea13 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Tue, 15 Oct 2024 07:58:27 -0700 Subject: [PATCH 4/4] chore: cargo build-man --- src/doc/man/generated_txt/cargo-package.txt | 15 +++----------- src/doc/src/commands/cargo-package.md | 10 ++-------- src/etc/man/cargo-package.1 | 22 ++------------------- 3 files changed, 7 insertions(+), 40 deletions(-) diff --git a/src/doc/man/generated_txt/cargo-package.txt b/src/doc/man/generated_txt/cargo-package.txt index fac84660fb1..d7265289ce5 100644 --- a/src/doc/man/generated_txt/cargo-package.txt +++ b/src/doc/man/generated_txt/cargo-package.txt @@ -36,18 +36,9 @@ DESCRIPTION o Symlinks are flattened to their target files. - o Subdirectories containing Cargo.toml are excluded, as they are - assumed to be separate packages. - - o A target directory in the root of the package is excluded. - - o Files and directories matching the [include] and [exclude] fields - in the manifest are included or excluded. Include patterns can - override the following rules. - - o Files that are ignored by VCS are excluded. - - o Unix hidden files and directories (starting with .) are excluded. + o Files and directories are included or excluded based on rules + mentioned in the [include] and [exclude] fields + . 3. Extract the .crate file and build it to verify it can build. diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md index 5b02574f9e7..d50af10f411 100644 --- a/src/doc/src/commands/cargo-package.md +++ b/src/doc/src/commands/cargo-package.md @@ -28,14 +28,8 @@ stored in the `target/package` directory. This performs the following steps: about the current VCS checkout hash if available, as well as a flag if the worktree is dirty. - Symlinks are flattened to their target files. - - Subdirectories containing `Cargo.toml` are excluded, as they are assumed - to be separate packages. - - A `target` directory in the root of the package is excluded. - - Files and directories matching the `[include]` and `[exclude]` fields in - the manifest are included or excluded. Include patterns can override the - following rules. - - Files that are ignored by VCS are excluded. - - Unix hidden files and directories (starting with `.`) are excluded. + - Files and directories are included or excluded based on rules mentioned in + [the `[include]` and `[exclude]` fields](../reference/manifest.html#the-exclude-and-include-fields). 3. Extract the `.crate` file and build it to verify it can build. - This will rebuild your package from scratch to ensure that it can be diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index 4085c6bb684..9f124d96a4b 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -51,26 +51,8 @@ worktree is dirty. .RE .sp .RS 4 -\h'-04'\(bu\h'+02'Subdirectories containing \fBCargo.toml\fR are excluded, as they are assumed -to be separate packages. -.RE -.sp -.RS 4 -\h'-04'\(bu\h'+02'A \fBtarget\fR directory in the root of the package is excluded. -.RE -.sp -.RS 4 -\h'-04'\(bu\h'+02'Files and directories matching the \fB[include]\fR and \fB[exclude]\fR fields in -the manifest are included or excluded. Include patterns can override the -following rules. -.RE -.sp -.RS 4 -\h'-04'\(bu\h'+02'Files that are ignored by VCS are excluded. -.RE -.sp -.RS 4 -\h'-04'\(bu\h'+02'Unix hidden files and directories (starting with \fB\&.\fR) are excluded. +\h'-04'\(bu\h'+02'Files and directories are included or excluded based on rules mentioned in +\fIthe \f(BI[include]\fI and \f(BI[exclude]\fI fields\fR \&. .RE .RE .sp