Merge branch 'tristan/config-max-jobs' into 'master'

Add max-jobs configuration and command line option

Closes #1033

See merge request BuildStream/buildstream!1473

29 files changed, 155 insertions, 70 deletions

diff --git a/man/bst-artifact-checkout.1 b/man/bst-artifact-checkout.1
index eb16f6ffe..138b7ab54 100644
--- a/man/bst-artifact-checkout.1
+++ b/man/bst-artifact-checkout.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT CHECKOUT" "1" "01-Jul-2019" "" "bst artifact checkout Manual"
+.TH "BST ARTIFACT CHECKOUT" "1" "14-Jul-2019" "" "bst artifact checkout Manual"
 .SH NAME
 bst\-artifact\-checkout \- Checkout contents of an artifact
 .SH SYNOPSIS
diff --git a/man/bst-artifact-delete.1 b/man/bst-artifact-delete.1
index 8f80cbcaa..aa1bb34e4 100644
--- a/man/bst-artifact-delete.1
+++ b/man/bst-artifact-delete.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT DELETE" "1" "01-Jul-2019" "" "bst artifact delete Manual"
+.TH "BST ARTIFACT DELETE" "1" "14-Jul-2019" "" "bst artifact delete Manual"
 .SH NAME
 bst\-artifact\-delete \- Remove artifacts from the local cache
 .SH SYNOPSIS
diff --git a/man/bst-artifact-log.1 b/man/bst-artifact-log.1
index cfe4b15b1..34205e3f8 100644
--- a/man/bst-artifact-log.1
+++ b/man/bst-artifact-log.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT LOG" "1" "01-Jul-2019" "" "bst artifact log Manual"
+.TH "BST ARTIFACT LOG" "1" "14-Jul-2019" "" "bst artifact log Manual"
 .SH NAME
 bst\-artifact\-log \- Show logs of artifacts
 .SH SYNOPSIS
diff --git a/man/bst-artifact-pull.1 b/man/bst-artifact-pull.1
index a78178142..6b9262570 100644
--- a/man/bst-artifact-pull.1
+++ b/man/bst-artifact-pull.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT PULL" "1" "01-Jul-2019" "" "bst artifact pull Manual"
+.TH "BST ARTIFACT PULL" "1" "14-Jul-2019" "" "bst artifact pull Manual"
 .SH NAME
 bst\-artifact\-pull \- Pull a built artifact
 .SH SYNOPSIS
diff --git a/man/bst-artifact-push.1 b/man/bst-artifact-push.1
index 88115a891..6894a5be2 100644
--- a/man/bst-artifact-push.1
+++ b/man/bst-artifact-push.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT PUSH" "1" "01-Jul-2019" "" "bst artifact push Manual"
+.TH "BST ARTIFACT PUSH" "1" "14-Jul-2019" "" "bst artifact push Manual"
 .SH NAME
 bst\-artifact\-push \- Push a built artifact
 .SH SYNOPSIS
diff --git a/man/bst-artifact-server.1 b/man/bst-artifact-server.1
index 7f10ee5d9..ed5c0c096 100644
--- a/man/bst-artifact-server.1
+++ b/man/bst-artifact-server.1
@@ -1,4 +1,4 @@
-.TH "BST-ARTIFACT-SERVER" "1" "01-Jul-2019" "" "bst-artifact-server Manual"
+.TH "BST-ARTIFACT-SERVER" "1" "14-Jul-2019" "" "bst-artifact-server Manual"
 .SH NAME
 bst-artifact-server \- CAS Artifact Server
 .SH SYNOPSIS
diff --git a/man/bst-artifact.1 b/man/bst-artifact.1
index 7f65dce5b..d5b0a4797 100644
--- a/man/bst-artifact.1
+++ b/man/bst-artifact.1
@@ -1,4 +1,4 @@
-.TH "BST ARTIFACT" "1" "01-Jul-2019" "" "bst artifact Manual"
+.TH "BST ARTIFACT" "1" "14-Jul-2019" "" "bst artifact Manual"
 .SH NAME
 bst\-artifact \- Manipulate cached artifacts
 .SH SYNOPSIS
@@ -8,6 +8,10 @@ bst\-artifact \- Manipulate cached artifacts
 Manipulate cached artifacts
 .SH COMMANDS
 .PP
+\fBcheckout\fP
+  Checkout contents of an artifact
+  See \fBbst artifact-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
+.PP
 \fBpull\fP
   Pull a built artifact
   See \fBbst artifact-pull(1)\fP for full documentation on the \fBpull\fP command.
@@ -16,14 +20,10 @@ Manipulate cached artifacts
   Push a built artifact
   See \fBbst artifact-push(1)\fP for full documentation on the \fBpush\fP command.
 .PP
-\fBdelete\fP
-  Remove artifacts from the local cache
-  See \fBbst artifact-delete(1)\fP for full documentation on the \fBdelete\fP command.
-.PP
 \fBlog\fP
   Show logs of artifacts
   See \fBbst artifact-log(1)\fP for full documentation on the \fBlog\fP command.
 .PP
-\fBcheckout\fP
-  Checkout contents of an artifact
-  See \fBbst artifact-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
+\fBdelete\fP
+  Remove artifacts from the local cache
+  See \fBbst artifact-delete(1)\fP for full documentation on the \fBdelete\fP command.
diff --git a/man/bst-build.1 b/man/bst-build.1
index 760f1390e..1eab130a4 100644
--- a/man/bst-build.1
+++ b/man/bst-build.1
@@ -1,4 +1,4 @@
-.TH "BST BUILD" "1" "01-Jul-2019" "" "bst build Manual"
+.TH "BST BUILD" "1" "14-Jul-2019" "" "bst build Manual"
 .SH NAME
 bst\-build \- Build elements in a pipeline
 .SH SYNOPSIS
diff --git a/man/bst-help.1 b/man/bst-help.1
index 77b2dde3e..df6caf815 100644
--- a/man/bst-help.1
+++ b/man/bst-help.1
@@ -1,4 +1,4 @@
-.TH "BST HELP" "1" "01-Jul-2019" "" "bst help Manual"
+.TH "BST HELP" "1" "14-Jul-2019" "" "bst help Manual"
 .SH NAME
 bst\-help \- Print usage information
 .SH SYNOPSIS
diff --git a/man/bst-init.1 b/man/bst-init.1
index 7ec8cd04b..58c4e1311 100644
--- a/man/bst-init.1
+++ b/man/bst-init.1
@@ -1,4 +1,4 @@
-.TH "BST INIT" "1" "01-Jul-2019" "" "bst init Manual"
+.TH "BST INIT" "1" "14-Jul-2019" "" "bst init Manual"
 .SH NAME
 bst\-init \- Initialize a new BuildStream project
 .SH SYNOPSIS
diff --git a/man/bst-shell.1 b/man/bst-shell.1
index 61970597f..a6e8956da 100644
--- a/man/bst-shell.1
+++ b/man/bst-shell.1
@@ -1,4 +1,4 @@
-.TH "BST SHELL" "1" "01-Jul-2019" "" "bst shell Manual"
+.TH "BST SHELL" "1" "14-Jul-2019" "" "bst shell Manual"
 .SH NAME
 bst\-shell \- Shell into an element's sandbox environment
 .SH SYNOPSIS
diff --git a/man/bst-show.1 b/man/bst-show.1
index b7ea98022..ce74604a5 100644
--- a/man/bst-show.1
+++ b/man/bst-show.1
@@ -1,4 +1,4 @@
-.TH "BST SHOW" "1" "01-Jul-2019" "" "bst show Manual"
+.TH "BST SHOW" "1" "14-Jul-2019" "" "bst show Manual"
 .SH NAME
 bst\-show \- Show elements in the pipeline
 .SH SYNOPSIS
diff --git a/man/bst-source-checkout.1 b/man/bst-source-checkout.1
index 592be1542..4a3e1edd9 100644
--- a/man/bst-source-checkout.1
+++ b/man/bst-source-checkout.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE CHECKOUT" "1" "01-Jul-2019" "" "bst source checkout Manual"
+.TH "BST SOURCE CHECKOUT" "1" "14-Jul-2019" "" "bst source checkout Manual"
 .SH NAME
 bst\-source\-checkout \- Checkout sources for an element
 .SH SYNOPSIS
diff --git a/man/bst-source-fetch.1 b/man/bst-source-fetch.1
index d3f2d6d81..e25ec9175 100644
--- a/man/bst-source-fetch.1
+++ b/man/bst-source-fetch.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE FETCH" "1" "01-Jul-2019" "" "bst source fetch Manual"
+.TH "BST SOURCE FETCH" "1" "14-Jul-2019" "" "bst source fetch Manual"
 .SH NAME
 bst\-source\-fetch \- Fetch sources in a pipeline
 .SH SYNOPSIS
diff --git a/man/bst-source-track.1 b/man/bst-source-track.1
index df15b3d2e..6ce8e7a1d 100644
--- a/man/bst-source-track.1
+++ b/man/bst-source-track.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE TRACK" "1" "01-Jul-2019" "" "bst source track Manual"
+.TH "BST SOURCE TRACK" "1" "14-Jul-2019" "" "bst source track Manual"
 .SH NAME
 bst\-source\-track \- Track new source references
 .SH SYNOPSIS
diff --git a/man/bst-source.1 b/man/bst-source.1
index 1726d50ab..2598d4d1d 100644
--- a/man/bst-source.1
+++ b/man/bst-source.1
@@ -1,4 +1,4 @@
-.TH "BST SOURCE" "1" "01-Jul-2019" "" "bst source Manual"
+.TH "BST SOURCE" "1" "14-Jul-2019" "" "bst source Manual"
 .SH NAME
 bst\-source \- Manipulate sources for an element
 .SH SYNOPSIS
@@ -8,6 +8,10 @@ bst\-source \- Manipulate sources for an element
 Manipulate sources for an element
 .SH COMMANDS
 .PP
+\fBfetch\fP
+  Fetch sources in a pipeline
+  See \fBbst source-fetch(1)\fP for full documentation on the \fBfetch\fP command.
+.PP
 \fBtrack\fP
   Track new source references
   See \fBbst source-track(1)\fP for full documentation on the \fBtrack\fP command.
@@ -15,7 +19,3 @@ Manipulate sources for an element
 \fBcheckout\fP
   Checkout sources for an element
   See \fBbst source-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
-.PP
-\fBfetch\fP
-  Fetch sources in a pipeline
-  See \fBbst source-fetch(1)\fP for full documentation on the \fBfetch\fP command.
diff --git a/man/bst-workspace-close.1 b/man/bst-workspace-close.1
index 4331e87fb..0bcf74bf7 100644
--- a/man/bst-workspace-close.1
+++ b/man/bst-workspace-close.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE CLOSE" "1" "01-Jul-2019" "" "bst workspace close Manual"
+.TH "BST WORKSPACE CLOSE" "1" "14-Jul-2019" "" "bst workspace close Manual"
 .SH NAME
 bst\-workspace\-close \- Close workspaces
 .SH SYNOPSIS
diff --git a/man/bst-workspace-list.1 b/man/bst-workspace-list.1
index d892b6a35..199ff3461 100644
--- a/man/bst-workspace-list.1
+++ b/man/bst-workspace-list.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE LIST" "1" "01-Jul-2019" "" "bst workspace list Manual"
+.TH "BST WORKSPACE LIST" "1" "14-Jul-2019" "" "bst workspace list Manual"
 .SH NAME
 bst\-workspace\-list \- List open workspaces
 .SH SYNOPSIS
diff --git a/man/bst-workspace-open.1 b/man/bst-workspace-open.1
index 522f8d806..cb59cbfb6 100644
--- a/man/bst-workspace-open.1
+++ b/man/bst-workspace-open.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE OPEN" "1" "01-Jul-2019" "" "bst workspace open Manual"
+.TH "BST WORKSPACE OPEN" "1" "14-Jul-2019" "" "bst workspace open Manual"
 .SH NAME
 bst\-workspace\-open \- Open a new workspace
 .SH SYNOPSIS
diff --git a/man/bst-workspace-reset.1 b/man/bst-workspace-reset.1
index f0d712c74..255840434 100644
--- a/man/bst-workspace-reset.1
+++ b/man/bst-workspace-reset.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE RESET" "1" "01-Jul-2019" "" "bst workspace reset Manual"
+.TH "BST WORKSPACE RESET" "1" "14-Jul-2019" "" "bst workspace reset Manual"
 .SH NAME
 bst\-workspace\-reset \- Reset a workspace to its original state
 .SH SYNOPSIS
diff --git a/man/bst-workspace.1 b/man/bst-workspace.1
index 091ac4df6..aab453ccc 100644
--- a/man/bst-workspace.1
+++ b/man/bst-workspace.1
@@ -1,4 +1,4 @@
-.TH "BST WORKSPACE" "1" "01-Jul-2019" "" "bst workspace Manual"
+.TH "BST WORKSPACE" "1" "14-Jul-2019" "" "bst workspace Manual"
 .SH NAME
 bst\-workspace \- Manipulate developer workspaces
 .SH SYNOPSIS
@@ -8,18 +8,18 @@ bst\-workspace \- Manipulate developer workspaces
 Manipulate developer workspaces
 .SH COMMANDS
 .PP
+\fBopen\fP
+  Open a new workspace
+  See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
+.PP
 \fBclose\fP
   Close workspaces
   See \fBbst workspace-close(1)\fP for full documentation on the \fBclose\fP command.
 .PP
-\fBlist\fP
-  List open workspaces
-  See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command.
-.PP
 \fBreset\fP
   Reset a workspace to its original state
   See \fBbst workspace-reset(1)\fP for full documentation on the \fBreset\fP command.
 .PP
-\fBopen\fP
-  Open a new workspace
-  See \fBbst workspace-open(1)\fP for full documentation on the \fBopen\fP command.
+\fBlist\fP
+  List open workspaces
+  See \fBbst workspace-list(1)\fP for full documentation on the \fBlist\fP command.
diff --git a/man/bst.1 b/man/bst.1
index dc45b2696..16ed29260 100644
--- a/man/bst.1
+++ b/man/bst.1
@@ -1,4 +1,4 @@
-.TH "BST" "1" "01-Jul-2019" "" "bst Manual"
+.TH "BST" "1" "14-Jul-2019" "" "bst Manual"
 .SH NAME
 bst \- Build and manipulate BuildStream projects...
 .SH SYNOPSIS
@@ -32,6 +32,9 @@ Maximum simultaneous build tasks
 \fB\-\-pushers\fP INTEGER
 Maximum simultaneous upload tasks
 .TP
+\fB\-\-max\-jobs\fP INTEGER
+Number of parallel jobs allowed for a given build task
+.TP
 \fB\-\-network\-retries\fP INTEGER
 Maximum retries for network tasks
 .TP
@@ -72,37 +75,33 @@ Include an element's build tree when pulling remote element artifacts
 Cache artifact build tree content on creation
 .SH COMMANDS
 .PP
-\fBworkspace\fP
-  Manipulate developer workspaces
-  See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
+\fBhelp\fP
+  Print usage information
+  See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
 .PP
-\fBpull\fP
-  COMMAND OBSOLETE - Pull a built artifact
-  See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
+\fBinit\fP
+  Initialize a new BuildStream project
+  See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
+.PP
+\fBbuild\fP
+  Build elements in a pipeline
+  See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
 .PP
 \fBshow\fP
   Show elements in the pipeline
   See \fBbst-show(1)\fP for full documentation on the \fBshow\fP command.
 .PP
-\fBtrack\fP
-  COMMAND OBSOLETE - Track new source references
-  See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
+\fBshell\fP
+  Shell into an element's sandbox environment
+  See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command.
 .PP
 \fBsource\fP
   Manipulate sources for an element
   See \fBbst-source(1)\fP for full documentation on the \fBsource\fP command.
 .PP
-\fBpush\fP
-  COMMAND OBSOLETE - Push a built artifact
-  See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
-.PP
-\fBbuild\fP
-  Build elements in a pipeline
-  See \fBbst-build(1)\fP for full documentation on the \fBbuild\fP command.
-.PP
-\fBhelp\fP
-  Print usage information
-  See \fBbst-help(1)\fP for full documentation on the \fBhelp\fP command.
+\fBworkspace\fP
+  Manipulate developer workspaces
+  See \fBbst-workspace(1)\fP for full documentation on the \fBworkspace\fP command.
 .PP
 \fBartifact\fP
   Manipulate cached artifacts
@@ -112,14 +111,18 @@ Cache artifact build tree content on creation
   COMMAND OBSOLETE - Fetch sources in a pipeline
   See \fBbst-fetch(1)\fP for full documentation on the \fBfetch\fP command.
 .PP
-\fBshell\fP
-  Shell into an element's sandbox environment
-  See \fBbst-shell(1)\fP for full documentation on the \fBshell\fP command.
-.PP
-\fBinit\fP
-  Initialize a new BuildStream project
-  See \fBbst-init(1)\fP for full documentation on the \fBinit\fP command.
+\fBtrack\fP
+  COMMAND OBSOLETE - Track new source references
+  See \fBbst-track(1)\fP for full documentation on the \fBtrack\fP command.
 .PP
 \fBcheckout\fP
   COMMAND OBSOLETE - Checkout a built artifact
   See \fBbst-checkout(1)\fP for full documentation on the \fBcheckout\fP command.
+.PP
+\fBpull\fP
+  COMMAND OBSOLETE - Pull a built artifact
+  See \fBbst-pull(1)\fP for full documentation on the \fBpull\fP command.
+.PP
+\fBpush\fP
+  COMMAND OBSOLETE - Push a built artifact
+  See \fBbst-push(1)\fP for full documentation on the \fBpush\fP command.
diff --git a/src/buildstream/_context.py b/src/buildstream/_context.py
index c29910418..286ed6d3d 100644
--- a/src/buildstream/_context.py
+++ b/src/buildstream/_context.py
@@ -121,6 +121,9 @@ class Context():
         # What to do when a build fails in non interactive mode
         self.sched_error_action = None
 
+        # Maximum jobs per build
+        self.build_max_jobs = None
+
         # Size of the artifact cache in bytes
         self.config_cache_quota = None
 
@@ -205,7 +208,7 @@ class Context():
                             "artifactdir is obsolete")
 
         defaults.validate_keys([
-            'cachedir', 'sourcedir', 'builddir', 'logdir', 'scheduler',
+            'cachedir', 'sourcedir', 'builddir', 'logdir', 'scheduler', 'build',
             'artifacts', 'source-caches', 'logging', 'projects', 'cache', 'prompt',
             'workspacedir', 'remote-execution',
         ])
@@ -312,6 +315,11 @@ class Context():
         self.sched_pushers = scheduler.get_int('pushers')
         self.sched_network_retries = scheduler.get_int('network-retries')
 
+        # Load build config
+        build = defaults.get_mapping('build')
+        build.validate_keys(['max-jobs'])
+        self.build_max_jobs = build.get_int('max-jobs')
+
         # Load per-projects overrides
         self._project_overrides = defaults.get_mapping('projects', default={})
 
diff --git a/src/buildstream/_frontend/app.py b/src/buildstream/_frontend/app.py
index 0479b8c19..f04e9595e 100644
--- a/src/buildstream/_frontend/app.py
+++ b/src/buildstream/_frontend/app.py
@@ -191,6 +191,7 @@ class App():
             'fetchers': 'sched_fetchers',
             'builders': 'sched_builders',
             'pushers': 'sched_pushers',
+            'max_jobs': 'build_max_jobs',
             'network_retries': 'sched_network_retries',
             'pull_buildtrees': 'pull_buildtrees',
             'cache_buildtrees': 'cache_buildtrees'
diff --git a/src/buildstream/_frontend/cli.py b/src/buildstream/_frontend/cli.py
index fda81598d..1f5d500a8 100644
--- a/src/buildstream/_frontend/cli.py
+++ b/src/buildstream/_frontend/cli.py
@@ -241,6 +241,8 @@ def print_version(ctx, param, value):
               help="Maximum simultaneous build tasks")
 @click.option('--pushers', type=click.INT, default=None,
               help="Maximum simultaneous upload tasks")
+@click.option('--max-jobs', type=click.INT, default=None,
+              help="Number of parallel jobs allowed for a given build task")
 @click.option('--network-retries', type=click.INT, default=None,
               help="Maximum retries for network tasks")
 @click.option('--no-interactive', is_flag=True, default=False,
diff --git a/src/buildstream/_project.py b/src/buildstream/_project.py
index 97a2c4f77..a2ce5ae91 100644
--- a/src/buildstream/_project.py
+++ b/src/buildstream/_project.py
@@ -805,8 +805,13 @@ class Project():
         # Based on some testing (mainly on AWS), maximum effective
         # max-jobs value seems to be around 8-10 if we have enough cores
         # users should set values based on workload and build infrastructure
-        platform = Platform.get_platform()
-        output.base_variables['max-jobs'] = str(platform.get_cpu_count(8))
+        if self._context.build_max_jobs == 0:
+            # User requested automatic max-jobs
+            platform = Platform.get_platform()
+            output.base_variables['max-jobs'] = str(platform.get_cpu_count(8))
+        else:
+            # User requested explicit max-jobs setting
+            output.base_variables['max-jobs'] = str(self._context.build_max_jobs)
 
         # Export options into variables, if that was requested
         output.options.export_variables(output.base_variables)
diff --git a/src/buildstream/data/userconfig.yaml b/src/buildstream/data/userconfig.yaml
index 34fd300d1..a73c1ce44 100644
--- a/src/buildstream/data/userconfig.yaml
+++ b/src/buildstream/data/userconfig.yaml
@@ -78,6 +78,20 @@ scheduler:
 
 
 #
+# Build related configuration
+#
+build:
+
+  #
+  # Maximum number of jobs to run per build task.
+  #
+  # The default behavior when this is set to 0, is to use the
+  # maximum number of threads available, with a maximum of 8.
+  #
+  max-jobs: 0
+
+
+#
 #    Logging
 #
 logging:
diff --git a/tests/frontend/completions.py b/tests/frontend/completions.py
index 773eec040..3619242ac 100644
--- a/tests/frontend/completions.py
+++ b/tests/frontend/completions.py
@@ -35,6 +35,7 @@ MAIN_OPTIONS = [
     "--error-lines ",
     "--fetchers ",
     "--log-file ",
+    "--max-jobs ",
     "--message-lines ",
     "--network-retries ",
     "--no-colors ",
diff --git a/tests/frontend/show.py b/tests/frontend/show.py
index 756fe1786..55691a5c6 100644
--- a/tests/frontend/show.py
+++ b/tests/frontend/show.py
@@ -465,3 +465,54 @@ def test_format_deps(cli, datafiles, dep_kind, expected_deps):
     if result.output.strip() != expected:
         raise AssertionError("Expected output:\n{}\nInstead received output:\n{}"
                              .format(expected, result.output))
+
+
+# This tests the resolved value of the 'max-jobs' variable,
+# ensuring at least that the variables are resolved according
+# to how the user has configured max-jobs
+#
+@pytest.mark.datafiles(os.path.join(DATA_DIR, 'project'))
+@pytest.mark.parametrize("cli_value, config_value", [
+    (None, None),
+    (None, '16'),
+    ('16', None),
+    ('5', '16'),
+    ('0', '16'),
+    ('16', '0'),
+])
+def test_max_jobs(cli, datafiles, cli_value, config_value):
+    project = str(datafiles)
+    target = 'target.bst'
+
+    # Specify `--max-jobs` if this test sets it
+    args = []
+    if cli_value is not None:
+        args += ['--max-jobs', cli_value]
+    args += ['show', '--deps', 'none', '--format', '%{vars}', target]
+
+    # Specify `max-jobs` in user configuration if this test sets it
+    if config_value is not None:
+        cli.configure({
+            'build': {
+                'max-jobs': config_value
+            }
+        })
+
+    result = cli.run(project=project, silent=True, args=args)
+    result.assert_success()
+    loaded = _yaml.load_data(result.output)
+    loaded_value = loaded.get_int('max-jobs')
+
+    # We expect the value provided on the command line to take
+    # precedence over the configuration file value, if specified.
+    #
+    # If neither are specified then we expect the default
+    expected_value = cli_value or config_value or '0'
+
+    if expected_value == '0':
+        # If we are expecting the automatic behavior of using the maximum
+        # number of cores available, just check that it is a value > 0
+        assert loaded_value > 0, "Automatic setting of max-jobs didnt work"
+    else:
+        # Check that we got the explicitly set value
+        assert loaded_value == int(expected_value)