Add flags to assert lock/cache behavior to Cargo

If a lock file is generated and some equivalent of `cargo fetch` is run then
Cargo shouldn't ever touch the network or modify `Cargo.lock` until any
`Cargo.toml` later changes, but this often wants to be asserted in some build
environments where it's a programmer error if Cargo attempts to access the
network.

The `--locked` flag added here will assert that `Cargo.lock` does not need to
change to proceed. That is, if `Cargo.lock` would be modified (as it
automatically is by default) this is turned into a hard error instead.

This `--frozen` will not only assert that `Cargo.lock` doesn't change (the same
behavior as `--locked`), but it will also will manually prevent Cargo from
touching the network by ensuring that all network requests return an error.

These flags can be used in environments where it is *expected* that no network
access happens (or no lockfile changes happen) because it has been pre-arranged
for Cargo to not happen. Examples of this include:

* CI for projects want to pass `--locked` to ensure that `Cargo.lock` is up to
  date before changes are checked in.
* Environments with vendored dependencies want to pass `--frozen` as touching
  the network indicates a programmer error that something wasn't vendored
  correctly.

A crucial property of these two flags is that **they do not change the behavior
of Cargo**. They are simply assertions at a few locations in Cargo to ensure
that actions expected to not happen indeed don't happen. Some documentation has
also been added to this effect.

Closes #2111

Author: alexcrichton

src/bin/bench.rs

@@ -20,6 +20,8 @@ pub struct Options {
     flag_example: Vec<String>,
     flag_test: Vec<String>,
     flag_bench: Vec<String>,
+    flag_frozen: bool,
+    flag_locked: bool,
     arg_args: Vec<String>,
 }
 
@@ -46,6 +48,8 @@ Options:
     -v, --verbose ...            Use verbose output
     -q, --quiet                  No output printed to stdout
     --color WHEN                 Coloring: auto, always, never
+    --frozen                     Require Cargo.lock and cache are up to date
+    --locked                     Require Cargo.lock is up to date
 
 All of the trailing arguments are passed to the benchmark binaries generated
 for filtering benchmarks and generally providing options configuring how they
@@ -64,9 +68,11 @@ Compilation can be customized with the `bench` profile in the manifest.
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
     let root = try!(find_root_manifest_for_wd(options.flag_manifest_path, config.cwd()));
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
 
     let ops = ops::TestOptions {
         no_run: options.flag_no_run,

src/bin/build.rs

@@ -23,6 +23,8 @@ pub struct Options {
     flag_example: Vec<String>,
     flag_test: Vec<String>,
     flag_bench: Vec<String>,
+    flag_locked: bool,
+    flag_frozen: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -48,6 +50,8 @@ Options:
     -v, --verbose ...            Use verbose output
     -q, --quiet                  No output printed to stdout
     --color WHEN                 Coloring: auto, always, never
+    --frozen                     Require Cargo.lock and cache are up to date
+    --locked                     Require Cargo.lock is up to date
 
 If the --package argument is given, then SPEC is a package id specification
 which indicates which package should be built. If it is not given, then the
@@ -62,9 +66,11 @@ the --release flag will use the `release` profile instead.
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
     debug!("executing; cmd=cargo-build; args={:?}",
            env::args().collect::<Vec<_>>());
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
 
     let root = try!(find_root_manifest_for_wd(options.flag_manifest_path, config.cwd()));
 

src/bin/cargo.rs

@@ -28,6 +28,8 @@ pub struct Flags {
     flag_explain: Option<String>,
     arg_command: String,
     arg_args: Vec<String>,
+    flag_locked: bool,
+    flag_frozen: bool,
 }
 
 const USAGE: &'static str = "
@@ -45,6 +47,8 @@ Options:
     -v, --verbose ...   Use verbose output
     -q, --quiet         No output printed to stdout
     --color WHEN        Coloring: auto, always, never
+    --frozen            Require Cargo.lock and cache are up to date
+    --locked            Require Cargo.lock is up to date
 
 Some common cargo commands are (see all commands with --list):
     build       Compile the current project
@@ -68,6 +72,16 @@ fn main() {
     execute_main_without_stdin(execute, true, USAGE)
 }
 
+macro_rules! configure_shell {
+    ($config:expr, $options:expr) => (
+        try!($config.configure($options.flag_verbose,
+                               $options.flag_quiet,
+                               &$options.flag_color,
+                               $options.flag_frozen,
+                               $options.flag_locked));
+    )
+}
+
 macro_rules! each_subcommand{
     ($mac:ident) => {
         $mac!(bench);
@@ -113,9 +127,11 @@ each_subcommand!(declare_mod);
   on this top-level information.
 */
 fn execute(flags: Flags, config: &Config) -> CliResult<Option<()>> {
-    try!(config.configure_shell(flags.flag_verbose,
-                                flags.flag_quiet,
-                                &flags.flag_color));
+    try!(config.configure(flags.flag_verbose,
+                          flags.flag_quiet,
+                          &flags.flag_color,
+                          flags.flag_frozen,
+                          flags.flag_locked));
 
     init_git_transports(config);
     cargo::util::job::setup();

src/bin/clean.rs

@@ -14,6 +14,8 @@ pub struct Options {
     flag_quiet: Option<bool>,
     flag_color: Option<String>,
     flag_release: bool,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -31,6 +33,8 @@ Options:
     -v, --verbose ...            Use verbose output
     -q, --quiet                  No output printed to stdout
     --color WHEN                 Coloring: auto, always, never
+    --frozen                     Require Cargo.lock and cache are up to date
+    --locked                     Require Cargo.lock is up to date
 
 If the --package argument is given, then SPEC is a package id specification
 which indicates which package's artifacts should be cleaned out. If it is not
@@ -40,9 +44,11 @@ and its format, see the `cargo help pkgid` command.
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
     debug!("executing; cmd=cargo-clean; args={:?}", env::args().collect::<Vec<_>>());
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
 
     let root = try!(find_root_manifest_for_wd(options.flag_manifest_path, config.cwd()));
     let opts = ops::CleanOptions {

src/bin/doc.rs

@@ -19,6 +19,8 @@ pub struct Options {
     flag_package: Vec<String>,
     flag_lib: bool,
     flag_bin: Vec<String>,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -43,6 +45,8 @@ Options:
     -v, --verbose ...            Use verbose output
     -q, --quiet                  No output printed to stdout
     --color WHEN                 Coloring: auto, always, never
+    --frozen                     Require Cargo.lock and cache are up to date
+    --locked                     Require Cargo.lock is up to date
 
 By default the documentation for the local package and all dependencies is
 built. The output is all placed in `target/doc` in rustdoc's usual format.
@@ -54,9 +58,11 @@ the `cargo help pkgid` command.
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
 
     let root = try!(find_root_manifest_for_wd(options.flag_manifest_path, config.cwd()));
 

src/bin/fetch.rs

@@ -9,6 +9,8 @@ pub struct Options {
     flag_verbose: u32,
     flag_quiet: Option<bool>,
     flag_color: Option<String>,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -23,6 +25,8 @@ Options:
     -v, --verbose ...        Use verbose output
     -q, --quiet              No output printed to stdout
     --color WHEN             Coloring: auto, always, never
+    --frozen                 Require Cargo.lock and cache are up to date
+    --locked                 Require Cargo.lock is up to date
 
 If a lockfile is available, this command will ensure that all of the git
 dependencies and/or registries dependencies are downloaded and locally
@@ -35,9 +39,11 @@ all updated.
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
     let root = try!(find_root_manifest_for_wd(options.flag_manifest_path, config.cwd()));
     let ws = try!(Workspace::new(&root, config));
     try!(ops::fetch(&ws));

src/bin/generate_lockfile.rs

@@ -11,6 +11,8 @@ pub struct Options {
     flag_verbose: u32,
     flag_quiet: Option<bool>,
     flag_color: Option<String>,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -25,13 +27,17 @@ Options:
     -v, --verbose ...        Use verbose output
     -q, --quiet              No output printed to stdout
     --color WHEN             Coloring: auto, always, never
+    --frozen                 Require Cargo.lock and cache are up to date
+    --locked                 Require Cargo.lock is up to date
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
     debug!("executing; cmd=cargo-generate-lockfile; args={:?}", env::args().collect::<Vec<_>>());
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
     let root = try!(find_root_manifest_for_wd(options.flag_manifest_path, config.cwd()));
 
     let ws = try!(Workspace::new(&root, config));

src/bin/git_checkout.rs

@@ -9,6 +9,8 @@ pub struct Options {
     flag_verbose: u32,
     flag_quiet: Option<bool>,
     flag_color: Option<String>,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -23,12 +25,16 @@ Options:
     -v, --verbose ...        Use verbose output
     -q, --quiet              No output printed to stdout
     --color WHEN             Coloring: auto, always, never
+    --frozen                 Require Cargo.lock and cache are up to date
+    --locked                 Require Cargo.lock is up to date
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
     let Options { flag_url: url, flag_reference: reference, .. } = options;
 
     let url = try!(url.to_url().map_err(|e| {

src/bin/init.rs

@@ -12,6 +12,8 @@ pub struct Options {
     arg_path: Option<String>,
     flag_name: Option<String>,
     flag_vcs: Option<ops::VersionControl>,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -31,13 +33,17 @@ Options:
     -v, --verbose ...   Use verbose output
     -q, --quiet         No output printed to stdout
     --color WHEN        Coloring: auto, always, never
+    --frozen            Require Cargo.lock and cache are up to date
+    --locked            Require Cargo.lock is up to date
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
     debug!("executing; cmd=cargo-init; args={:?}", env::args().collect::<Vec<_>>());
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
 
     let Options { flag_bin, arg_path, flag_name, flag_vcs, .. } = options;
 

src/bin/install.rs

@@ -16,6 +16,8 @@ pub struct Options {
     flag_root: Option<String>,
     flag_list: bool,
     flag_force: bool,
+    flag_frozen: bool,
+    flag_locked: bool,
 
     arg_crate: Option<String>,
     flag_vers: Option<String>,
@@ -56,6 +58,8 @@ Build and install options:
     -v, --verbose ...         Use verbose output
     -q, --quiet               Less output printed to stdout
     --color WHEN              Coloring: auto, always, never
+    --frozen                  Require Cargo.lock and cache are up to date
+    --locked                  Require Cargo.lock is up to date
 
 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
@@ -89,9 +93,11 @@ The `--list` option will list all installed packages (and their versions).
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
 
     let compile_opts = ops::CompileOptions {
         config: config,

src/bin/login.rs

@@ -13,6 +13,8 @@ pub struct Options {
     flag_verbose: u32,
     flag_quiet: Option<bool>,
     flag_color: Option<String>,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -27,13 +29,17 @@ Options:
     -v, --verbose ...        Use verbose output
     -q, --quiet              No output printed to stdout
     --color WHEN             Coloring: auto, always, never
+    --frozen                 Require Cargo.lock and cache are up to date
+    --locked                 Require Cargo.lock is up to date
 
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<()>> {
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
     let token = match options.arg_token.clone() {
         Some(token) => token,
         None => {

src/bin/metadata.rs

@@ -13,6 +13,8 @@ pub struct Options {
     flag_no_deps: bool,
     flag_quiet: Option<bool>,
     flag_verbose: u32,
+    flag_frozen: bool,
+    flag_locked: bool,
 }
 
 pub const USAGE: &'static str = "
@@ -34,12 +36,16 @@ Options:
     -v, --verbose ...          Use verbose output
     -q, --quiet                No output printed to stdout
     --color WHEN               Coloring: auto, always, never
+    --frozen                   Require Cargo.lock and cache are up to date
+    --locked                   Require Cargo.lock is up to date
 ";
 
 pub fn execute(options: Options, config: &Config) -> CliResult<Option<ExportInfo>> {
-    try!(config.configure_shell(options.flag_verbose,
-                                options.flag_quiet,
-                                &options.flag_color));
+    try!(config.configure(options.flag_verbose,
+                          options.flag_quiet,
+                          &options.flag_color,
+                          options.flag_frozen,
+                          options.flag_locked));
     let manifest = try!(find_root_manifest_for_wd(options.flag_manifest_path, config.cwd()));
 
     let options = OutputMetadataOptions {