From 4661c9a7d4bb720fef35a2e93a0baffd4e55d8ec Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 08:23:51 -0800 Subject: [PATCH 01/28] Mention --offline in the FAQ entry on offline. --- src/doc/src/faq.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/doc/src/faq.md b/src/doc/src/faq.md index ee006621856..2a58bdaf45a 100644 --- a/src/doc/src/faq.md +++ b/src/doc/src/faq.md @@ -178,7 +178,7 @@ and a populated cache of the crates reflected in the lock file. If either of these components are missing, then they're required for the build to succeed and must be fetched remotely. -As of Rust 1.11.0 Cargo understands a new flag, `--frozen`, which is an +As of Rust 1.11.0, Cargo understands a new flag, `--frozen`, which is an assertion that it shouldn't touch the network. When passed, Cargo will immediately return an error if it would otherwise attempt a network request. The error should include contextual information about why the network request is @@ -187,7 +187,15 @@ not change the behavior of Cargo*, it simply asserts that Cargo shouldn't touch the network as a previous command has been run to ensure that network activity shouldn't be necessary. +The `--offline` flag was added in Rust 1.36.0. This flag tells Cargo to not +access the network, and try to proceed with available cached data if possible. +You can use [`cargo fetch`] in one project to download dependencies before +going offline, and then use those same dependencies in another project with +the `--offline` flag (or [configuration value][offline config]). + For more information about vendoring, see documentation on [source replacement][replace]. [replace]: reference/source-replacement.md +[`cargo fetch`]: commands/cargo-fetch.md +[offline config]: reference/config.md#netoffline From bb3f1325a9dc9e0159ae2a20bb3d400d6d899453 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 08:28:28 -0800 Subject: [PATCH 02/28] Mention that `--features` can be specified multiple times. --- src/doc/man/generated/cargo-bench.html | 3 ++- src/doc/man/generated/cargo-build.html | 3 ++- src/doc/man/generated/cargo-check.html | 3 ++- src/doc/man/generated/cargo-doc.html | 3 ++- src/doc/man/generated/cargo-fix.html | 3 ++- src/doc/man/generated/cargo-install.html | 3 ++- src/doc/man/generated/cargo-metadata.html | 3 ++- src/doc/man/generated/cargo-package.html | 3 ++- src/doc/man/generated/cargo-publish.html | 3 ++- src/doc/man/generated/cargo-run.html | 3 ++- src/doc/man/generated/cargo-rustc.html | 3 ++- src/doc/man/generated/cargo-rustdoc.html | 3 ++- src/doc/man/generated/cargo-test.html | 3 ++- src/doc/man/options-features.adoc | 3 ++- src/etc/man/cargo-bench.1 | 9 +++++---- src/etc/man/cargo-build.1 | 3 ++- src/etc/man/cargo-check.1 | 3 ++- src/etc/man/cargo-doc.1 | 7 ++++--- src/etc/man/cargo-fix.1 | 3 ++- src/etc/man/cargo-install.1 | 9 +++++---- src/etc/man/cargo-metadata.1 | 7 ++++--- src/etc/man/cargo-package.1 | 7 ++++--- src/etc/man/cargo-publish.1 | 3 ++- src/etc/man/cargo-run.1 | 3 ++- src/etc/man/cargo-rustc.1 | 3 ++- src/etc/man/cargo-rustdoc.1 | 7 ++++--- src/etc/man/cargo-test.1 | 3 ++- 27 files changed, 68 insertions(+), 41 deletions(-) diff --git a/src/doc/man/generated/cargo-bench.html b/src/doc/man/generated/cargo-bench.html index c6e03d01ca5..c6355b5244a 100644 --- a/src/doc/man/generated/cargo-bench.html +++ b/src/doc/man/generated/cargo-bench.html @@ -213,7 +213,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-build.html b/src/doc/man/generated/cargo-build.html index a0d135aa49d..5c4e19387c6 100644 --- a/src/doc/man/generated/cargo-build.html +++ b/src/doc/man/generated/cargo-build.html @@ -142,7 +142,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-check.html b/src/doc/man/generated/cargo-check.html index 4147edbd710..fe7f7c8295f 100644 --- a/src/doc/man/generated/cargo-check.html +++ b/src/doc/man/generated/cargo-check.html @@ -146,7 +146,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-doc.html b/src/doc/man/generated/cargo-doc.html index 62d0542bfa3..643392e938a 100644 --- a/src/doc/man/generated/cargo-doc.html +++ b/src/doc/man/generated/cargo-doc.html @@ -124,7 +124,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-fix.html b/src/doc/man/generated/cargo-fix.html index 4cd6f46d66e..f068264e619 100644 --- a/src/doc/man/generated/cargo-fix.html +++ b/src/doc/man/generated/cargo-fix.html @@ -217,7 +217,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-install.html b/src/doc/man/generated/cargo-install.html index 252639075f2..bd18bb94aa3 100644 --- a/src/doc/man/generated/cargo-install.html +++ b/src/doc/man/generated/cargo-install.html @@ -212,7 +212,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-metadata.html b/src/doc/man/generated/cargo-metadata.html index bc86b267492..51405638d79 100644 --- a/src/doc/man/generated/cargo-metadata.html +++ b/src/doc/man/generated/cargo-metadata.html @@ -321,7 +321,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-package.html b/src/doc/man/generated/cargo-package.html index 77912c97554..20a023483e2 100644 --- a/src/doc/man/generated/cargo-package.html +++ b/src/doc/man/generated/cargo-package.html @@ -140,7 +140,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-publish.html b/src/doc/man/generated/cargo-publish.html index b3c3e4a6df3..6f79f51debf 100644 --- a/src/doc/man/generated/cargo-publish.html +++ b/src/doc/man/generated/cargo-publish.html @@ -133,7 +133,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-run.html b/src/doc/man/generated/cargo-run.html index 0ee9ab22ed3..538be3555a1 100644 --- a/src/doc/man/generated/cargo-run.html +++ b/src/doc/man/generated/cargo-run.html @@ -76,7 +76,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-rustc.html b/src/doc/man/generated/cargo-rustc.html index ff5b5c0287e..eab9fb580a1 100644 --- a/src/doc/man/generated/cargo-rustc.html +++ b/src/doc/man/generated/cargo-rustc.html @@ -137,7 +137,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-rustdoc.html b/src/doc/man/generated/cargo-rustdoc.html index b8426e51d51..e3620374589 100644 --- a/src/doc/man/generated/cargo-rustdoc.html +++ b/src/doc/man/generated/cargo-rustdoc.html @@ -152,7 +152,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/generated/cargo-test.html b/src/doc/man/generated/cargo-test.html index 4bf31f1dc79..fe8f0679bae 100644 --- a/src/doc/man/generated/cargo-test.html +++ b/src/doc/man/generated/cargo-test.html @@ -233,7 +233,8 @@

Feature Selection

Space or comma separated list of features to activate. These features only apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax.

+may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.

--all-features
diff --git a/src/doc/man/options-features.adoc b/src/doc/man/options-features.adoc index 666ef21e4ec..d9294e2d410 100644 --- a/src/doc/man/options-features.adoc +++ b/src/doc/man/options-features.adoc @@ -6,7 +6,8 @@ every selected package. *--features* _FEATURES_:: Space or comma separated list of features to activate. These features only apply to the current directory's package. Features of direct dependencies - may be enabled with `/` syntax. + may be enabled with `/` syntax. This flag may be + specified multiple times, which enables all specified features. *--all-features*:: Activate all available features of all selected packages. diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 626facce232..7321c1753c1 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -2,12 +2,12 @@ .\" Title: cargo-bench .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-11-15 +.\" Date: 2019-12-05 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-BENCH" "1" "2019-11-15" "\ \&" "\ \&" +.TH "CARGO\-BENCH" "1" "2019-12-05" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -251,7 +251,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP @@ -567,4 +568,4 @@ cargo bench \-\-bench bench_name \-\- modname::some_benchmark .RE .SH "SEE ALSO" .sp -\fBcargo\fP(1), \fBcargo\-test\fP(1) +\fBcargo\fP(1), \fBcargo\-test\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index 5a8565b8b3e..3e5603a1cb7 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -151,7 +151,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index 93c4efef929..12820a53697 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -155,7 +155,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 726db633ca2..fccfe8bfc7d 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -2,12 +2,12 @@ .\" Title: cargo-doc .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-11-11 +.\" Date: 2019-12-05 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-DOC" "1" "2019-11-11" "\ \&" "\ \&" +.TH "CARGO\-DOC" "1" "2019-12-05" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -123,7 +123,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index 3a493f9265c..b228671f555 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -225,7 +225,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 2dfdff5f5ec..6ab8bc36937 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -2,12 +2,12 @@ .\" Title: cargo-install .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-11-04 +.\" Date: 2019-12-05 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-INSTALL" "1" "2019-11-04" "\ \&" "\ \&" +.TH "CARGO\-INSTALL" "1" "2019-12-05" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -302,7 +302,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP @@ -511,4 +512,4 @@ cargo install \-\-list .RE .SH "SEE ALSO" .sp -\fBcargo\fP(1), \fBcargo\-uninstall\fP(1), \fBcargo\-search\fP(1), \fBcargo\-publish\fP(1) +\fBcargo\fP(1), \fBcargo\-uninstall\fP(1), \fBcargo\-search\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 index 7589c86a2f5..2529f686ade 100644 --- a/src/etc/man/cargo-metadata.1 +++ b/src/etc/man/cargo-metadata.1 @@ -2,12 +2,12 @@ .\" Title: cargo-metadata .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-10-28 +.\" Date: 2019-12-05 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-METADATA" "1" "2019-10-28" "\ \&" "\ \&" +.TH "CARGO\-METADATA" "1" "2019-12-05" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -324,7 +324,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index b1283fb76ec..7d34613271e 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -2,12 +2,12 @@ .\" Title: cargo-package .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-10-28 +.\" Date: 2019-11-21 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-PACKAGE" "1" "2019-10-28" "\ \&" "\ \&" +.TH "CARGO\-PACKAGE" "1" "2019-11-21" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -206,7 +206,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index 2f337d4eb09..52f309bf82a 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -169,7 +169,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 410f3a9521a..56c8074d89d 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -75,7 +75,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index 17b7722c86c..6f36d6ea82c 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -144,7 +144,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 668b083e9f0..761f7190e7f 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -2,12 +2,12 @@ .\" Title: cargo-rustdoc .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-11-11 +.\" Date: 2019-12-05 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-RUSTDOC" "1" "2019-11-11" "\ \&" "\ \&" +.TH "CARGO\-RUSTDOC" "1" "2019-12-05" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -154,7 +154,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 476ea5f254f..94aecf61650 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -287,7 +287,8 @@ every selected package. .RS 4 Space or comma separated list of features to activate. These features only apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. +may be enabled with \fB/\fP syntax. This flag may be +specified multiple times, which enables all specified features. .RE .sp \fB\-\-all\-features\fP From 97b833e6badd20f5980ae11475831a443710723a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 09:08:01 -0800 Subject: [PATCH 03/28] Add links for rustflags/rustdocflags. --- src/doc/man/cargo-rustc.adoc | 4 ++-- src/doc/man/cargo-rustdoc.adoc | 4 ++-- src/doc/man/generated/cargo-rustc.html | 4 ++-- src/doc/man/generated/cargo-rustdoc.html | 4 ++-- src/etc/man/cargo-rustc.1 | 8 +++++--- src/etc/man/cargo-rustdoc.1 | 10 ++++++---- 6 files changed, 19 insertions(+), 15 deletions(-) diff --git a/src/doc/man/cargo-rustc.adoc b/src/doc/man/cargo-rustc.adoc index 7ba60cb19e1..e3ef3e5fc72 100644 --- a/src/doc/man/cargo-rustc.adoc +++ b/src/doc/man/cargo-rustc.adoc @@ -25,8 +25,8 @@ flags. include::description-one-target.adoc[] To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` -environment variable or the `build.rustflags` -linkcargo:reference/config.html[config value]. +linkcargo:reference/environment-variables.html[environment variable] or the +`build.rustflags` linkcargo:reference/config.html[config value]. == OPTIONS diff --git a/src/doc/man/cargo-rustdoc.adoc b/src/doc/man/cargo-rustdoc.adoc index 61dfcb413db..96f37252aaa 100644 --- a/src/doc/man/cargo-rustdoc.adoc +++ b/src/doc/man/cargo-rustdoc.adoc @@ -25,8 +25,8 @@ flags. include::description-one-target.adoc[] To pass flags to all rustdoc processes spawned by Cargo, use the -`RUSTDOCFLAGS` environment variable or the `build.rustdocflags` configuration -option. +`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable] +or the `build.rustdocflags` linkcargo:reference/config.html[config value]. == OPTIONS diff --git a/src/doc/man/generated/cargo-rustc.html b/src/doc/man/generated/cargo-rustc.html index eab9fb580a1..5642a4aa642 100644 --- a/src/doc/man/generated/cargo-rustc.html +++ b/src/doc/man/generated/cargo-rustc.html @@ -31,8 +31,8 @@

DESCRIPTION

package the filters of --lib, --bin, etc, must be used to select which target is compiled. To pass flags to all compiler processes spawned by Cargo, use the RUSTFLAGS -environment variable or the build.rustflags -config value.

+environment variable or the +build.rustflags config value.

diff --git a/src/doc/man/generated/cargo-rustdoc.html b/src/doc/man/generated/cargo-rustdoc.html index e3620374589..c8c73a2fd6c 100644 --- a/src/doc/man/generated/cargo-rustdoc.html +++ b/src/doc/man/generated/cargo-rustdoc.html @@ -31,8 +31,8 @@

DESCRIPTION

package the filters of --lib, --bin, etc, must be used to select which target is compiled. To pass flags to all rustdoc processes spawned by Cargo, use the -RUSTDOCFLAGS environment variable or the build.rustdocflags configuration -option.

+RUSTDOCFLAGS environment variable +or the build.rustdocflags config value.

diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index 6f36d6ea82c..018d64bf21e 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -2,12 +2,12 @@ .\" Title: cargo-rustc .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 +.\" Date: 2019-12-18 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-RUSTC" "1" "2019-09-05" "\ \&" "\ \&" +.TH "CARGO\-RUSTC" "1" "2019-12-18" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -51,7 +51,9 @@ arguments are provided. If more than one target is available for the current package the filters of \fB\-\-lib\fP, \fB\-\-bin\fP, etc, must be used to select which target is compiled. To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fP -environment variable or the \fBbuild.rustflags\fP +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable" " " +or the +\fBbuild.rustflags\fP \c .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." .SH "OPTIONS" .SS "Package Selection" diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 761f7190e7f..3ee72e244ca 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -2,12 +2,12 @@ .\" Title: cargo-rustdoc .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-12-05 +.\" Date: 2019-12-18 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-RUSTDOC" "1" "2019-12-05" "\ \&" "\ \&" +.TH "CARGO\-RUSTDOC" "1" "2019-12-18" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -51,8 +51,10 @@ arguments are provided. If more than one target is available for the current package the filters of \fB\-\-lib\fP, \fB\-\-bin\fP, etc, must be used to select which target is compiled. To pass flags to all rustdoc processes spawned by Cargo, use the -\fBRUSTDOCFLAGS\fP environment variable or the \fBbuild.rustdocflags\fP configuration -option. +\fBRUSTDOCFLAGS\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable" +or the \fBbuild.rustdocflags\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." .SH "OPTIONS" .SS "Documentation Options" .sp From 64f605bf6ab87f41e83c1c717e1d5a4a2fd9c329 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 10:34:46 -0800 Subject: [PATCH 04/28] Document the target directory layout. Closes #4756. --- src/doc/src/guide/build-cache.md | 76 +++++++++++++++++++++++++++----- 1 file changed, 66 insertions(+), 10 deletions(-) diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md index a84bbdf4b9f..0c455b2ae53 100644 --- a/src/doc/src/guide/build-cache.md +++ b/src/doc/src/guide/build-cache.md @@ -1,15 +1,71 @@ ## Build cache -Cargo shares build artifacts among all the packages of a single workspace. -Today, Cargo does not share build results across different workspaces, but -a similar result can be achieved by using a third party tool, [sccache]. +Cargo stores the output of a build into the "target" directory. By default, +this is the directory named `target` in the root of your workspace. To change +the location, you can set the `CARGO_TARGET_DIR` [environment variable], the +[`build.target-dir`] config value, or the `--target-dir` command-line flag. -To setup `sccache`, install it with `cargo install sccache` and set -`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. -If you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to -`.bashrc`. Alternatively, you can set `build.rustc-wrapper` in the - [Cargo configuration][config]. Refer to sccache documentation for more - details. +The directory layout depends on whether or not you are cross-compiling for a +different platform with the `--target` flag. When not cross-compiling, the +output goes into the root of the target directory, separated based on whether +or not it is a release build: -[sccache]: https://github.com/mozilla/sccache +Directory | Description +----------|------------ +target/debug/ | Contains debug build output. +target/release/ | Contains release build output (with `--release` flag). + +When building for another target, the output is placed in a directory with the +name of the target: + +Directory | Example +----------|-------- +target/<triple>/debug/ | target/thumbv7em-none-eabihf/debug/ +target/<triple>/release/ | target/thumbv7em-none-eabihf/release/ + +Within the profile directory (`debug` or `release`), artifacts are placed into +the following directories: + +Directory | Description +----------|------------ +target/debug/ | Contains the output of the package being built (the `[[bin]]` executables and `[lib]` library targets). +target/debug/examples/ | Contains examples (`[[example]]` targets). + +Some commands place their output in dedicated directories in the top level of +the `target` directory: + +Directory | Description +----------|------------ +target/doc/ | Contains rustdoc documentation ([`cargo doc`]). +target/package/ | Contains the output of the [`cargo package`] and [`cargo publish`] commands. + +Cargo also creates several other directories and files needed for the build +process. Their layout is considered internal to Cargo, and is subject to +change. Some of these directories are: + +Directory | Description +----------|------------ +target/debug/deps/ |  Dependencies and other artifacts. +target/debug/incremental/ |  `rustc` [incremental output], a cache used to speed up subsequent builds. +target/debug/build/ |  Output from [build scripts]. + +### Shared cache + +A third party tool, [sccache], can be used to share built dependencies across +different workspaces. + +To setup `sccache`, install it with `cargo install sccache` and set +`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If +you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to +`.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo +configuration][config]. Refer to sccache documentation for more details. + +[`build.target-dir`]: ../reference/config.md#buildtarget-dir +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo package`]: ../commands/cargo-package.md +[`cargo publish`]: ../commands/cargo-publish.md +[build scripts]: ../reference/build-scripts.md [config]: ../reference/config.md +[environment variable]: ../reference/environment-variables.md +[incremental output]: ../reference/profiles.md#incremental +[sccache]: https://github.com/mozilla/sccache From 98752b0049b350188a8b514455c3c7492d3473a8 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 11:04:53 -0800 Subject: [PATCH 05/28] Fix awkward comma in sentence. --- src/doc/src/reference/manifest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 9842329f5e5..973a45e14b0 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -20,7 +20,7 @@ The package name is an identifier used to refer to the package. It is used when listed as a dependency in another package, and as the default name of inferred lib and bin targets. -The name must not be empty, use only [alphanumeric] characters or `-` or `_`. +The name must use only [alphanumeric] characters or `-` or `_`, and cannot be empty. Note that [`cargo new`] and [`cargo init`] impose some additional restrictions on the package name, such as enforcing that it is a valid Rust identifier and not a keyword. [crates.io][cratesio] imposes even more restrictions, such as From da881b717891c05158f70b727a6b8b6722db0963 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 11:27:30 -0800 Subject: [PATCH 06/28] Simplify some crates.io links. --- src/doc/src/reference/manifest.md | 22 +++++++++---------- .../src/reference/specifying-dependencies.md | 6 ++--- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 973a45e14b0..98009b4e4e8 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -23,7 +23,7 @@ inferred lib and bin targets. The name must use only [alphanumeric] characters or `-` or `_`, and cannot be empty. Note that [`cargo new`] and [`cargo init`] impose some additional restrictions on the package name, such as enforcing that it is a valid Rust identifier and not -a keyword. [crates.io][cratesio] imposes even more restrictions, such as +a keyword. [crates.io] imposes even more restrictions, such as enforcing only ASCII characters, not a reserved name, not a special Windows name such as "nul", is not too long, etc. @@ -50,7 +50,7 @@ The `authors` field lists people or organizations that are considered the "authors" of the package. The exact meaning is open to interpretation — it may list the original or primary authors, current maintainers, or owners of the package. These names will be listed on the crate's page on -[crates.io][cratesio]. An optional email address may be included within angled +[crates.io]. An optional email address may be included within angled brackets at the end of each author. #### The `edition` field (optional) @@ -108,8 +108,8 @@ links = "foo" #### The `documentation` field (optional) This field specifies a URL to a website hosting the crate's documentation. -If no URL is specified in the manifest file, [crates.io][cratesio] will -automatically link your crate to the corresponding [docs.rs][docsrs] page. +If no URL is specified in the manifest file, [crates.io] will +automatically link your crate to the corresponding [docs.rs] page. Documentation links from specific hosts are blacklisted. Hosts are added to the blacklist if they are known to not be hosting documentation and are @@ -118,12 +118,9 @@ following hosts are blacklisted: * rust-ci.org -Documentation URLs from blacklisted hosts will not appear on crates.io, and +Documentation URLs from blacklisted hosts will not appear on [crates.io], and may be replaced by docs.rs links. -[docsrs]: https://docs.rs/ -[cratesio]: https://crates.io/ - #### The `exclude` and `include` fields (optional) You can explicitly specify that a set of file patterns should be ignored or @@ -224,7 +221,7 @@ For more information, see the documentation for the workspace table below. #### The `license` and `license-file` fields (optional) The `license` field can be set to an [SPDX 2.1 license -expression][spdx-2.1-license-expressions] for the package. Currently crates.io +expression][spdx-2.1-license-expressions] for the package. Currently [crates.io] will validate the license provided against a whitelist of known license and exception identifiers from the [SPDX license list 3.6][spdx-license-list-3.6]. Parentheses are not currently supported. @@ -285,7 +282,7 @@ keywords = ["...", "..."] categories = ["...", "..."] ``` -The [crates.io](https://crates.io) registry will render the description, display +The [crates.io] registry will render the description, display the license, link to the three URLs and categorize by the keywords. These keys provide useful information to users of the registry and also influence the search ranking of a crate. It is highly discouraged to omit everything in a @@ -293,7 +290,7 @@ published crate. ### The `[badges]` section -crates.io can display various badges for build status, test coverage, etc. for +[crates.io] can display various badges for build status, test coverage, etc. for each crate. All badges are optional. - The badges pertaining to build status that are currently available are @@ -903,7 +900,6 @@ dependencies][replace] section of the documentation and [RFC 1969] for the technical specification of this feature. [RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969 -[crates.io]: https://crates.io/ [replace]: specifying-dependencies.md#overriding-dependencies #### Using `[patch]` with multiple versions @@ -957,5 +953,7 @@ dependencies][replace] section of the documentation. [`cargo new`]: ../commands/cargo-new.md [`cargo run`]: ../commands/cargo-run.md [`cargo test`]: ../commands/cargo-test.md +[crates.io]: https://crates.io/ +[docs.rs]: https://docs.rs/ [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 [spdx-license-list-3.6]: https://github.com/spdx/license-list-data/tree/v3.6 diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index aa2881df00b..9966150e2ef 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -175,7 +175,7 @@ And that’s it! The next `cargo build` will automatically build `hello_utils` a all of its own dependencies, and others can also start using the crate as well. However, crates that use dependencies specified with only a path are not permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we -would need to publish a version of `hello_utils` to [crates.io](https://crates.io) +would need to publish a version of `hello_utils` to [crates.io] and specify its version in the dependencies line as well: ```toml @@ -530,8 +530,6 @@ example: mio = "0.0.1" ``` -[crates.io]: https://crates.io/ - ### Build dependencies You can depend on other Cargo-based crates for use in your build scripts. @@ -625,3 +623,5 @@ following to the above manifest: [features] log-debug = ['foo/log-debug'] # using 'bar/log-debug' would be an error! ``` + +[crates.io]: https://crates.io/ From 2a4aa42018aa8c76cd72eebeb19f7185db89c7fe Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 22:06:53 -0800 Subject: [PATCH 07/28] Be clearer about which fields are optional/required. This attempts to be clearer about the requirements for crates.io publishing. This also includes some other clarifications around various fields and specifying dependencies. Closes #3971 Closes #7055 --- src/doc/src/appendix/glossary.md | 2 +- src/doc/src/reference/manifest.md | 292 +++++++++++------- src/doc/src/reference/publishing.md | 39 ++- .../src/reference/specifying-dependencies.md | 46 +++ 4 files changed, 248 insertions(+), 131 deletions(-) diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md index 4bd44c54c3c..cfb3785093a 100644 --- a/src/doc/src/appendix/glossary.md +++ b/src/doc/src/appendix/glossary.md @@ -180,7 +180,7 @@ manifest is located. [config option]: ../reference/config.md [directory layout]: ../reference/manifest.md#the-project-layout [edition guide]: ../../edition-guide/index.html -[edition-field]: ../reference/manifest.md#the-edition-field-optional +[edition-field]: ../reference/manifest.md#the-edition-field [environment variable]: ../reference/environment-variables.md [feature]: ../reference/manifest.md#the-features-section [git dependency]: ../reference/specifying-dependencies.md#specifying-dependencies-from-git-repositories diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 98009b4e4e8..e729ccb1d27 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -3,6 +3,7 @@ The `Cargo.toml` file for each package is called its *manifest*. Every manifest file consists of one or more sections. + ### The `[package]` section The first section in a `Cargo.toml` is `[package]`. @@ -14,6 +15,11 @@ version = "0.1.0" # the current version, obeying semver authors = ["Alice ", "Bob "] ``` +The only fields required by Cargo are [`name`](#the-name-field) and +[`version`](#the-version-field). If publishing to a registry, the registry may +require additional fields. See the notes below and [the publishing +chapter][publishing] for requirements for publishing to [crates.io]. + #### The `name` field The package name is an identifier used to refer to the package. It is used @@ -44,7 +50,7 @@ Versioning](https://semver.org/), so make sure you follow some basic rules: traits, fields, types, functions, methods or anything else. * Use version numbers with three numeric parts such as 1.0.0 rather than 1.0. -#### The `authors` field (optional) +#### The `authors` field The `authors` field lists people or organizations that are considered the "authors" of the package. The exact meaning is open to interpretation — it may @@ -53,9 +59,11 @@ package. These names will be listed on the crate's page on [crates.io]. An optional email address may be included within angled brackets at the end of each author. -#### The `edition` field (optional) +> **Note**: [crates.io] requires at least one author to be listed. + +#### The `edition` field -You can opt in to a specific Rust Edition for your package with the +You can opt in to a specific [Rust Edition] for your package with the `edition` key in `Cargo.toml`. If you don't specify the edition, it will default to 2015. @@ -71,12 +79,162 @@ latest edition. Setting the `edition` key in `[package]` will affect all targets/crates in the package, including test suites, benchmarks, binaries, examples, etc. +#### The `description` field + +The description is a short blurb about the package. [crates.io] will display +this with your package. This should be plain text (not Markdown). + +```toml +[package] +# ... +description = "A short description of my package" +``` + +> **Note**: [crates.io] requires the `description` to be set. + +#### The `documentation` field + +The `documentation` field specifies a URL to a website hosting the crate's +documentation. If no URL is specified in the manifest file, [crates.io] will +automatically link your crate to the corresponding [docs.rs] page. + +```toml +[package] +# ... +documentation = "https://docs.rs/bitflags" +``` + +> **Note**: [crates.io] may not show certain sites if they are known to not be +> hosting documentation and are possibly of malicious intent e.g., ad tracking +> networks. At this time, the site `rust-ci.org` is not allowed. + +#### The `readme` field + +The `readme` field should be the path to a file in the package root (relative +to this `Cargo.toml`) that contains general information about the package. +This file will be transferred to the registry when you publish. [crates.io] +will interpret it as Markdown and render it on the crate's page. + +```toml +[package] +# ... +readme = "README.md" +``` + +#### The `homepage` field + +The `homepage` field should be a URL to a site that is the home page for your +package. + +```toml +[package] +# ... +homepage = "https://serde.rs/" +``` + +#### The `repository` field + +The `repository` field should be a URL to the source repository for your +package. + +```toml +[package] +# ... +repository = "https://github.com/rust-lang/cargo/" +``` + +#### The `license` and `license-file` fields + +The `license` field contains the name of the software license that the package +is released under. The `license-file` field contains the path to a file +containing the text of the license (relative to this `Cargo.toml`). + +[crates.io] interprets the `license` field as an [SPDX 2.1 license +expression][spdx-2.1-license-expressions]. The name must be a known license +from the [SPDX license list 3.6][spdx-license-list-3.6]. Parentheses are not +currently supported. See the [SPDX site] for more information. + +SPDX license expressions support AND and OR operators to combine multiple +licenses.[^slash] + +```toml +[package] +# ... +license = "MIT OR Apache-2.0" +``` + +Using `OR` indicates the user may choose either license. Using `AND` indicates +the user must comply with both licenses simultaneously. The `WITH` operator +indicates a license with a special exception. Some examples: + +* `MIT OR Apache-2.0` +* `LGPL-2.1 AND MIT AND BSD-2-Clause` +* `GPL-2.0+ WITH Bison-exception-2.2` + +If a package is using a nonstandard license, then the `license-file` field may +be specified in lieu of the `license` field. + +```toml +[package] +# ... +license-file = "LICENSE.txt" +``` + +> **Note**: [crates.io] requires either `license` or `license-file` to be set. + +[^slash]: Previously multiple licenses could be separated with a `/`, but that +usage is deprecated. + +#### The `keywords` field + +The `keywords` field is an array of strings that describe this package. This +can help when searching for the package on a registry, and you may choose any +words that would help someone find this crate. + +```toml +[package] +# ... +keywords = ["gamedev", "graphics"] +``` + +> **Note**: [crates.io] has a maximum of 5 keywords. Each keyword must be +> ASCII text, start with a letter, and only contain letters, numbers, `_` or +> `-`, and have at most 20 characters. + +#### The `categories` field + +The `categories` field is an array of strings of the categories this package +belongs to. + +```toml +categories = ["command-line-utilities", "development-tools::cargo-plugins"] +``` + +> **Note**: [crates.io] has a maximum of 5 categories. Each category should +> match one of the strings available at , and +> must match exactly. + +#### The `workspace` field + +The `workspace` field can be used to configure the workspace that this package +will be a member of. If not specified this will be inferred as the first +Cargo.toml with `[workspace]` upwards in the filesystem. + +```toml +[package] +# ... +workspace = "path/to/workspace/root" +``` + +For more information, see the documentation for the [workspace table +below](#the-workspace-section). + -#### The `build` field (optional) +#### The `build` field -This field specifies a file in the package root which is a [build script] for -building native code. More information can be found in the [build script -guide][build script]. +The `build` field specifies a file in the package root which is a [build +script] for building native code. More information can be found in the [build +script guide][build script]. [build script]: build-scripts.md @@ -91,10 +249,10 @@ The default is `"build.rs"`, which loads the script from a file named specify a path to a different file or `build = false` to disable automatic detection of the build script. -#### The `links` field (optional) +#### The `links` field -This field specifies the name of a native library that is being linked to. -More information can be found in the [`links`][links] section of the build +The `links` field specifies the name of a native library that is being linked +to. More information can be found in the [`links`][links] section of the build script guide. [links]: build-scripts.md#the-links-manifest-key @@ -105,23 +263,7 @@ script guide. links = "foo" ``` -#### The `documentation` field (optional) - -This field specifies a URL to a website hosting the crate's documentation. -If no URL is specified in the manifest file, [crates.io] will -automatically link your crate to the corresponding [docs.rs] page. - -Documentation links from specific hosts are blacklisted. Hosts are added -to the blacklist if they are known to not be hosting documentation and are -possibly of malicious intent e.g., ad tracking networks. URLs from the -following hosts are blacklisted: - -* rust-ci.org - -Documentation URLs from blacklisted hosts will not appear on [crates.io], and -may be replaced by docs.rs links. - -#### The `exclude` and `include` fields (optional) +#### The `exclude` and `include` fields You can explicitly specify that a set of file patterns should be ignored or included for the purposes of packaging. The patterns specified in the @@ -183,7 +325,7 @@ if any of those files change. [gitignore]: https://git-scm.com/docs/gitignore -#### The `publish` field (optional) +#### The `publish` field The `publish` field can be used to prevent a package from being published to a package registry (like *crates.io*) by mistake, for instance to keep a package @@ -204,90 +346,6 @@ allowed to be published to. publish = ["some-registry-name"] ``` -#### The `workspace` field (optional) - -The `workspace` field can be used to configure the workspace that this package -will be a member of. If not specified this will be inferred as the first -Cargo.toml with `[workspace]` upwards in the filesystem. - -```toml -[package] -# ... -workspace = "path/to/workspace/root" -``` - -For more information, see the documentation for the workspace table below. - -#### The `license` and `license-file` fields (optional) - -The `license` field can be set to an [SPDX 2.1 license -expression][spdx-2.1-license-expressions] for the package. Currently [crates.io] -will validate the license provided against a whitelist of known license and -exception identifiers from the [SPDX license list 3.6][spdx-license-list-3.6]. -Parentheses are not currently supported. - -Previously multiple licenses could be separated with a `/`, but that usage is -deprecated. Instead, use a license expression with AND and OR operators to get -more explicit semantics. - -```toml -[package] -# ... -license = "MIT OR Apache-2.0" -``` - -If a package is using a nonstandard license, then the `license-file` field may -be specified in lieu of the `license` field. It must point to a file relative to -this manifest (similar to the `readme` field). - -```toml -[package] -# ... -license-file = "..." -``` - -#### Package metadata - -There are a number of optional metadata fields also accepted under the -`[package]` section: - -```toml -[package] -# ... - -# A short blurb about the package. This is not rendered in any format when -# uploaded to crates.io (aka this is not markdown). -description = "..." - -# These URLs point to more information about the package. These are -# intended to be webviews of the relevant data, not necessarily compatible -# with VCS tools and the like. -documentation = "..." -homepage = "..." -repository = "..." - -# This points to a file under the package root (relative to this `Cargo.toml`). -# The contents of this file are stored and indexed in the registry. -# crates.io will render this file and place the result on the crate's page. -readme = "..." - -# This is a list of up to five keywords that describe this crate. Keywords -# are searchable on crates.io, and you may choose any words that would -# help someone find this crate. -keywords = ["...", "..."] - -# This is a list of up to five categories where this crate would fit. -# Categories are a fixed list available at crates.io/category_slugs, and -# they must match exactly. -categories = ["...", "..."] -``` - -The [crates.io] registry will render the description, display -the license, link to the three URLs and categorize by the keywords. These keys -provide useful information to users of the registry and also influence the -search ranking of a crate. It is highly discouraged to omit everything in a -published crate. - ### The `[badges]` section [crates.io] can display various badges for build status, test coverage, etc. for @@ -367,7 +425,7 @@ is-it-maintained-open-issues = { repository = "..." } maintenance = { status = "..." } ``` -#### The `metadata` table (optional) +#### The `metadata` table Cargo by default will warn about unused keys in `Cargo.toml` to assist in detecting typos and such. The `package.metadata` table, however, is completely @@ -492,6 +550,9 @@ Note that it is explicitly allowed for features to not actually activate any optional dependencies. This allows packages to internally enable/disable features without requiring a new dependency. +> **Note**: [crates.io] requires feature names to only contain ASCII letters, +> digits, `_`, or `-`. + #### Usage in end products One major use-case for this feature is specifying optional features in @@ -821,7 +882,7 @@ autobins = false > is `false` if at least one target is manually defined in `Cargo.toml`. > Beginning with the 2018 edition, the default is always `true`. -#### The `required-features` field (optional) +#### The `required-features` field The `required-features` field specifies which features the target needs in order to be built. If any of the required features are not selected, the target will @@ -955,5 +1016,8 @@ dependencies][replace] section of the documentation. [`cargo test`]: ../commands/cargo-test.md [crates.io]: https://crates.io/ [docs.rs]: https://docs.rs/ +[publishing]: publishing.md +[Rust Edition]: ../../edition-guide/index.html [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 [spdx-license-list-3.6]: https://github.com/spdx/license-list-data/tree/v3.6 +[SPDX site]: https://spdx.org/license-list diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md index eea28e9038c..88e6f888fde 100644 --- a/src/doc/src/reference/publishing.md +++ b/src/doc/src/reference/publishing.md @@ -30,19 +30,19 @@ immediately. Keep in mind that crate names on [crates.io] are allocated on a first-come-first- serve basis. Once a crate name is taken, it cannot be used for another crate. -Check out the [metadata you can -specify](manifest.md#package-metadata) in `Cargo.toml` to ensure -your crate can be discovered more easily! Before publishing, make sure you have -filled out the following fields: - -- `authors` -- `license` or `license-file` -- `description` -- `homepage` -- `documentation` -- `repository` - -It would also be a good idea to include some `keywords` and `categories`, +Check out the [metadata you can specify](manifest.md) in `Cargo.toml` to +ensure your crate can be discovered more easily! Before publishing, make sure +you have filled out the following fields: + +- [`authors`] +- [`license` or `license-file`] +- [`description`] +- [`homepage`] +- [`documentation`] +- [`repository`] +- [`readme`] + +It would also be a good idea to include some [`keywords`] and [`categories`], though they are not required. If you are publishing a library, you may also want to consult the [Rust API @@ -83,8 +83,7 @@ $ cargo package --list Cargo will automatically ignore files ignored by your version control system when packaging, but if you want to specify an extra set of files to ignore you -can use the [`exclude` -key](manifest.md#the-exclude-and-include-fields-optional) in the +can use the [`exclude` key](manifest.md#the-exclude-and-include-fields) in the manifest: ```toml @@ -241,9 +240,17 @@ the “Grant Access” button next to its name: [RFC 1105]: https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md [Rust API Guidelines]: https://rust-lang-nursery.github.io/api-guidelines/ +[`authors`]: manifest.md#the-authors-field [`cargo login`]: ../commands/cargo-login.md [`cargo package`]: ../commands/cargo-package.md [`cargo publish`]: ../commands/cargo-publish.md +[`categories`]: manifest.md#the-categories-field +[`description`]: manifest.md#the-description-field +[`documentation`]: manifest.md#the-documentation-field +[`homepage`]: manifest.md#the-homepage-field +[`keywords`]: manifest.md#the-keywords-field +[`license` or `license-file`]: manifest.md#the-license-and-license-file-fields +[`readme`]: manifest.md#the-readme-field +[`repository`]: manifest.md#the-repository-field [crates.io]: https://crates.io/ [oauth-scopes]: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/ - diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 9966150e2ef..5188cc102dd 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -83,6 +83,8 @@ positioned. 1.2.* := >=1.2.0, <1.3.0 ``` +> **Note**: [crates.io] does not allow bare `*` versions. + ### Comparison requirements **Comparison requirements** allow manually specifying a version range or an @@ -114,6 +116,9 @@ to the name of the registry to use. some-crate = { version = "1.0", registry = "my-registry" } ``` +> **Note**: [crates.io] does not allow packages to be published with +> dependencies on other registries. + [registries documentation]: registries.md ### Specifying dependencies from `git` repositories @@ -144,6 +149,10 @@ rand = { git = "https://github.com/rust-lang-nursery/rand", branch = "next" } See [Git Authentication] for help with git authentication for private repos. +> **Note**: [crates.io] does not allow packages to be published with `git` +> dependencies (`git` [dev-dependencies] are ignored). See the [Multiple +> locations](#multiple-locations) section for a fallback alternative. + [Git Authentication]: ../appendix/git-authentication.md ### Specifying path dependencies @@ -183,6 +192,36 @@ and specify its version in the dependencies line as well: hello_utils = { path = "hello_utils", version = "0.1.0" } ``` +> **Note**: [crates.io] does not allow packages to be published with `path` +> dependencies (`path` [dev-dependencies] are ignored). See the [Multiple +> locations](#multiple-locations) section for a fallback alternative. + +### Multiple locations + +It is possible to specify both a registry version and a `git` or `path` +location. The `git` or `path` dependency will be used locally (in which case +the `version` is ignored), and when published to a registry like [crates.io], +it will use the registry version. Other combinations are not allowed. +Examples: + +```toml +[dependencies] +# Uses `my-bitflags` when used locally, and uses +# version 1.0 from crates.io when published. +bitflags = { path = "my-bitflags", version = "1.0" } + +# Uses the given git repo when used locally, and uses +# version 1.0 from crates.io when published. +smallvec = { git = "https://github.com/servo/rust-smallvec", version = "1.0" } +``` + +One example where this can be useful is when you have split up a library into +multiple packages within the same workspace. You can then use `path` +dependencies to point to the local packages within the workspace to use the +local version during development, and then use the [crates.io] version once it +is published. This is similar to specifying an +[override](#overriding-dependencies). + ### Overriding dependencies There are a number of methods in Cargo to support overriding dependencies and @@ -530,6 +569,12 @@ example: mio = "0.0.1" ``` +> **Note**: When a package is published, only dev-dependencies that specify a +> `version` will be included in the published crate. For most use cases, +> dev-dependencies are not needed when published, though some users (like OS +> packagers) may want to run tests within a crate, so providing a `version` if +> possible can still be beneficial. + ### Build dependencies You can depend on other Cargo-based crates for use in your build scripts. @@ -625,3 +670,4 @@ log-debug = ['foo/log-debug'] # using 'bar/log-debug' would be an error! ``` [crates.io]: https://crates.io/ +[dev-dependencies]: #development-dependencies From b884b0d20a4e5a7d17698c1855fab55f0fff6343 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 22:17:22 -0800 Subject: [PATCH 08/28] Fix minor `vendor` mistake in glossary. --- src/doc/src/appendix/glossary.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md index cfb3785093a..fec93a83ccf 100644 --- a/src/doc/src/appendix/glossary.md +++ b/src/doc/src/appendix/glossary.md @@ -135,9 +135,9 @@ The meaning of the term *target* depends on the context: `thumb`, `mips`, etc. - `sub` = The CPU sub-architecture, for example `arm` has `v7`, `v7s`, `v5te`, etc. - - `vendor` = The vendor, for example `unknown`, `apple`, `pc`, `linux`, etc. - - `sys` = The system name, for example `linux`, `windows`, etc. `none` is - typically used for bare-metal without an OS. + - `vendor` = The vendor, for example `unknown`, `apple`, `pc`, `nvidia`, etc. + - `sys` = The system name, for example `linux`, `windows`, `darwin`, etc. + `none` is typically used for bare-metal without an OS. - `abi` = The ABI, for example `gnu`, `android`, `eabi`, etc. Some parameters may be omitted. Run `rustc --print target-list` for a list of From 07aed501c544c2ac180e21406222b0a08c0896ac Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2019 22:29:35 -0800 Subject: [PATCH 09/28] Fix some chapter links missing from index pages. --- src/doc/src/index.md | 4 ++++ src/doc/src/reference/index.md | 2 ++ 2 files changed, 6 insertions(+) diff --git a/src/doc/src/index.md b/src/doc/src/index.md index b33385c4823..17595ff9cd9 100644 --- a/src/doc/src/index.md +++ b/src/doc/src/index.md @@ -25,6 +25,10 @@ The reference covers the details of various areas of Cargo. **[Frequently Asked Questions](faq.md)** +**Appendicies:** +* [Glossary](appendix/glossary.md) +* [Git Authentication](appendix/git-authentication.md) + [rust]: https://www.rust-lang.org/ [crates.io]: https://crates.io/ [GitHub]: https://github.com/rust-lang/cargo/tree/master/src/doc diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md index a9bf76c8537..a6eb8a2e0c9 100644 --- a/src/doc/src/reference/index.md +++ b/src/doc/src/reference/index.md @@ -4,6 +4,7 @@ The reference covers the details of various areas of Cargo. * [Specifying Dependencies](specifying-dependencies.md) * [The Manifest Format](manifest.md) +* [Profiles](profiles.md) * [Configuration](config.md) * [Environment Variables](environment-variables.md) * [Build Scripts](build-scripts.md) @@ -11,4 +12,5 @@ The reference covers the details of various areas of Cargo. * [Package ID Specifications](pkgid-spec.md) * [Source Replacement](source-replacement.md) * [External Tools](external-tools.md) +* [Registries](registries.md) * [Unstable Features](unstable.md) From fee34fcf651a34f12ba41428009b35180279638d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 10:11:17 -0800 Subject: [PATCH 10/28] Clarify `cargo fix` behavior with features. --- src/doc/man/cargo-fix.adoc | 14 +++++++++----- src/doc/man/generated/cargo-fix.html | 15 ++++++++++----- src/etc/man/cargo-fix.1 | 18 +++++++++++------- 3 files changed, 30 insertions(+), 17 deletions(-) diff --git a/src/doc/man/cargo-fix.adoc b/src/doc/man/cargo-fix.adoc index 2a7ff56a64f..0cc8c3da4f8 100644 --- a/src/doc/man/cargo-fix.adoc +++ b/src/doc/man/cargo-fix.adoc @@ -28,14 +28,18 @@ executing: cargo fix --edition -which behaves the same as `cargo check --all-targets`. Similarly if you'd like -to fix code for different platforms you can do: +which behaves the same as `cargo check --all-targets`. - cargo fix --edition --target x86_64-pc-windows-gnu +`cargo fix` is only capable of fixing code that is normally compiled with +`cargo check`. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed: + + cargo fix --edition --features foo -or if your crate has optional features: +Similarly, other `cfg` expressions like platform-specific code will need to +pass `--target` to fix code for the given target. - cargo fix --edition --no-default-features --features foo + cargo fix --edition --target x86_64-pc-windows-gnu If you encounter any problems with `cargo fix` or otherwise have any questions or feature requests please don't hesitate to file an issue at diff --git a/src/doc/man/generated/cargo-fix.html b/src/doc/man/generated/cargo-fix.html index f068264e619..0bd6629729a 100644 --- a/src/doc/man/generated/cargo-fix.html +++ b/src/doc/man/generated/cargo-fix.html @@ -34,20 +34,25 @@

DESCRIPTION

-

which behaves the same as cargo check --all-targets. Similarly if you’d like -to fix code for different platforms you can do:

+

which behaves the same as cargo check --all-targets.

+
+
+

cargo fix is only capable of fixing code that is normally compiled with +cargo check. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed:

-
cargo fix --edition --target x86_64-pc-windows-gnu
+
cargo fix --edition --features foo
-

or if your crate has optional features:

+

Similarly, other cfg expressions like platform-specific code will need to +pass --target to fix code for the given target.

-
cargo fix --edition --no-default-features --features foo
+
cargo fix --edition --target x86_64-pc-windows-gnu
diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index b228671f555..372cfbc334e 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -2,12 +2,12 @@ .\" Title: cargo-fix .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 +.\" Date: 2019-12-19 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-FIX" "1" "2019-09-05" "\ \&" "\ \&" +.TH "CARGO\-FIX" "1" "2019-12-19" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -53,20 +53,24 @@ cargo fix \-\-edition .fi .if n .RE .sp -which behaves the same as \fBcargo check \-\-all\-targets\fP. Similarly if you\(cqd like -to fix code for different platforms you can do: +which behaves the same as \fBcargo check \-\-all\-targets\fP. +.sp +\fBcargo fix\fP is only capable of fixing code that is normally compiled with +\fBcargo check\fP. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed: .sp .if n .RS 4 .nf -cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu +cargo fix \-\-edition \-\-features foo .fi .if n .RE .sp -or if your crate has optional features: +Similarly, other \fBcfg\fP expressions like platform\-specific code will need to +pass \fB\-\-target\fP to fix code for the given target. .sp .if n .RS 4 .nf -cargo fix \-\-edition \-\-no\-default\-features \-\-features foo +cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu .fi .if n .RE .sp From 765c80da03cdd69880f58e88c9953023b06c1100 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 10:25:32 -0800 Subject: [PATCH 11/28] Describe dep-info files a little better. --- src/doc/src/guide/build-cache.md | 15 +++++++++++++++ src/doc/src/reference/config.md | 12 ++++-------- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md index 0c455b2ae53..f96721c410a 100644 --- a/src/doc/src/guide/build-cache.md +++ b/src/doc/src/guide/build-cache.md @@ -49,6 +49,20 @@ Directory | Description target/debug/incremental/ |  `rustc` [incremental output], a cache used to speed up subsequent builds. target/debug/build/ |  Output from [build scripts]. +### Dep-info files + +Next to each compiled artifact is a file called a "dep info" file with a `.d` +suffix. This file is a Makefile-like syntax that indicates all of the file +dependencies required to rebuild the artifact. These are intended to be used +with external build systems so that they can detect if Cargo needs to be +re-executed. The paths in the file are absolute by default. See the +[`build.dep-info-basedir`] config option to use relative paths. + +```Makefile +# Example dep-info file found in target/debug/foo.d +/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs +``` + ### Shared cache A third party tool, [sccache], can be used to share built dependencies across @@ -60,6 +74,7 @@ you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to `.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo configuration][config]. Refer to sccache documentation for more details. +[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir [`build.target-dir`]: ../reference/config.md#buildtarget-dir [`cargo doc`]: ../commands/cargo-doc.md [`cargo package`]: ../commands/cargo-package.md diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index e580e9158b5..f2369c38619 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -348,14 +348,10 @@ overrides the config setting. * Default: none * Environment: `CARGO_BUILD_DEP_INFO_BASEDIR` -Strips the given path prefix from dep info file paths. - -Cargo saves a "dep info" file with a `.d` suffix which is a Makefile-like -syntax that indicates all of the file dependencies required to rebuild the -artifact. These are intended to be used with external build systems so that -they can detect if Cargo needs to be re-executed. The paths in the file are -absolute by default. This config setting can be set to strip the given prefix -from all of the paths for tools that require relative paths. +Strips the given path prefix from [dep +info](../guide/build-cache.md#dep-info-files) file paths. This config setting +is intended to convert absolute paths to relative paths for tools that require +relative paths. The setting itself is a config-relative path. So, for example, a value of `"."` would strip all paths starting with the parent directory of the `.cargo` From c4033d327fff46b0b8fdd0834f4c0727eecd74db Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 10:30:27 -0800 Subject: [PATCH 12/28] Mention `cargo metadata` for custom subcommands. --- src/doc/src/reference/external-tools.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/doc/src/reference/external-tools.md b/src/doc/src/reference/external-tools.md index 5611b3f9658..9aaf85dc8b3 100644 --- a/src/doc/src/reference/external-tools.md +++ b/src/doc/src/reference/external-tools.md @@ -241,5 +241,11 @@ Cargo. Alternatively, it can link to `cargo` crate as a library, but this approach has drawbacks: * Cargo as a library is unstable: the API may change without deprecation - * versions of the linked Cargo library may be different from the Cargo binary + +Instead, it is encouraged to use the CLI interface to drive Cargo. The [`cargo +metadata`] command can be used to obtain information about the current project +(the [`cargo_metadata`] crate provides a Rust interface to this command). + +[`cargo metadata`]: ../commands/cargo-metadata.md +[`cargo_metadata`]: https://crates.io/crates/cargo_metadata From 14f7a91354e860768e01b0349119c5482ebaba43 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 11:45:04 -0800 Subject: [PATCH 13/28] Build script change detection: link to include/exclude --- src/doc/src/reference/build-scripts.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index 4800e229cc7..867823faba7 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -240,11 +240,14 @@ cross-compiling, so keep that in consideration of the impact on compile time. When rebuilding a package, Cargo does not necessarily know if the build script needs to be run again. By default, it takes a conservative approach of always -re-running the build script if any file within the package is changed. For -most cases, this is not a good choice, so it is recommended that every build -script emit at least one of the `rerun-if` instructions (described below). If -these are emitted, then Cargo will only re-run the script if the given value -has changed. +re-running the build script if any file within the package is changed (or the +list of files controlled by the [`exclude` and `include` fields]). For most +cases, this is not a good choice, so it is recommended that every build script +emit at least one of the `rerun-if` instructions (described below). If these +are emitted, then Cargo will only re-run the script if the given value has +changed. + +[`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields #### `cargo:rerun-if-changed=PATH` From 82bcbdefbc93f9f898e22b956df7ee14b1f4d0fb Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 13:24:13 -0800 Subject: [PATCH 14/28] Break up the Platform specific dependencies section. --- src/doc/src/reference/specifying-dependencies.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index 5188cc102dd..e43b1d808f6 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -481,7 +481,6 @@ Cargo how to find local unpublished crates. ### Platform specific dependencies - Platform-specific dependencies take the same format, but are listed under a `target` section. Normally Rust-like [`#[cfg]` syntax](../../reference/conditional-compilation.html) will be used to define @@ -531,6 +530,8 @@ winhttp = "0.4.0" openssl = "1.0.1" ``` +#### Custom target specifications + If you’re using a custom target specification (such as `--target foo/bar.json`), use the base filename without the `.json` extension: @@ -543,6 +544,8 @@ openssl = "1.0.1" native = { path = "native/i686" } ``` +> **Note**: Custom target specifications are not usable on the stable channel. + ### Development dependencies You can add a `[dev-dependencies]` section to your `Cargo.toml` whose format From 18e02dad286c492350985d64a7a735973b7fda97 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 13:26:14 -0800 Subject: [PATCH 15/28] Show example for 'cfg(feature="foo")' dependency alternative. --- .../src/reference/specifying-dependencies.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index e43b1d808f6..9521379390e 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -508,11 +508,19 @@ If you want to know which cfg targets are available on your platform, run targets are available for another platform, such as 64-bit Windows, run `rustc --print=cfg --target=x86_64-pc-windows-msvc`. -Unlike in your Rust source code, -you cannot use `[target.'cfg(feature = "my_crate")'.dependencies]` to add -dependencies based on optional crate features. -Use [the `[features]` section](manifest.md#the-features-section) -instead. +Unlike in your Rust source code, you cannot use +`[target.'cfg(feature = "fancy-feature")'.dependencies]` to add dependencies +based on optional features. Use [the `[features]` +section](manifest.md#the-features-section) instead: + +```toml +[dependencies] +foo = { version = "1.0", optional = true } +bar = { version = "1.0", optional = true } + +[features] +fancy-feature = ["foo", "bar"] +``` The same applies to `cfg(debug_assertions)`, `cfg(test)` and `cfg(prog_macro)`. These values will not work as expected and will always have the default value From caf88f5ceacbfb08338b1ba0796f5c5aedc90c95 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 13:33:13 -0800 Subject: [PATCH 16/28] Try to make it a little clearer that cargo package/publish will rebuild from scratch. Closes #3062 --- src/doc/man/cargo-package.adoc | 3 +++ src/doc/man/generated/cargo-package.html | 9 +++++++++ src/etc/man/cargo-package.1 | 17 +++++++++++++++-- 3 files changed, 27 insertions(+), 2 deletions(-) diff --git a/src/doc/man/cargo-package.adoc b/src/doc/man/cargo-package.adoc index 788f55f9b0d..ba1c1b5d69a 100644 --- a/src/doc/man/cargo-package.adoc +++ b/src/doc/man/cargo-package.adoc @@ -33,6 +33,9 @@ steps: about the current VCS checkout hash if available (not included with `--allow-dirty`). . 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 + this step. . Check that build scripts did not modify any source files. The list of files included can be controlled with the `include` and `exclude` diff --git a/src/doc/man/generated/cargo-package.html b/src/doc/man/generated/cargo-package.html index 20a023483e2..42bca1aee71 100644 --- a/src/doc/man/generated/cargo-package.html +++ b/src/doc/man/generated/cargo-package.html @@ -59,6 +59,15 @@

DESCRIPTION

  • 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 +this step.

      +
      • +
    +

  • Check that build scripts did not modify any source files.

    diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index 7d34613271e..95012e9b480 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -2,12 +2,12 @@ .\" Title: cargo-package .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-11-21 +.\" Date: 2019-12-19 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-PACKAGE" "1" "2019-11-21" "\ \&" "\ \&" +.TH "CARGO\-PACKAGE" "1" "2019-12-19" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -132,6 +132,19 @@ about the current VCS checkout hash if available (not included with . IP " 3." 4.2 .\} Extract the \fB.crate\fP file and build it to verify it can build. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +This will rebuild your package from scratch to ensure that it can be +built from a pristine state. The \fB\-\-no\-verify\fP flag can be used to skip +this step. +.RE .RE .sp .RS 4 From 47a46ae77a618c6d61fdfa16fcfd7abe375d1990 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 13:57:27 -0800 Subject: [PATCH 17/28] Try to be clearer about how `--target` is different. Closes #3817 --- src/doc/man/generated/cargo-bench.html | 5 +++++ src/doc/man/generated/cargo-build.html | 5 +++++ src/doc/man/generated/cargo-check.html | 5 +++++ src/doc/man/generated/cargo-clean.html | 5 +++++ src/doc/man/generated/cargo-doc.html | 5 +++++ src/doc/man/generated/cargo-fetch.html | 5 +++++ src/doc/man/generated/cargo-fix.html | 5 +++++ src/doc/man/generated/cargo-install.html | 5 +++++ src/doc/man/generated/cargo-package.html | 5 +++++ src/doc/man/generated/cargo-publish.html | 5 +++++ src/doc/man/generated/cargo-run.html | 5 +++++ src/doc/man/generated/cargo-rustc.html | 5 +++++ src/doc/man/generated/cargo-rustdoc.html | 5 +++++ src/doc/man/generated/cargo-test.html | 5 +++++ src/doc/man/options-target-triple.adoc | 4 ++++ src/doc/src/guide/build-cache.md | 20 ++++++++++++++------ src/etc/man/cargo-bench.1 | 5 +++++ src/etc/man/cargo-build.1 | 5 +++++ src/etc/man/cargo-check.1 | 5 +++++ src/etc/man/cargo-clean.1 | 5 +++++ src/etc/man/cargo-doc.1 | 5 +++++ src/etc/man/cargo-fetch.1 | 9 +++++++-- src/etc/man/cargo-fix.1 | 5 +++++ src/etc/man/cargo-install.1 | 5 +++++ src/etc/man/cargo-package.1 | 5 +++++ src/etc/man/cargo-publish.1 | 5 +++++ src/etc/man/cargo-run.1 | 5 +++++ src/etc/man/cargo-rustc.1 | 9 +++++++-- src/etc/man/cargo-rustdoc.1 | 9 +++++++-- src/etc/man/cargo-test.1 | 5 +++++ 30 files changed, 164 insertions(+), 12 deletions(-) diff --git a/src/doc/man/generated/cargo-bench.html b/src/doc/man/generated/cargo-bench.html index c6355b5244a..c25ebe82798 100644 --- a/src/doc/man/generated/cargo-bench.html +++ b/src/doc/man/generated/cargo-bench.html @@ -242,6 +242,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    • +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    diff --git a/src/doc/man/generated/cargo-build.html b/src/doc/man/generated/cargo-build.html index 5c4e19387c6..4ea50b0acc1 100644 --- a/src/doc/man/generated/cargo-build.html +++ b/src/doc/man/generated/cargo-build.html @@ -171,6 +171,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/generated/cargo-check.html b/src/doc/man/generated/cargo-check.html index fe7f7c8295f..5efbc7333d1 100644 --- a/src/doc/man/generated/cargo-check.html +++ b/src/doc/man/generated/cargo-check.html @@ -175,6 +175,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/generated/cargo-clean.html b/src/doc/man/generated/cargo-clean.html index 0c2e2fc73ed..f0d51b48be7 100644 --- a/src/doc/man/generated/cargo-clean.html +++ b/src/doc/man/generated/cargo-clean.html @@ -73,6 +73,11 @@

    Clean Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    diff --git a/src/doc/man/generated/cargo-doc.html b/src/doc/man/generated/cargo-doc.html index 643392e938a..7d9a0f591c7 100644 --- a/src/doc/man/generated/cargo-doc.html +++ b/src/doc/man/generated/cargo-doc.html @@ -153,6 +153,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/generated/cargo-fetch.html b/src/doc/man/generated/cargo-fetch.html index 346d566a14e..64c1e05efc7 100644 --- a/src/doc/man/generated/cargo-fetch.html +++ b/src/doc/man/generated/cargo-fetch.html @@ -50,6 +50,11 @@

    Fetch options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    diff --git a/src/doc/man/generated/cargo-fix.html b/src/doc/man/generated/cargo-fix.html index 0bd6629729a..ad35f4bb4ef 100644 --- a/src/doc/man/generated/cargo-fix.html +++ b/src/doc/man/generated/cargo-fix.html @@ -251,6 +251,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/generated/cargo-install.html b/src/doc/man/generated/cargo-install.html index bd18bb94aa3..b9a44dcc8e2 100644 --- a/src/doc/man/generated/cargo-install.html +++ b/src/doc/man/generated/cargo-install.html @@ -241,6 +241,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --debug
    diff --git a/src/doc/man/generated/cargo-package.html b/src/doc/man/generated/cargo-package.html index 42bca1aee71..d308037e6fb 100644 --- a/src/doc/man/generated/cargo-package.html +++ b/src/doc/man/generated/cargo-package.html @@ -126,6 +126,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --target-dir DIRECTORY
    diff --git a/src/doc/man/generated/cargo-publish.html b/src/doc/man/generated/cargo-publish.html index 6f79f51debf..ba0e151490a 100644 --- a/src/doc/man/generated/cargo-publish.html +++ b/src/doc/man/generated/cargo-publish.html @@ -110,6 +110,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --target-dir DIRECTORY
    diff --git a/src/doc/man/generated/cargo-run.html b/src/doc/man/generated/cargo-run.html index 538be3555a1..b0580adbcc9 100644 --- a/src/doc/man/generated/cargo-run.html +++ b/src/doc/man/generated/cargo-run.html @@ -105,6 +105,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/generated/cargo-rustc.html b/src/doc/man/generated/cargo-rustc.html index 5642a4aa642..b2488f62f06 100644 --- a/src/doc/man/generated/cargo-rustc.html +++ b/src/doc/man/generated/cargo-rustc.html @@ -166,6 +166,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/generated/cargo-rustdoc.html b/src/doc/man/generated/cargo-rustdoc.html index c8c73a2fd6c..e95c9591072 100644 --- a/src/doc/man/generated/cargo-rustdoc.html +++ b/src/doc/man/generated/cargo-rustdoc.html @@ -181,6 +181,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/generated/cargo-test.html b/src/doc/man/generated/cargo-test.html index fe8f0679bae..2bf94d7ac60 100644 --- a/src/doc/man/generated/cargo-test.html +++ b/src/doc/man/generated/cargo-test.html @@ -262,6 +262,11 @@

    Compilation Options

    This may also be specified with the build.target config value.

    +
    +

    Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

    +
    --release
    diff --git a/src/doc/man/options-target-triple.adoc b/src/doc/man/options-target-triple.adoc index eac97d88505..9cb6d7c85e5 100644 --- a/src/doc/man/options-target-triple.adoc +++ b/src/doc/man/options-target-triple.adoc @@ -6,3 +6,7 @@ + This may also be specified with the `build.target` linkcargo:reference/config.html[config value]. ++ +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +linkcargo:guide/build-cache.html[build cache] documentation for more details. diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md index f96721c410a..f1722932574 100644 --- a/src/doc/src/guide/build-cache.md +++ b/src/doc/src/guide/build-cache.md @@ -5,24 +5,31 @@ this is the directory named `target` in the root of your workspace. To change the location, you can set the `CARGO_TARGET_DIR` [environment variable], the [`build.target-dir`] config value, or the `--target-dir` command-line flag. -The directory layout depends on whether or not you are cross-compiling for a -different platform with the `--target` flag. When not cross-compiling, the -output goes into the root of the target directory, separated based on whether -or not it is a release build: +The directory layout depends on whether or not you are using the `--target` +flag to build for a specific platform. If `--target` is not specified, Cargo +runs in a mode where it builds for the host architecture. The output goes into +the root of the target directory, separated based on whether or not it is a +release build: Directory | Description ----------|------------ target/debug/ | Contains debug build output. target/release/ | Contains release build output (with `--release` flag). -When building for another target, the output is placed in a directory with the -name of the target: +When building for another target with `--target`, the output is placed in a +directory with the name of the target: Directory | Example ----------|-------- target/<triple>/debug/ | target/thumbv7em-none-eabihf/debug/ target/<triple>/release/ | target/thumbv7em-none-eabihf/release/ +> **Note**: When not using `--target`, this has a consequence that Cargo will +> share your dependencies with build scripts and proc macros. [`RUSTFLAGS`] +> will be shared with every `rustc` invocation. With the `--target` flag, +> build scripts and proc macros are built separately (for the host +> architecture), and do not share `RUSTFLAGS`. + Within the profile directory (`debug` or `release`), artifacts are placed into the following directories: @@ -74,6 +81,7 @@ you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to `.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo configuration][config]. Refer to sccache documentation for more details. +[`RUSTFLAGS`]: ../reference/config.md#buildrustflags [`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir [`build.target-dir`]: ../reference/config.md#buildtarget-dir [`cargo doc`]: ../commands/cargo-doc.md diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 7321c1753c1..3d4bdc35792 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -276,6 +276,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .SS "Output Options" .sp diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index 3e5603a1cb7..17ed8d17913 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -176,6 +176,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index 12820a53697..8513a156584 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -180,6 +180,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP diff --git a/src/etc/man/cargo-clean.1 b/src/etc/man/cargo-clean.1 index cf52542a7a7..7ad930ab1c7 100644 --- a/src/etc/man/cargo-clean.1 +++ b/src/etc/man/cargo-clean.1 @@ -82,6 +82,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index fccfe8bfc7d..60c9d825236 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -148,6 +148,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP diff --git a/src/etc/man/cargo-fetch.1 b/src/etc/man/cargo-fetch.1 index 6bada865551..1442fa02eb6 100644 --- a/src/etc/man/cargo-fetch.1 +++ b/src/etc/man/cargo-fetch.1 @@ -2,12 +2,12 @@ .\" Title: cargo-fetch .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 +.\" Date: 2019-11-11 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-FETCH" "1" "2019-09-05" "\ \&" "\ \&" +.TH "CARGO\-FETCH" "1" "2019-11-11" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -60,6 +60,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .SS "Display Options" .sp diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index 372cfbc334e..e86d48079d0 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -254,6 +254,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 6ab8bc36937..c733b4edf03 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -327,6 +327,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-debug\fP diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index 95012e9b480..f85d664355b 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -199,6 +199,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-target\-dir\fP \fIDIRECTORY\fP diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index 52f309bf82a..fe060251c5e 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -149,6 +149,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-target\-dir\fP \fIDIRECTORY\fP diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 56c8074d89d..d49aa0e9573 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -100,6 +100,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index 018d64bf21e..199dba235ac 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -2,12 +2,12 @@ .\" Title: cargo-rustc .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-12-18 +.\" Date: 2019-12-19 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-RUSTC" "1" "2019-12-18" "\ \&" "\ \&" +.TH "CARGO\-RUSTC" "1" "2019-12-19" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -171,6 +171,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 3ee72e244ca..3125cd1abbd 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -2,12 +2,12 @@ .\" Title: cargo-rustdoc .\" Author: [see the "AUTHOR(S)" section] .\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-12-18 +.\" Date: 2019-12-19 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "CARGO\-RUSTDOC" "1" "2019-12-18" "\ \&" "\ \&" +.TH "CARGO\-RUSTDOC" "1" "2019-12-19" "\ \&" "\ \&" .ie \n(.g .ds Aq \(aq .el .ds Aq ' .ss \n[.ss] 0 @@ -181,6 +181,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 94aecf61650..5b1b0b94cc3 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -312,6 +312,11 @@ list of supported targets. .sp This may also be specified with the \fBbuild.target\fP .URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " +documentation for more details. .RE .sp \fB\-\-release\fP From e958fe630d3344fe4b18c1d1555412cb934503e1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 14:17:14 -0800 Subject: [PATCH 18/28] Clarify that [replace] requires a version number. Closes #4212 --- src/doc/src/reference/manifest.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index e729ccb1d27..74e08bb27b5 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -1000,11 +1000,11 @@ other copies. The syntax is similar to the `[dependencies]` section: Each key in the `[replace]` table is a [package ID specification](pkgid-spec.md), which allows arbitrarily choosing a node in the -dependency graph to override. The value of each key is the same as the -`[dependencies]` syntax for specifying dependencies, except that you can't -specify features. Note that when a crate is overridden the copy it's overridden -with must have both the same name and version, but it can come from a different -source (e.g., git or a local path). +dependency graph to override (the 3-part version number is required). The +value of each key is the same as the `[dependencies]` syntax for specifying +dependencies, except that you can't specify features. Note that when a crate +is overridden the copy it's overridden with must have both the same name and +version, but it can come from a different source (e.g., git or a local path). More information about overriding dependencies can be found in the [overriding dependencies][replace] section of the documentation. From 018b5f5923952ab60dd21048d957d1e8fbedac23 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 14:21:44 -0800 Subject: [PATCH 19/28] Document that [replace] should not be used. cc #7092 --- src/doc/src/reference/manifest.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 74e08bb27b5..775739389a0 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -989,6 +989,9 @@ crates. ### The `[replace]` Section +> **Note**: `[replace]` is deprecated. You should use the [`[patch]`][patch] +> table instead. + This section of Cargo.toml can be used to [override dependencies][replace] with other copies. The syntax is similar to the `[dependencies]` section: @@ -1021,3 +1024,4 @@ dependencies][replace] section of the documentation. [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 [spdx-license-list-3.6]: https://github.com/spdx/license-list-data/tree/v3.6 [SPDX site]: https://spdx.org/license-list +[patch]: #the-patch-section From e5bc8cc6e4a099f95d91fed8d3beb9504a64dafd Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Thu, 19 Dec 2019 18:20:14 -0800 Subject: [PATCH 20/28] Try to clarify dev/test profile selection. Closes #4438 --- src/doc/src/images/profile-selection.svg | 3 +++ src/doc/src/reference/profiles.md | 3 +++ 2 files changed, 6 insertions(+) create mode 100644 src/doc/src/images/profile-selection.svg diff --git a/src/doc/src/images/profile-selection.svg b/src/doc/src/images/profile-selection.svg new file mode 100644 index 00000000000..4975383bf76 --- /dev/null +++ b/src/doc/src/images/profile-selection.svg @@ -0,0 +1,3 @@ + + +
    lib
    profile: dev
    lib<br>profile: dev
    lib (unit test)
    profile: test
    [Not supported by viewer]
    dependency1
    profile: dev
    [Not supported by viewer]
    integration test
    profile: test
    [Not supported by viewer]
    bin (unit test)
    profile: test
    [Not supported by viewer]
    bin (executable)
    profile: dev
    bin (executable)<br>profile: dev
    dependency2
    profile: dev
    [Not supported by viewer]
    dependency3
    profile: dev
    [Not supported by viewer]
    Executables
    [Not supported by viewer]
    Profile selection for cargo test
    Profile selection for <font face="Courier New">cargo test</font>     \ No newline at end of file diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md index 88f01800b64..818bd59b3fa 100644 --- a/src/doc/src/reference/profiles.md +++ b/src/doc/src/reference/profiles.md @@ -304,6 +304,9 @@ profile. However, when building an integration test target, the library target is built with the `dev` profile and linked into the integration test executable. +![Profile selection for cargo test](../images/profile-selection.svg) + + [`cargo bench`]: ../commands/cargo-bench.md [`cargo build`]: ../commands/cargo-build.md [`cargo check`]: ../commands/cargo-check.md From 0a5f54b5dc4d17a218042ba70da3d3c427d705f0 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Dec 2019 09:55:06 -0800 Subject: [PATCH 21/28] Don't describe the package layout twice. --- src/doc/src/appendix/glossary.md | 2 +- src/doc/src/guide/project-layout.md | 58 ++++++++++++++++++-------- src/doc/src/reference/manifest.md | 64 ++++++++--------------------- 3 files changed, 58 insertions(+), 66 deletions(-) diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md index fec93a83ccf..f87ab45a3c3 100644 --- a/src/doc/src/appendix/glossary.md +++ b/src/doc/src/appendix/glossary.md @@ -178,7 +178,7 @@ manifest is located. [Source Replacement]: ../reference/source-replacement.md [cargo-unstable]: ../reference/unstable.md [config option]: ../reference/config.md -[directory layout]: ../reference/manifest.md#the-project-layout +[directory layout]: ../guide/project-layout.md [edition guide]: ../../edition-guide/index.html [edition-field]: ../reference/manifest.md#the-edition-field [environment variable]: ../reference/environment-variables.md diff --git a/src/doc/src/guide/project-layout.md b/src/doc/src/guide/project-layout.md index 6c9f4a7719c..7e1566f6b50 100644 --- a/src/doc/src/guide/project-layout.md +++ b/src/doc/src/guide/project-layout.md @@ -3,21 +3,34 @@ Cargo uses conventions for file placement to make it easy to dive into a new Cargo package: -``` +```text . ├── Cargo.lock ├── Cargo.toml -├── benches -│   └── large-input.rs -├── examples -│   └── simple.rs -├── src -│   ├── bin -│   │   └── another_executable.rs +├── src/ │   ├── lib.rs -│   └── main.rs -└── tests - └── some-integration-tests.rs +│   ├── main.rs +│   └── bin/ +│ ├── named-executable.rs +│      ├── another-executable.rs +│      └── multi-file-executable/ +│      ├── main.rs +│      └── some_module.rs +├── benches/ +│   ├── large-input.rs +│   └── multi-file-bench/ +│   ├── main.rs +│   └── bench_module.rs +├── examples/ +│   ├── simple.rs +│   └── multi-file-example/ +│   ├── main.rs +│   └── ex_module.rs +└── tests/ + ├── some-integration-tests.rs + └── multi-file-test/ + ├── main.rs + └── test_module.rs ``` * `Cargo.toml` and `Cargo.lock` are stored in the root of your package (*package @@ -25,11 +38,22 @@ Cargo package: * Source code goes in the `src` directory. * The default library file is `src/lib.rs`. * The default executable file is `src/main.rs`. -* Other executables can be placed in `src/bin/*.rs`. -* Integration tests go in the `tests` directory (unit tests go in each file - they're testing). -* Examples go in the `examples` directory. + * Other executables can be placed in `src/bin/`. * Benchmarks go in the `benches` directory. +* Examples go in the `examples` directory. +* Integration tests go in the `tests` directory. + +If a binary, example, bench, or integration test consists of multiple source +files, place a `main.rs` file along with the extra modules within a +subdirectory of the `src/bin`, `examples`, `benches`, or `tests` directory. +The name of the executable will be the directory name. + +You can learn more about Rust's module system in [the book][book-modules]. + +See [Configuring a target] for more details on manually configuring targets. +See [Target auto-discovery] for more information on controlling how Cargo +automatically infers target names. -These are explained in more detail in the [manifest -description](../reference/manifest.md#the-project-layout). +[book-modules]: ../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html +[Configuring a target]: ../reference/manifest.md#configuring-a-target +[Target auto-discovery]: ../reference/manifest.md#target-auto-discovery diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 775739389a0..a30558d57a2 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -679,53 +679,6 @@ When `default-members` is not specified, the default is the root manifest if it is a package, or every member manifest (as if `--workspace` were specified on the command-line) for virtual workspaces. -### The project layout - -If your package is an executable, name the main source file `src/main.rs`. If it -is a library, name the main source file `src/lib.rs`. - -Cargo will also treat any files located in `src/bin/*.rs` as executables. If your -executable consists of more than just one source file, you might also use a directory -inside `src/bin` containing a `main.rs` file which will be treated as an executable -with a name of the parent directory. - -Your package can optionally contain folders named `examples`, `tests`, and -`benches`, which Cargo will treat as containing examples, -integration tests, and benchmarks respectively. Analogous to `bin` targets, they -may be composed of single files or directories with a `main.rs` file. - -``` -▾ src/ # directory containing source files - lib.rs # the main entry point for libraries and packages - main.rs # the main entry point for packages producing executables - ▾ bin/ # (optional) directory containing additional executables - *.rs - ▾ */ # (optional) directories containing multi-file executables - main.rs -▾ examples/ # (optional) examples - *.rs - ▾ */ # (optional) directories containing multi-file examples - main.rs -▾ tests/ # (optional) integration tests - *.rs - ▾ */ # (optional) directories containing multi-file tests - main.rs -▾ benches/ # (optional) benchmarks - *.rs - ▾ */ # (optional) directories containing multi-file benchmarks - main.rs -``` - -To structure your code after you've created the files and folders for your -package, you should remember to use Rust's module system, which you can read -about in [the -book](../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html). - -See [Configuring a target](#configuring-a-target) below for more details on -manually configuring target settings. See [Target -auto-discovery](#target-auto-discovery) below for more information on -controlling how Cargo automatically infers targets. - ### Examples Files located under `examples` are example uses of the functionality provided by @@ -845,7 +798,7 @@ path = "src/my-cool-binary.rs" #### Target auto-discovery By default, Cargo automatically determines the targets to build based on the -[layout of the files](#the-project-layout) on the filesystem. The target +[layout of the files][package-layout] on the filesystem. The target configuration tables, such as `[lib]`, `[[bin]]`, `[[test]]`, `[[bench]]`, or `[[example]]`, can be used to add additional targets that don't follow the standard directory layout. @@ -1024,4 +977,19 @@ dependencies][replace] section of the documentation. [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 [spdx-license-list-3.6]: https://github.com/spdx/license-list-data/tree/v3.6 [SPDX site]: https://spdx.org/license-list +[package-layout]: ../guide/project-layout.md [patch]: #the-patch-section + + From 0f99322f937f7e259d0095f041cdfb96b69a6307 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Fri, 20 Dec 2019 16:13:42 -0800 Subject: [PATCH 22/28] Move cargo targets to a new chapter. Closes #6913. --- src/doc/src/SUMMARY.md | 1 + src/doc/src/appendix/glossary.md | 4 +- src/doc/src/guide/project-layout.md | 4 +- src/doc/src/reference/cargo-targets.md | 368 +++++++++++++++++++++++++ src/doc/src/reference/index.md | 1 + src/doc/src/reference/manifest.md | 203 +------------- 6 files changed, 381 insertions(+), 200 deletions(-) create mode 100644 src/doc/src/reference/cargo-targets.md diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index 8a1ca888bc7..9cb3d16d74b 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -21,6 +21,7 @@ * [Cargo Reference](reference/index.md) * [Specifying Dependencies](reference/specifying-dependencies.md) * [The Manifest Format](reference/manifest.md) + * [Cargo Targets](reference/cargo-targets.md) * [Profiles](reference/profiles.md) * [Configuration](reference/config.md) * [Environment Variables](reference/environment-variables.md) diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md index f87ab45a3c3..6152312a65b 100644 --- a/src/doc/src/appendix/glossary.md +++ b/src/doc/src/appendix/glossary.md @@ -185,14 +185,14 @@ manifest is located. [feature]: ../reference/manifest.md#the-features-section [git dependency]: ../reference/specifying-dependencies.md#specifying-dependencies-from-git-repositories [git source]: ../reference/source-replacement.md -[integration-tests]: ../reference/manifest.md#integration-tests +[integration-tests]: ../reference/cargo-targets.md#integration-tests [manifest]: ../reference/manifest.md [path dependency]: ../reference/specifying-dependencies.md#specifying-path-dependencies [path overrides]: ../reference/specifying-dependencies.md#overriding-with-local-dependencies [pkgid-spec]: ../reference/pkgid-spec.md [rustdoc-unstable]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html [target-feature]: ../../reference/attributes/codegen.html#the-target_feature-attribute -[targets]: ../reference/manifest.md#configuring-a-target +[targets]: ../reference/cargo-targets.md#configuring-a-target [unstable-book]: https://doc.rust-lang.org/nightly/unstable-book/index.html [virtual]: ../reference/manifest.md#virtual-manifest [workspace]: ../reference/manifest.md#the-workspace-section diff --git a/src/doc/src/guide/project-layout.md b/src/doc/src/guide/project-layout.md index 7e1566f6b50..4869924c688 100644 --- a/src/doc/src/guide/project-layout.md +++ b/src/doc/src/guide/project-layout.md @@ -55,5 +55,5 @@ See [Target auto-discovery] for more information on controlling how Cargo automatically infers target names. [book-modules]: ../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html -[Configuring a target]: ../reference/manifest.md#configuring-a-target -[Target auto-discovery]: ../reference/manifest.md#target-auto-discovery +[Configuring a target]: ../reference/cargo-targets.md#configuring-a-target +[Target auto-discovery]: ../reference/cargo-targets.md#target-auto-discovery diff --git a/src/doc/src/reference/cargo-targets.md b/src/doc/src/reference/cargo-targets.md new file mode 100644 index 00000000000..e3eb7cc550d --- /dev/null +++ b/src/doc/src/reference/cargo-targets.md @@ -0,0 +1,368 @@ +## Cargo Targets + +Cargo packages consist of *targets* which correspond to source files which can +be compiled into a crate. Packages can have [library](#library), +[binary](#binaries), [example](#examples), [test](#tests), and +[benchmark](#benchmarks) targets. The list of targets can be configured in the +`Cargo.toml` manifest, often [inferred automatically](#target-auto-discovery) +by the [directory layout][package layout] of the source files. + +See [Configuring a target](#configuring-a-target) below for details on +configuring the settings for a target. + +### Library + +The library target defines a "library" that can be used and linked by other +libraries and executables. The filename defaults to `src/lib.rs`, and the name +of the library defaults to the name of the package. A package can have only +one library. The settings for the library can be [customized] in the `[lib]` +table in `Cargo.toml`. + +```toml +# Example of customizing the library in Cargo.toml. +[lib] +crate-type = ["cdylib"] +bench = false +``` + +### Binaries + +Binary targets are executables programs that can be run after being compiled. +The default binary filename is `src/main.rs`, which defaults to the name of +the package. Additional binaries are stored in the [`src/bin/` +directory][package layout]. The settings for each binary can be [customized] +in the `[[bin]]` tables in `Cargo.toml`. + +Binaries can use the public API of the package's library. They are also linked +with the [`[dependencies]`][dependencies] defined in `Cargo.toml`. + +You can run individual binaries with the [`cargo run`] command with the `--bin +` option. [`cargo install`] can be used to copy the executable to a +common location. + +```toml +# Example of customizing binaries in Cargo.toml. +[[bin]] +name = "cool-tool" +test = false +bench = false + +[[bin]] +name = "frobnicator" +required-features = ["frobnicate"] +``` + +### Examples + +Files located under the [`examples` directory][package layout] are example +uses of the functionality provided by the library. When compiled, they are +placed in the [`target/debug/examples` directory][build cache]. + +Examples can use the public API of the package's library. They are also linked +with the [`[dependencies]`][dependencies] and +[`[dev-dependencies]`][dev-dependencies] defined in `Cargo.toml`. + +By default, examples are executable binaries (with a `main()` function). You +can specify the [`crate-type` field](#the-crate-type-field) to make an example +be compiled as a library: + +```toml +[[example]] +name = "foo" +crate-type = ["staticlib"] +``` + +You can run individual executable examples with the [`cargo run`] command with +the `--example ` option. Library examples can be built with +[`cargo build`] with the `--example ` option. [`cargo install`] +with the `--example ` option can be used to copy executable +binaries to a common location. Examples are compiled by [`cargo test`] by +default to protect them from bit-rotting. Set [the `test` +field](#the-test-field) to `true` if you have `#[test]` functions in the +example that you want to run with [`cargo test`]. + +### Tests + +There are two styles of tests within a Cargo project: + +* *Unit tests* which are functions marked with the [`#[test]` + attribute][test-attribute] located within your library or binaries (or any + target enabled with [the `test` field](#the-test-field)). These tests have + access to private APIs located within the target they are defined in. +* *Integration tests* which is a separate executable binary, also containing + `#[test]` functions, which is linked with the project's library and has + access to its *public* API. + +Tests are run with the [`cargo test`] command. By default, Cargo and `rustc` +use the libtest harness which is responsible for collecting functions +annotated with the [`#[test]` attribute][test-attribute] and executing them in +parallel, reporting the success and failure of each test. See [the `harness` +field](#the-harness-field) if you want to use a different harness or test +strategy. + +#### Integration tests + +Files located under the [`tests` directory][package layout] are integration +tests. When you run [`cargo test`], Cargo will compile each of these files as +a separate crate, and execute them. + +Integration tests can use the public API of the package's library. They are +also linked with the [`[dependencies]`][dependencies] and +[`[dev-dependencies]`][dev-dependencies] defined in `Cargo.toml`. + +If you want to share code among multiple integration tests, you can place it +in a separate module such as `tests/common/mod.rs` and then put `mod common;` +in each test to import it. + +Each integration test results in a separate executable binary, and [`cargo +test`] will run them serially. In some cases this can be inefficient, as it +can take longer to compile, and may not make full use of multiple CPUs when +running the tests. If you have a lot of integration tests, you may want to +consider creating a single integration test, and split the tests into multiple +modules. The libtest harness will automatically find all of the `#[test]` +annotated functions and run them in parallel. You can pass module names to +[`cargo test`] to only run the tests within that module. + +### Benchmarks + +Benchmarks provide a way to test the performance of your code using the +[`cargo bench`] command. They follow the same structure as [tests](#tests), +with each benchmark function annotated with the `#[bench]` attribute. +Similarly to tests: + +* Benchmarks are placed in the [`benches` directory][package layout]. +* Benchmark functions defined in libraries and binaries have access to the + *private* API within the target they are defined in. Benchmarks in the + `benches` directory may use the *public* API. +* [The `bench` field](#the-bench-field) can be used to define which targets + are benchmarked by default. +* [The `harness` field](#the-harness-field) can be used to disable the + built-in harness. + +> **Note**: The [`#[bench]` +> attribute](../../unstable-book/library-features/test.html) is currently +> unstable and only available on the [nightly channel]. There are some +> packages available on [crates.io](https://crates.io/keywords/benchmark) that +> may help with running benchmarks on the stable channel, such as +> [Criterion](https://crates.io/crates/criterion). + +### Configuring a target + +All of the `[lib]`, `[[bin]]`, `[[example]]`, `[[test]]`, and `[[bench]]` +sections in `Cargo.toml` support similar configuration for specifying how a +target should be built. The double-bracket sections like `[[bin]]` are +array-of-table of [TOML](https://github.com/toml-lang/toml#array-of-tables), +which means you can write more than one `[[bin]]` section to make several +executables in your crate. You can only specify one library, so `[lib]` is a +normal TOML table. + +The following is an overview of the TOML settings for each target, with each +field described in detail below. + +```toml +[lib] +name = "foo" # The name of the target. +path = "src/lib.rs" # The source file of the target. +test = true # Is tested by default. +doctest = true # Documentation examples are tested by default. +bench = true # Is benchmarked by default. +doc = true # Is documented by default. +plugin = false # Used as a compiler plugin (deprecated). +proc-macro = false # Set to `true` for a proc-macro library. +harness = true # Use libtest harness. +edition = "2015" # The edition of the target. +crate-type = ["lib"] # The crate types to generate. +required-features = [] # Features required to build this target (N/A for lib). +``` + +#### The `name` field + +The `name` field specifies the name of the target, which corresponds to the +filename of the artifact that will be generated. For a library, this is the +crate name that dependencies will use to reference it. + +For the `[lib]` and the default binary (`src/main.rs`), this defaults to the +name of the package, with any dashes replaced with underscores. For other +[auto discovered](#target-auto-discovery) targets, it defaults to the +directory or file name. + +This is required for all targets except `[lib]`. + +#### The `path` field + +The `path` field specifies where the source for the crate is located, relative +to the `Cargo.toml` file. + +If not specified, the [inferred path](#target-auto-discovery) is used based on +the target name. + +#### The `test` field + +The `test` field indicates whether or not the target is tested by default by +[`cargo test`]. The default is `true` for lib, bins, and tests. + +> **Note**: Examples are built by [`cargo test`] by default to ensure they +> continue to compile, but they are not *tested* by default. Setting `test = +> true` for an example will also build it as a test and run any +> [`#[test]`][test-attribute] functions defined in the example. + +#### The `doctest` field + +The `doctest` field indicates whether or not [documentation examples] are +tested by default by [`cargo test`]. This is only relevant for libraries, it +has no effect on other sections. The default is `true` for the library. + +#### The `bench` field + +The `bench` field indicates whether or not the target is benchmarked by +default by [`cargo bench`]. The default is `true` for lib, bins, and +benchmarks. + +#### The `doc` field + +The `doc` field indicates whether or not the target is included in the +documentation generated by [`cargo doc`] by default. The default is `true` for +libraries and binaries. + +> **Note**: The binary will be skipped if its name is the same as the lib +> target. + +#### The `plugin` field + +This field is used for `rustc` plugins, which are being deprecated. + +#### The `proc-macro` field + +The `proc-macro` field indicates that the library is a [procedural macro] +([reference][proc-macro-reference]). This is only valid for the `[lib]` +target. + +#### The `harness` field + +The `harness` field indicates that the [`--test` flag] will be passed to +`rustc` which will automatically include the libtest library which is the +driver for collecting and running tests marked with the [`#[test]` +attribute][test-attribute] or benchmarks with the `#[bench]` attribute. The +default is `true` for all targets. + +If set to `false`, then you are responsible for defining a `main()` function +to run tests and benchmarks. + +#### The `edition` field + +The `edition` field defines the [Rust edition] the target will use. If not +specified, it defaults to the [`edition` field][package-edition] for the +`[package]`. This field should usually not be set, and is only intended for +advanced scenarios such as incrementally transitioning a large package to a +new edition. + +#### The `crate-type` field + +The `crate-type` field defines the [crate types] that will be generated by the +target. It is an array of strings, allowing you to specify multiple crate +types for a single target. This can only be specified for libraries and +examples. Binaries, tests, and benchmarks are always the "bin" crate type. The +defaults are: + +Target | Crate Type +-------|----------- +Normal library | `"lib"` +Proc-macro library | `"proc-macro"` +Example | `"bin"` + +The available options are `bin`, `lib`, `rlib`, `dylib`, `cdylib`, +`staticlib`, and `proc-macro`. You can read more about the different crate +types in the [Rust Reference Manual][crate types]. + +#### The `required-features` field + +The `required-features` field specifies which [features] the target needs in +order to be built. If any of the required features are not enabled, the +target will be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, +`[[test]]`, and `[[example]]` sections, it has no effect on `[lib]`. + +```toml +[features] +# ... +postgres = [] +sqlite = [] +tools = [] + +[[bin]] +name = "my-pg-tool" +required-features = ["postgres", "tools"] +``` + + +### Target auto-discovery + +By default, Cargo automatically determines the targets to build based on the +[layout of the files][package layout] on the filesystem. The target +configuration tables, such as `[lib]`, `[[bin]]`, `[[test]]`, `[[bench]]`, or +`[[example]]`, can be used to add additional targets that don't follow the +standard directory layout. + +The automatic target discovery can be disabled so that only manually +configured targets will be built. Setting the keys `autobins`, `autoexamples`, +`autotests`, or `autobenches` to `false` in the `[package]` section will +disable auto-discovery of the corresponding target type. + +```toml +[package] +# ... +autobins = false +autoexamples = false +autotests = false +autobenches = false +``` + +Disabling automatic discovery should only be needed for specialized +situations. For example, if you have a library where you want a *module* named +`bin`, this would present a problem because Cargo would usually attempt to +compile anything in the `bin` directory as an executable. Here is a sample +layout of this scenario: + +``` +├── Cargo.toml +└── src +    ├── lib.rs +    └── bin +       └── mod.rs +``` + +To prevent Cargo from inferring `src/bin/mod.rs` as an executable, set +`autobins = false` in `Cargo.toml` to disable auto-discovery: + +```toml +[package] +# … +autobins = false +``` + +> **Note**: For packages with the 2015 edition, the default for auto-discovery +> is `false` if at least one target is manually defined in `Cargo.toml`. +> Beginning with the 2018 edition, the default is always `true`. + + +[Build cache]: ../guide/build-cache.md +[Rust Edition]: ../../edition-guide/index.html +[`--test` flag]: ../../rustc/command-line-arguments.html#option-test +[`cargo bench`]: ../commands/cargo-bench.md +[`cargo build`]: ../commands/cargo-build.md +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo install`]: ../commands/cargo-install.md +[`cargo run`]: ../commands/cargo-run.md +[`cargo test`]: ../commands/cargo-test.md +[crate types]: ../../reference/linkage.html +[crates.io]: https://crates.io/ +[customized]: #configuring-a-target +[dependencies]: specifying-dependencies.md +[dev-dependencies]: specifying-dependencies.md#development-dependencies +[documentation examples]: ../../rustdoc/documentation-tests.html +[features]: manifest.md#the-features-section +[nightly channel]: ../../book/appendix-07-nightly-rust.html +[package layout]: ../guide/project-layout.md +[package-edition]: manifest.md#the-edition-field +[proc-macro-reference]: ../../reference/procedural-macros.html +[procedural macro]: ../../book/ch19-06-macros.html +[test-attribute]: ../../reference/attributes/testing.html#the-test-attribute diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md index a6eb8a2e0c9..a8258ec5c51 100644 --- a/src/doc/src/reference/index.md +++ b/src/doc/src/reference/index.md @@ -4,6 +4,7 @@ The reference covers the details of various areas of Cargo. * [Specifying Dependencies](specifying-dependencies.md) * [The Manifest Format](manifest.md) + * [Cargo Targets](cargo-targets.md) * [Profiles](profiles.md) * [Configuration](config.md) * [Environment Variables](environment-variables.md) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index a30558d57a2..305d1498f96 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -679,200 +679,6 @@ When `default-members` is not specified, the default is the root manifest if it is a package, or every member manifest (as if `--workspace` were specified on the command-line) for virtual workspaces. -### Examples - -Files located under `examples` are example uses of the functionality provided by -the library. When compiled, they are placed in the `target/examples` directory. - -They can compile either as executables (with a `main()` function) or libraries -and pull in the library by using `extern crate `. They are -compiled when you run your tests to protect them from bitrotting. - -You can run individual executable examples with the command `cargo run --example -`. - -Specify `crate-type` to make an example be compiled as a library (additional -information about crate types is available in -[The Rust Reference](../../reference/linkage.html)): - -```toml -[[example]] -name = "foo" -crate-type = ["staticlib"] -``` - -You can build individual library examples with the command `cargo build ---example `. - -### Tests - -When you run [`cargo test`], Cargo will: - -* compile and run your library’s unit tests, which are in the files reachable - from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be - considered at this stage); -* compile and run your library’s documentation tests, which are embedded inside - of documentation blocks; -* compile and run your library’s [integration tests](#integration-tests); and -* compile your library’s examples. - -#### Integration tests - -Each file in `tests/*.rs` is an integration test. When you run [`cargo test`], -Cargo will compile each of these files as a separate crate. The crate can link -to your library by using `extern crate `, like any other code that -depends on it. - -Cargo will not automatically compile files inside subdirectories of `tests`, but -an integration test can import modules from these directories as usual. For -example, if you want several integration tests to share some code, you can put -the shared code in `tests/common/mod.rs` and then put `mod common;` in each of -the test files. - -### Configuring a target - -All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]` -sections support similar configuration for specifying how a target should be -built. The double-bracket sections like `[[bin]]` are array-of-table of -[TOML](https://github.com/toml-lang/toml#array-of-tables), which means you can -write more than one `[[bin]]` section to make several executables in your crate. - -The example below uses `[lib]`, but it also applies to all other sections -as well. All values listed are the defaults for that option unless otherwise -specified. - -```toml -[package] -# ... - -[lib] -# The name of a target is the name of the library that will be generated. This -# is defaulted to the name of the package, with any dashes replaced -# with underscores. (Rust `extern crate` declarations reference this name; -# therefore the value must be a valid Rust identifier to be usable.) -name = "foo" - -# This field points at where the crate is located, relative to the `Cargo.toml`. -path = "src/lib.rs" - -# A flag for enabling unit tests for this target. This is used by `cargo test`. -test = true - -# A flag for enabling documentation tests for this target. This is only relevant -# for libraries, it has no effect on other sections. This is used by -# `cargo test`. -doctest = true - -# A flag for enabling benchmarks for this target. This is used by `cargo bench`. -bench = true - -# A flag for enabling documentation of this target. This is used by `cargo doc`. -doc = true - -# If the target is meant to be a compiler plugin, this field must be set to true -# for Cargo to correctly compile it and make it available for all dependencies. -plugin = false - -# If the target is meant to be a "macros 1.1" procedural macro, this field must -# be set to true. -proc-macro = false - -# If set to false, `cargo test` will omit the `--test` flag to rustc, which -# stops it from generating a test harness. This is useful when the binary being -# built manages the test runner itself. -harness = true - -# If set then a target can be configured to use a different edition than the -# `[package]` is configured to use, perhaps only compiling a library with the -# 2018 edition or only compiling one unit test with the 2015 edition. By default -# all targets are compiled with the edition specified in `[package]`. -edition = '2015' - -# Here's an example of a TOML "array of tables" section, in this case specifying -# a binary target name and path. -[[bin]] -name = "my-cool-binary" -path = "src/my-cool-binary.rs" -``` - -#### Target auto-discovery - -By default, Cargo automatically determines the targets to build based on the -[layout of the files][package-layout] on the filesystem. The target -configuration tables, such as `[lib]`, `[[bin]]`, `[[test]]`, `[[bench]]`, or -`[[example]]`, can be used to add additional targets that don't follow the -standard directory layout. - -The automatic target discovery can be disabled so that only manually -configured targets will be built. Setting the keys `autobins`, `autoexamples`, -`autotests`, or `autobenches` to `false` in the `[package]` section will -disable auto-discovery of the corresponding target type. - -Disabling automatic discovery should only be needed for specialized -situations. For example, if you have a library where you want a *module* named -`bin`, this would present a problem because Cargo would usually attempt to -compile anything in the `bin` directory as an executable. Here is a sample -layout of this scenario: - -``` -├── Cargo.toml -└── src -    ├── lib.rs -    └── bin -       └── mod.rs -``` - -To prevent Cargo from inferring `src/bin/mod.rs` as an executable, set -`autobins = false` in `Cargo.toml` to disable auto-discovery: - -```toml -[package] -# … -autobins = false -``` - -> **Note**: For packages with the 2015 edition, the default for auto-discovery -> is `false` if at least one target is manually defined in `Cargo.toml`. -> Beginning with the 2018 edition, the default is always `true`. - -#### The `required-features` field - -The `required-features` field specifies which features the target needs in order -to be built. If any of the required features are not selected, the target will -be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, `[[test]]`, -and `[[example]]` sections, it has no effect on `[lib]`. - -```toml -[features] -# ... -postgres = [] -sqlite = [] -tools = [] - -[[bin]] -# ... -required-features = ["postgres", "tools"] -``` - -#### Building dynamic or static libraries - -If your package produces a library, you can specify which kind of library to -build by explicitly listing the library in your `Cargo.toml`: - -```toml -# ... - -[lib] -name = "..." -crate-type = ["dylib"] # could be `staticlib` as well -``` - -The available options are `dylib`, `rlib`, `staticlib`, `cdylib`, and -`proc-macro`. - -You can read more about the different crate types in the -[Rust Reference Manual](../../reference/linkage.html) - ### The `[patch]` Section This section of Cargo.toml can be used to [override dependencies][replace] with @@ -969,7 +775,6 @@ dependencies][replace] section of the documentation. [`cargo init`]: ../commands/cargo-init.md [`cargo new`]: ../commands/cargo-new.md [`cargo run`]: ../commands/cargo-run.md -[`cargo test`]: ../commands/cargo-test.md [crates.io]: https://crates.io/ [docs.rs]: https://docs.rs/ [publishing]: publishing.md @@ -977,13 +782,19 @@ dependencies][replace] section of the documentation. [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 [spdx-license-list-3.6]: https://github.com/spdx/license-list-data/tree/v3.6 [SPDX site]: https://spdx.org/license-list -[package-layout]: ../guide/project-layout.md [patch]: #the-patch-section + + diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 748a06eda77..44df763c8d1 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -84,8 +84,8 @@ When specified, `default-members` must expand to a subset of `members`. [package]: manifest.md#the-package-section [output directory]: ../guide/build-cache.md -[patch]: manifest.md#the-patch-section -[replace]: manifest.md#the-replace-section +[patch]: overriding-dependencies.md#the-patch-section +[replace]: overriding-dependencies.md#the-replace-section [profiles]: profiles.md [`path` dependencies]: specifying-dependencies.md#specifying-path-dependencies [`package.workspace`]: manifest.md#the-workspace-field From c2ff76287b1fc0e3a5a1424d4dc2d91af9148f6f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 21 Dec 2019 13:22:58 -0800 Subject: [PATCH 27/28] Add build script examples to reference index. --- src/doc/src/reference/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md index 00a6874590d..dd41258fd73 100644 --- a/src/doc/src/reference/index.md +++ b/src/doc/src/reference/index.md @@ -12,6 +12,7 @@ The reference covers the details of various areas of Cargo. * [Configuration](config.md) * [Environment Variables](environment-variables.md) * [Build Scripts](build-scripts.md) + * [Build Script Examples](build-script-examples.md) * [Publishing on crates.io](publishing.md) * [Package ID Specifications](pkgid-spec.md) * [Source Replacement](source-replacement.md) From 493eb34327932964081c90bec8284a01b85aa0ad Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 21 Dec 2019 13:28:27 -0800 Subject: [PATCH 28/28] Note that harness=false enables cfg(test). --- src/doc/src/reference/cargo-targets.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/doc/src/reference/cargo-targets.md b/src/doc/src/reference/cargo-targets.md index 0e9891ac020..4be13c3529f 100644 --- a/src/doc/src/reference/cargo-targets.md +++ b/src/doc/src/reference/cargo-targets.md @@ -248,6 +248,9 @@ default is `true` for all targets. If set to `false`, then you are responsible for defining a `main()` function to run tests and benchmarks. +Tests have the [`cfg(test)` conditional expression][cfg-test] enabled whether +or not the harness is enabled. + #### The `edition` field The `edition` field defines the [Rust edition] the target will use. If not @@ -353,6 +356,7 @@ autobins = false [`cargo install`]: ../commands/cargo-install.md [`cargo run`]: ../commands/cargo-run.md [`cargo test`]: ../commands/cargo-test.md +[cfg-test]: ../../reference/conditional-compilation.html#test [crate types]: ../../reference/linkage.html [crates.io]: https://crates.io/ [customized]: #configuring-a-target