Stabilize publish-lockfile.

Author: ehuss

src/bin/cargo/commands/install.rs

@@ -68,15 +68,16 @@ pub fn cli() -> App {
         )
         .after_help(
             "\
-This command manages Cargo's local set of installed binary crates. Only packages
-which have [[bin]] targets can be installed, and all binaries are installed into
-the installation root's `bin` folder. The installation root is determined, in
-order of precedence, by `--root`, `$CARGO_INSTALL_ROOT`, the `install.root`
-configuration key, and finally the home directory (which is either
-`$CARGO_HOME` if set or `$HOME/.cargo` by default).
+This command manages Cargo's local set of installed binary crates. Only
+packages which have executable [[bin]] or [[example]] targets can be
+installed, and all executables are installed into the installation root's
+`bin` folder. The installation root is determined, in order of precedence, by
+`--root`, `$CARGO_INSTALL_ROOT`, the `install.root` configuration key, and
+finally the home directory (which is either `$CARGO_HOME` if set or
+`$HOME/.cargo` by default).
 
 There are multiple sources from which a crate can be installed. The default
-location is crates.io but the `--git`, `--path`, and `registry` flags can
+location is crates.io but the `--git`, `--path`, and `--registry` flags can
 change this source. If the source contains more than one package (such as
 crates.io or a git repository with multiple crates) the `<crate>` argument is
 required to indicate which crate should be installed.

src/cargo/core/features.rs

@@ -186,6 +186,7 @@ features! {
         [stable] rename_dependency: bool,
 
         // Whether a lock file is published with this crate
+        // This is deprecated, and will likely be removed in a future version.
         [unstable] publish_lockfile: bool,
 
         // Overriding profiles for dependencies.

src/cargo/core/manifest.rs

@@ -478,9 +478,6 @@ impl Manifest {
     pub fn publish(&self) -> &Option<Vec<String>> {
         &self.publish
     }
-    pub fn publish_lockfile(&self) -> bool {
-        self.publish_lockfile
-    }
     pub fn replace(&self) -> &[(PackageIdSpec, Dependency)] {
         &self.replace
     }

src/cargo/core/package.rs

@@ -240,8 +240,7 @@ impl Package {
 
     /// Returns if package should include `Cargo.lock`.
     pub fn include_lockfile(&self) -> bool {
-        self.manifest().publish_lockfile()
-            && self.targets().iter().any(|t| t.is_example() || t.is_bin())
+        self.targets().iter().any(|t| t.is_example() || t.is_bin())
     }
 }
 

src/cargo/ops/cargo_package.rs

@@ -42,8 +42,12 @@ pub struct PackageOpts<'cfg> {
 static VCS_INFO_FILE: &'static str = ".cargo_vcs_info.json";
 
 pub fn package(ws: &Workspace<'_>, opts: &PackageOpts<'_>) -> CargoResult<Option<FileLock>> {
-    // Make sure the Cargo.lock is up-to-date and valid.
-    ops::resolve_ws(ws)?;
+    if ws.root().join("Cargo.lock").exists() {
+        // Make sure the Cargo.lock is up-to-date and valid.
+        ops::resolve_ws(ws)?;
+        // If Cargo.lock does not exist, it will be generated by `build_lock`
+        // below, and will be validated during the verification step.
+    }
     let pkg = ws.current()?;
     let config = ws.config();
 
@@ -615,7 +619,7 @@ fn run_verify(ws: &Workspace<'_>, tar: &FileLock, opts: &PackageOpts<'_>) -> Car
     };
 
     let exec: Arc<dyn Executor> = Arc::new(DefaultExecutor);
-    ops::compile_ws(
+    ops::compile_with_exec(
         &ws,
         &ops::CompileOptions {
             config,

src/cargo/util/toml/mod.rs

@@ -1034,6 +1034,11 @@ impl TomlManifest {
         let publish_lockfile = match project.publish_lockfile {
             Some(b) => {
                 features.require(Feature::publish_lockfile())?;
+                warnings.push(
+                    "The `publish-lockfile` feature is deprecated and currently \
+                     has no effect. It may be removed in a future version."
+                        .to_string(),
+                );
                 b
             }
             None => features.is_enabled(Feature::publish_lockfile()),

src/doc/man/cargo-install.adoc

@@ -17,14 +17,15 @@ cargo-install - Build and install a Rust binary
 
 == DESCRIPTION
 
-This command manages Cargo's local set of installed binary crates. Only packages
-which have `\[[bin]]` targets can be installed, and all binaries are installed into
-the installation root's `bin` folder.
+This command manages Cargo's local set of installed binary crates. Only
+packages which have executable `\[[bin]]` or `\[[example]]` targets can be
+installed, and all executables are installed into the installation root's
+`bin` folder.
 
 include::description-install-root.adoc[]
 
 There are multiple sources from which a crate can be installed. The default
-location is crates.io but the `--git`, `--path`, and `registry` flags can
+location is crates.io but the `--git`, `--path`, and `--registry` flags can
 change this source. If the source contains more than one package (such as
 crates.io or a git repository with multiple crates) the _CRATE_ argument is
 required to indicate which crate should be installed.
@@ -42,6 +43,20 @@ specified by setting the `CARGO_TARGET_DIR` environment variable to a relative
 path. In particular, this can be useful for caching build artifacts on
 continuous integration systems.
 
+By default, the `Cargo.lock` file that is included with the package will be
+ignored. This means that Cargo will recompute which versions of dependencies
+to use, possibly using newer versions that have been released since the
+package was published. The `--locked` flag can be used to force Cargo to use
+the packaged `Cargo.lock` file if it is available. This may be useful for
+ensuring reproducible builds, to use the exact same set of dependencies that
+were available when the package was published. It may also be useful if a
+newer version of a dependency is published that no longer builds on your
+system, or has other problems. The downside to using `--locked` is that you
+will not receive any fixes or updates to any dependency. Note that Cargo did
+not start publishing `Cargo.lock` files until version 1.37, which means
+packages published with prior versions will not have a `Cargo.lock` file
+available.
+
 == OPTIONS
 
 === Install Options

src/doc/man/cargo-package.adoc

@@ -25,6 +25,9 @@ steps:
     - The original `Cargo.toml` file is rewritten and normalized.
     - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the
       manifest.
+    - `Cargo.lock` is automatically included if the package contains an
+      executable binary or example target. man:cargo-install[1] will use the
+      packaged lock file if the `--locked` flag is used.
     - A `.cargo_vcs_info.json` file is included that contains information
       about the current VCS checkout hash if available (not included with
       `--allow-dirty`).

src/doc/man/generated/cargo-install.html

@@ -17,9 +17,10 @@ <h2 id="cargo_install_synopsis">SYNOPSIS</h2>
 <h2 id="cargo_install_description">DESCRIPTION</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>This command manages Cargo&#8217;s local set of installed binary crates. Only packages
-which have <code>[[bin]]</code> targets can be installed, and all binaries are installed into
-the installation root&#8217;s <code>bin</code> folder.</p>
+<p>This command manages Cargo&#8217;s local set of installed binary crates. Only
+packages which have executable <code>[[bin]]</code> or <code>[[example]]</code> targets can be
+installed, and all executables are installed into the installation root&#8217;s
+<code>bin</code> folder.</p>
 </div>
 <div class="paragraph">
 <p>The installation root is determined, in order of precedence:</p>
@@ -45,7 +46,7 @@ <h2 id="cargo_install_description">DESCRIPTION</h2>
 </div>
 <div class="paragraph">
 <p>There are multiple sources from which a crate can be installed. The default
-location is crates.io but the <code>--git</code>, <code>--path</code>, and <code>registry</code> flags can
+location is crates.io but the <code>--git</code>, <code>--path</code>, and <code>--registry</code> flags can
 change this source. If the source contains more than one package (such as
 crates.io or a git repository with multiple crates) the <em>CRATE</em> argument is
 required to indicate which crate should be installed.</p>
@@ -65,6 +66,21 @@ <h2 id="cargo_install_description">DESCRIPTION</h2>
 path. In particular, this can be useful for caching build artifacts on
 continuous integration systems.</p>
 </div>
+<div class="paragraph">
+<p>By default, the <code>Cargo.lock</code> file that is included with the package will be
+ignored. This means that Cargo will recompute which versions of dependencies
+to use, possibly using newer versions that have been released since the
+package was published. The <code>--locked</code> flag can be used to force Cargo to use
+the packaged <code>Cargo.lock</code> file if it is available. This may be useful for
+ensuring reproducible builds, to use the exact same set of dependencies that
+were available when the package was published. It may also be useful if a
+newer version of a dependency is published that no longer builds on your
+system, or has other problems. The downside to using <code>--locked</code> is that you
+will not receive any fixes or updates to any dependency. Note that Cargo did
+not start publishing <code>Cargo.lock</code> files until version 1.37, which means
+packages published with prior versions will not have a <code>Cargo.lock</code> file
+available.</p>
+</div>
 </div>
 </div>
 <div class="sect1">

src/doc/man/generated/cargo-package.html

@@ -44,6 +44,11 @@ <h2 id="cargo_package_description">DESCRIPTION</h2>
 manifest.</p>
 </li>
 <li>
+<p><code>Cargo.lock</code> is automatically included if the package contains an
+executable binary or example target. <a href="commands/cargo-install.html">cargo-install(1)</a> will use the
+packaged lock file if the <code>--locked</code> flag is used.</p>
+</li>
+<li>
 <p>A <code>.cargo_vcs_info.json</code> file is included that contains information
 about the current VCS checkout hash if available (not included with
 <code>--allow-dirty</code>).</p>