Support for negative --jobs parameter, counting backwards from max CPUs

src/cargo/core/compiler/build_config.rs

@@ -56,27 +56,26 @@ impl BuildConfig {
     /// * `target.$target.libfoo.metadata`
     pub fn new(
         config: &Config,
-        jobs: Option<u32>,
+        jobs: Option<i32>,
         keep_going: bool,
         requested_targets: &[String],
         mode: CompileMode,
     ) -> CargoResult<BuildConfig> {
         let cfg = config.build_config()?;
         let requested_kinds = CompileKind::from_requested_targets(config, requested_targets)?;
-        if jobs == Some(0) {
-            anyhow::bail!("jobs must be at least 1")
-        }
         if jobs.is_some() && config.jobserver_from_env().is_some() {
             config.shell().warn(
                 "a `-j` argument was passed to Cargo but Cargo is \
                  also configured with an external jobserver in \
                  its environment, ignoring the `-j` parameter",
             )?;
         }
-        let jobs = jobs.or(cfg.jobs).unwrap_or(::num_cpus::get() as u32);
-        if jobs == 0 {
-            anyhow::bail!("jobs may not be 0");
-        }
+        let jobs = match jobs.or(cfg.jobs) {
+            None => ::num_cpus::get() as u32,
+            Some(0) => anyhow::bail!("jobs may not be 0"),
+            Some(j) if j < 0 => (::num_cpus::get() as i32 + j).max(1) as u32,
+            Some(j) => j as u32,
+        };
 
         if config.cli_unstable().build_std.is_some() && requested_kinds[0].is_host() {
             // TODO: This should eventually be fixed.

src/cargo/core/compiler/context/mod.rs

@@ -92,7 +92,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
         let jobserver = match bcx.config.jobserver_from_env() {
             Some(c) => c.clone(),
             None => {
-                let client = Client::new(bcx.build_config.jobs as usize)
+                let client = Client::new(bcx.jobs() as usize)
                     .with_context(|| "failed to create jobserver")?;
                 client.acquire_raw()?;
                 client
@@ -603,7 +603,7 @@ impl<'a, 'cfg> Context<'a, 'cfg> {
     }
 
     pub fn new_jobserver(&mut self) -> CargoResult<Client> {
-        let tokens = self.bcx.build_config.jobs as usize;
+        let tokens = self.bcx.jobs() as usize;
         let client = Client::new(tokens).with_context(|| "failed to create jobserver")?;
 
         // Drain the client fully

src/cargo/core/compiler/timings.rs

@@ -441,7 +441,7 @@ impl<'cfg> Timings<'cfg> {
             self.total_dirty,
             self.total_fresh + self.total_dirty,
             max_concurrency,
-            bcx.build_config.jobs,
+            bcx.jobs(),
             num_cpus::get(),
             self.start_str,
             total_time,

src/cargo/ops/cargo_package.rs

@@ -30,7 +30,7 @@ pub struct PackageOpts<'cfg> {
     pub check_metadata: bool,
     pub allow_dirty: bool,
     pub verify: bool,
-    pub jobs: Option<u32>,
+    pub jobs: Option<i32>,
     pub keep_going: bool,
     pub to_package: ops::Packages,
     pub targets: Vec<String>,

src/cargo/ops/registry.rs

@@ -80,7 +80,7 @@ pub struct PublishOpts<'cfg> {
     pub index: Option<String>,
     pub verify: bool,
     pub allow_dirty: bool,
-    pub jobs: Option<u32>,
+    pub jobs: Option<i32>,
     pub keep_going: bool,
     pub to_publish: ops::Packages,
     pub targets: Vec<String>,

src/cargo/util/command_prelude.rs

@@ -69,7 +69,8 @@ pub trait AppExt: Sized {
         self._arg(
             opt("jobs", "Number of parallel jobs, defaults to # of CPUs")
                 .short('j')
-                .value_name("N"),
+                .value_name("N")
+                .allow_hyphen_values(true),
         )
         ._arg(flag(
             "keep-going",
@@ -326,6 +327,19 @@ pub trait ArgMatchesExt {
         Ok(arg)
     }
 
+    fn value_of_i32(&self, name: &str) -> CargoResult<Option<i32>> {
+        let arg = match self._value_of(name) {
+            None => None,
+            Some(arg) => Some(arg.parse::<i32>().map_err(|_| {
+                clap::Error::raw(
+                    clap::ErrorKind::ValueValidation,
+                    format!("Invalid value: could not parse `{}` as a number", arg),
+                )
+            })?),
+        };
+        Ok(arg)
+    }
+
     /// Returns value of the `name` command-line argument as an absolute path
     fn value_of_path(&self, name: &str, config: &Config) -> Option<PathBuf> {
         self._value_of(name).map(|path| config.cwd().join(path))
@@ -359,8 +373,8 @@ pub trait ArgMatchesExt {
         Ok(ws)
     }
 
-    fn jobs(&self) -> CargoResult<Option<u32>> {
-        self.value_of_u32("jobs")
+    fn jobs(&self) -> CargoResult<Option<i32>> {
+        self.value_of_i32("jobs")
     }
 
     fn verbose(&self) -> u32 {

src/cargo/util/config/mod.rs

@@ -2195,7 +2195,7 @@ pub struct CargoBuildConfig {
     pub target_dir: Option<ConfigRelativePath>,
     pub incremental: Option<bool>,
     pub target: Option<BuildTargetConfig>,
-    pub jobs: Option<u32>,
+    pub jobs: Option<i32>,
     pub rustflags: Option<StringList>,
     pub rustdocflags: Option<StringList>,
     pub rustc_wrapper: Option<ConfigRelativePath>,

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

@@ -373,7 +373,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -318,7 +318,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -303,7 +303,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -274,7 +274,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -376,7 +376,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -255,7 +255,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -188,7 +188,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -155,7 +155,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -218,7 +218,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -320,7 +320,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -290,7 +290,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -393,7 +393,9 @@ OPTIONS
            Number of parallel jobs to run. May also be specified with the
            build.jobs config value
            <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
-           the number of CPUs.
+           the number of logical CPUs. If negative, it sets the maximum number
+           of parallel jobs to the number of logical CPUs plus provided value.
+           Should not be 0.
 
        --keep-going
            Build as many crates in the dependency graph as possible, rather

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

@@ -1,5 +1,7 @@
 {{#option "`-j` _N_" "`--jobs` _N_"}}
 Number of parallel jobs to run. May also be specified with the
 `build.jobs` [config value](../reference/config.html). Defaults to
-the number of CPUs.
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.
 {{/option}}

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

@@ -448,7 +448,9 @@ Rust test harness runs benchmarks serially in a single thread.
 <dt class="option-term" id="option-cargo-bench---jobs"><a class="option-anchor" href="#option-cargo-bench---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-bench---keep-going"><a class="option-anchor" href="#option-cargo-bench---keep-going"></a><code>--keep-going</code></dt>

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

@@ -388,7 +388,9 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-build---jobs"><a class="option-anchor" href="#option-cargo-build---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-build---keep-going"><a class="option-anchor" href="#option-cargo-build---keep-going"></a><code>--keep-going</code></dt>

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

@@ -369,7 +369,9 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-check---jobs"><a class="option-anchor" href="#option-cargo-check---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-check---keep-going"><a class="option-anchor" href="#option-cargo-check---keep-going"></a><code>--keep-going</code></dt>

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

@@ -343,7 +343,9 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-doc---jobs"><a class="option-anchor" href="#option-cargo-doc---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-doc---keep-going"><a class="option-anchor" href="#option-cargo-doc---keep-going"></a><code>--keep-going</code></dt>

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

@@ -449,7 +449,9 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-fix---jobs"><a class="option-anchor" href="#option-cargo-fix---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-fix---keep-going"><a class="option-anchor" href="#option-cargo-fix---keep-going"></a><code>--keep-going</code></dt>

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

@@ -293,7 +293,9 @@ offline.</p>
 <dt class="option-term" id="option-cargo-install---jobs"><a class="option-anchor" href="#option-cargo-install---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-install---keep-going"><a class="option-anchor" href="#option-cargo-install---keep-going"></a><code>--keep-going</code></dt>

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

@@ -226,7 +226,9 @@ offline.</p>
 <dt class="option-term" id="option-cargo-package---jobs"><a class="option-anchor" href="#option-cargo-package---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-package---keep-going"><a class="option-anchor" href="#option-cargo-package---keep-going"></a><code>--keep-going</code></dt>

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

@@ -192,7 +192,9 @@ offline.</p>
 <dt class="option-term" id="option-cargo-publish---jobs"><a class="option-anchor" href="#option-cargo-publish---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-publish---keep-going"><a class="option-anchor" href="#option-cargo-publish---keep-going"></a><code>--keep-going</code></dt>

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

@@ -281,7 +281,9 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-run---jobs"><a class="option-anchor" href="#option-cargo-run---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-run---keep-going"><a class="option-anchor" href="#option-cargo-run---keep-going"></a><code>--keep-going</code></dt>

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

@@ -382,7 +382,9 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-rustc---jobs"><a class="option-anchor" href="#option-cargo-rustc---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-rustc---keep-going"><a class="option-anchor" href="#option-cargo-rustc---keep-going"></a><code>--keep-going</code></dt>

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

@@ -362,7 +362,9 @@ for more information about how toolchain overrides work.</dd>
 <dt class="option-term" id="option-cargo-rustdoc---jobs"><a class="option-anchor" href="#option-cargo-rustdoc---jobs"></a><code>--jobs</code> <em>N</em></dt>
 <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 CPUs.</dd>
+the number of logical CPUs. If negative, it sets the maximum number of
+parallel jobs to the number of logical CPUs plus provided value.
+Should not be 0.</dd>
 
 
 <dt class="option-term" id="option-cargo-rustdoc---keep-going"><a class="option-anchor" href="#option-cargo-rustdoc---keep-going"></a><code>--keep-going</code></dt>