Auto merge of #12222 - charmitro:master, r=weihanglo

Support "default" option for `build.jobs`

This commit adds support for passing the keyword `default` to either the CLI `--jobs` argument on the `[build.jobs]'` section of `.cargo/config`.

Closes #11816

src/cargo/core/compiler/build_config.rs

@@ -1,4 +1,5 @@
 use crate::core::compiler::CompileKind;
+use crate::util::config::JobsConfig;
 use crate::util::interning::InternedString;
 use crate::util::{CargoResult, Config, RustfixDiagnosticServer};
 use anyhow::{bail, Context as _};
@@ -64,7 +65,7 @@ impl BuildConfig {
     /// * `target.$target.libfoo.metadata`
     pub fn new(
         config: &Config,
-        jobs: Option<i32>,
+        jobs: Option<JobsConfig>,
         keep_going: bool,
         requested_targets: &[String],
         mode: CompileMode,
@@ -78,11 +79,22 @@ impl BuildConfig {
                  its environment, ignoring the `-j` parameter",
             )?;
         }
-        let jobs = match jobs.or(cfg.jobs) {
+        let jobs = match jobs.or(cfg.jobs.clone()) {
             None => default_parallelism()?,
-            Some(0) => anyhow::bail!("jobs may not be 0"),
-            Some(j) if j < 0 => (default_parallelism()? as i32 + j).max(1) as u32,
-            Some(j) => j as u32,
+            Some(value) => match value {
+                JobsConfig::Integer(j) => match j {
+                    0 => anyhow::bail!("jobs may not be 0"),
+                    j if j < 0 => (default_parallelism()? as i32 + j).max(1) as u32,
+                    j => j as u32,
+                },
+                JobsConfig::String(j) => match j.as_str() {
+                    "default" => default_parallelism()?,
+                    _ => {
+                        anyhow::bail!(
+			    format!("could not parse `{j}`. Number of parallel jobs should be `default` or a number."))
+                    }
+                },
+            },
         };
 
         if config.cli_unstable().build_std.is_some() && requested_kinds[0].is_host() {

src/cargo/ops/cargo_fetch.rs

@@ -2,6 +2,7 @@ use crate::core::compiler::standard_lib;
 use crate::core::compiler::{BuildConfig, CompileMode, RustcTargetData};
 use crate::core::{PackageSet, Resolve, Workspace};
 use crate::ops;
+use crate::util::config::JobsConfig;
 use crate::util::CargoResult;
 use crate::util::Config;
 use std::collections::HashSet;
@@ -20,7 +21,7 @@ pub fn fetch<'a>(
     ws.emit_warnings()?;
     let (mut packages, resolve) = ops::resolve_ws(ws)?;
 
-    let jobs = Some(1);
+    let jobs = Some(JobsConfig::Integer(1));
     let keep_going = false;
     let config = ws.config();
     let build_config = BuildConfig::new(

src/cargo/ops/cargo_package.rs

@@ -13,6 +13,7 @@ use crate::core::{registry::PackageRegistry, resolver::HasDevUnits};
 use crate::core::{Feature, Shell, Verbosity, Workspace};
 use crate::core::{Package, PackageId, PackageSet, Resolve, SourceId};
 use crate::sources::PathSource;
+use crate::util::config::JobsConfig;
 use crate::util::errors::CargoResult;
 use crate::util::toml::TomlManifest;
 use crate::util::{self, human_readable_bytes, restricted_names, Config, FileLock};
@@ -31,7 +32,7 @@ pub struct PackageOpts<'cfg> {
     pub check_metadata: bool,
     pub allow_dirty: bool,
     pub verify: bool,
-    pub jobs: Option<i32>,
+    pub jobs: Option<JobsConfig>,
     pub keep_going: bool,
     pub to_package: ops::Packages,
     pub targets: Vec<String>,
@@ -198,7 +199,7 @@ pub fn package(ws: &Workspace<'_>, opts: &PackageOpts<'_>) -> CargoResult<Option
                 check_metadata: opts.check_metadata,
                 allow_dirty: opts.allow_dirty,
                 verify: opts.verify,
-                jobs: opts.jobs,
+                jobs: opts.jobs.clone(),
                 keep_going: opts.keep_going,
                 to_package: ops::Packages::Default,
                 targets: opts.targets.clone(),
@@ -861,7 +862,7 @@ fn run_verify(
         &ops::CompileOptions {
             build_config: BuildConfig::new(
                 config,
-                opts.jobs,
+                opts.jobs.clone(),
                 opts.keep_going,
                 &opts.targets,
                 CompileMode::Build,

src/cargo/ops/registry.rs

@@ -32,7 +32,7 @@ use crate::sources::{RegistrySource, SourceConfigMap, CRATES_IO_DOMAIN, CRATES_I
 use crate::util::auth::{
     paserk_public_from_paserk_secret, Secret, {self, AuthorizationError},
 };
-use crate::util::config::{Config, SslVersionConfig, SslVersionConfigRange};
+use crate::util::config::{Config, JobsConfig, SslVersionConfig, SslVersionConfigRange};
 use crate::util::errors::CargoResult;
 use crate::util::important_paths::find_root_manifest_for_wd;
 use crate::util::{truncate_with_ellipsis, IntoUrl};
@@ -101,7 +101,7 @@ pub struct PublishOpts<'cfg> {
     pub index: Option<String>,
     pub verify: bool,
     pub allow_dirty: bool,
-    pub jobs: Option<i32>,
+    pub jobs: Option<JobsConfig>,
     pub keep_going: bool,
     pub to_publish: ops::Packages,
     pub targets: Vec<String>,
@@ -196,7 +196,7 @@ pub fn publish(ws: &Workspace<'_>, opts: &PublishOpts<'_>) -> CargoResult<()> {
             allow_dirty: opts.allow_dirty,
             to_package: ops::Packages::Default,
             targets: opts.targets.clone(),
-            jobs: opts.jobs,
+            jobs: opts.jobs.clone(),
             keep_going: opts.keep_going,
             cli_features: cli_features,
         },

src/cargo/util/command_prelude.rs

@@ -23,6 +23,8 @@ pub use clap::{value_parser, Arg, ArgAction, ArgMatches};
 
 pub use clap::Command;
 
+use super::config::JobsConfig;
+
 pub trait CommandExt: Sized {
     fn _arg(self, arg: Arg) -> Self;
 
@@ -66,7 +68,7 @@ pub trait CommandExt: Sized {
 
     fn arg_jobs(self) -> Self {
         self._arg(
-            opt("jobs", "Number of parallel jobs, defaults to # of CPUs")
+            opt("jobs", "Number of parallel jobs, defaults to # of CPUs.")
                 .short('j')
                 .value_name("N")
                 .allow_hyphen_values(true),
@@ -364,8 +366,16 @@ pub trait ArgMatchesExt {
         Ok(ws)
     }
 
-    fn jobs(&self) -> CargoResult<Option<i32>> {
-        self.value_of_i32("jobs")
+    fn jobs(&self) -> CargoResult<Option<JobsConfig>> {
+        let arg = match self._value_of("jobs") {
+            None => None,
+            Some(arg) => match arg.parse::<i32>() {
+                Ok(j) => Some(JobsConfig::Integer(j)),
+                Err(_) => Some(JobsConfig::String(arg.to_string())),
+            },
+        };
+
+        Ok(arg)
     }
 
     fn verbose(&self) -> u32 {

src/cargo/util/config/mod.rs

@@ -2449,6 +2449,25 @@ pub struct CargoSshConfig {
     pub known_hosts: Option<Vec<Value<String>>>,
 }
 
+/// Configuration for `jobs` in `build` section. There are two
+/// ways to configure: An integer or a simple string expression.
+///
+/// ```toml
+/// [build]
+/// jobs = 1
+/// ```
+///
+/// ```toml
+/// [build]
+/// jobs = "default" # Currently only support "default".
+/// ```
+#[derive(Debug, Deserialize, Clone)]
+#[serde(untagged)]
+pub enum JobsConfig {
+    Integer(i32),
+    String(String),
+}
+
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub struct CargoBuildConfig {
@@ -2458,7 +2477,7 @@ pub struct CargoBuildConfig {
     pub target_dir: Option<ConfigRelativePath>,
     pub incremental: Option<bool>,
     pub target: Option<BuildTargetConfig>,
-    pub jobs: Option<i32>,
+    pub jobs: Option<JobsConfig>,
     pub rustflags: Option<StringList>,
     pub rustdocflags: Option<StringList>,
     pub rustc_wrapper: Option<ConfigRelativePath>,

src/doc/man/generated_txt/cargo-bench.txt

@@ -410,6 +410,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-build.txt

@@ -341,6 +341,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-check.txt

@@ -326,6 +326,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-doc.txt

@@ -297,6 +297,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-fix.txt

@@ -399,6 +399,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-install.txt

@@ -273,6 +273,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-package.txt

@@ -191,6 +191,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-publish.txt

@@ -157,6 +157,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-run.txt

@@ -245,6 +245,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-rustc.txt

@@ -343,6 +343,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-rustdoc.txt

@@ -313,6 +313,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/generated_txt/cargo-test.txt

@@ -432,6 +432,7 @@ OPTIONS
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
            the number of logical CPUs. If negative, it sets the maximum number
            of parallel jobs to the number of logical CPUs plus provided value.
+           If a string default is provided, it sets the value back to defaults.
            Should not be 0.
 
        --keep-going

src/doc/man/includes/options-jobs.md

@@ -2,6 +2,7 @@
 Number of parallel jobs to run. May also be specified with the
 `build.jobs` [config value](../reference/config.html). Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string `default` is provided, it sets the value back to defaults.
 Should not be 0.
 {{/option}}

src/doc/src/commands/cargo-bench.md

@@ -476,7 +476,8 @@ Rust test harness runs benchmarks serially in a single thread.
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-build.md

@@ -402,7 +402,8 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-check.md

@@ -383,7 +383,8 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-doc.md

@@ -357,7 +357,8 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-fix.md

@@ -463,7 +463,8 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-install.md

@@ -312,7 +312,8 @@ offline.</p>
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-package.md

@@ -227,7 +227,8 @@ offline.</p>
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-publish.md

@@ -193,7 +193,8 @@ offline.</p>
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-run.md

@@ -299,7 +299,8 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-rustc.md

@@ -396,7 +396,8 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-rustdoc.md

@@ -376,7 +376,8 @@ requires the <code>-Z unstable-options</code> flag to enable (see
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/commands/cargo-test.md

@@ -503,7 +503,8 @@ includes an option to control the number of threads used:
 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
 <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string <code>default</code> is provided, it sets the value back to defaults.
 Should not be 0.</dd>
 
 

src/doc/src/reference/config.md

@@ -370,13 +370,14 @@ recursive_example = "rr --example recursions"
 The `[build]` table controls build-time operations and compiler settings.
 
 ##### `build.jobs`
-* Type: integer
+* Type: integer or string
 * Default: number of logical CPUs
 * Environment: `CARGO_BUILD_JOBS`
 
 Sets the maximum number of compiler processes to run in parallel. If negative,
 it sets the maximum number of compiler processes to the number of logical CPUs
-plus provided value. Should not be 0.
+plus provided value. Should not be 0. If a string `default` is provided, it sets
+the value back to defaults.
 
 Can be overridden with the `--jobs` CLI option.
 

src/etc/man/cargo-bench.1

@@ -497,7 +497,8 @@ Rust test harness runs benchmarks serially in a single thread.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-build.1

@@ -412,7 +412,8 @@ Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-check.1

@@ -393,7 +393,8 @@ Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-doc.1

@@ -360,7 +360,8 @@ Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-fix.1

@@ -488,7 +488,8 @@ Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-install.1

@@ -338,7 +338,8 @@ May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-package.1

@@ -234,7 +234,8 @@ May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-publish.1

@@ -184,7 +184,8 @@ May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-run.1

@@ -297,7 +297,8 @@ Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-rustc.1

@@ -411,7 +411,8 @@ Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-rustdoc.1

@@ -379,7 +379,8 @@ Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details.
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

src/etc/man/cargo-test.1

@@ -523,7 +523,8 @@ cargo test \-j 2 \-\- \-\-test\-threads=2
 Number of parallel jobs to run. May also be specified with the
 \fBbuild.jobs\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. Defaults to
 the number of logical CPUs. If negative, it sets the maximum number of
-parallel jobs to the number of logical CPUs plus provided value.
+parallel jobs to the number of logical CPUs plus provided value. If
+a string \fBdefault\fR is provided, it sets the value back to defaults.
 Should not be 0.
 .RE
 .sp

tests/testsuite/build.rs

@@ -5566,6 +5566,8 @@ fn good_jobs() {
     p.cargo("build --jobs 1").run();
 
     p.cargo("build --jobs -1").run();
+
+    p.cargo("build --jobs default").run();
 }
 
 #[cargo_test]
@@ -5599,8 +5601,8 @@ fn invalid_jobs() {
         .run();
 
     p.cargo("build --jobs over9000")
-        .with_status(1)
-        .with_stderr("error: Invalid value: could not parse `over9000` as a number")
+        .with_status(101)
+        .with_stderr("error: could not parse `over9000`. Number of parallel jobs should be `default` or a number.")
         .run();
 }
 

tests/testsuite/config.rs

@@ -1,7 +1,7 @@
 //! Tests for config settings.
 
 use cargo::core::{PackageIdSpec, Shell};
-use cargo::util::config::{self, Config, Definition, SslVersionConfig, StringList};
+use cargo::util::config::{self, Config, Definition, JobsConfig, SslVersionConfig, StringList};
 use cargo::util::interning::InternedString;
 use cargo::util::toml::{self as cargo_toml, TomlDebugInfo, VecStringOrBool as VSOB};
 use cargo::CargoResult;
@@ -1651,3 +1651,63 @@ fn debuginfo_parsing() {
             .ends_with("could not load config key `profile.dev.debug`"));
     }
 }
+
+#[cargo_test]
+fn build_jobs_missing() {
+    write_config(
+        "\
+[build]
+",
+    );
+
+    let config = new_config();
+
+    assert!(config
+        .get::<Option<JobsConfig>>("build.jobs")
+        .unwrap()
+        .is_none());
+}
+
+#[cargo_test]
+fn build_jobs_default() {
+    write_config(
+        "\
+[build]
+jobs = \"default\"
+",
+    );
+
+    let config = new_config();
+
+    let a = config
+        .get::<Option<JobsConfig>>("build.jobs")
+        .unwrap()
+        .unwrap();
+
+    match a {
+        JobsConfig::String(v) => assert_eq!(&v, "default"),
+        JobsConfig::Integer(_) => panic!("Did not except an integer."),
+    }
+}
+
+#[cargo_test]
+fn build_jobs_integer() {
+    write_config(
+        "\
+[build]
+jobs = 2
+",
+    );
+
+    let config = new_config();
+
+    let a = config
+        .get::<Option<JobsConfig>>("build.jobs")
+        .unwrap()
+        .unwrap();
+
+    match a {
+        JobsConfig::String(_) => panic!("Did not except an integer."),
+        JobsConfig::Integer(v) => assert_eq!(v, 2),
+    }
+}