feat(tools): add -j/--jobs option to idf.py

Add a global -j/--jobs option to idf.py that sets the number of parallel
build jobs passed to the underlying build tool. Previously parallelism was
only configurable via the IDF_PY_BUILD_JOBS environment variable, and only
for the Ninja generator.

The option applies to both Ninja and Make and defaults to IDF_PY_BUILD_JOBS
when not given, so the environment variable keeps working as before.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tools/idf_py_actions/constants.py

@@ -29,7 +29,9 @@ GENERATORS: dict[str, str | dict | list] = collections.OrderedDict(
 if os.name != 'nt':
     MAKE_CMD = 'gmake' if platform.system() == 'FreeBSD' else 'make'
     GENERATORS['Unix Makefiles'] = {
-        'command': [MAKE_CMD, '-j', str(multiprocessing.cpu_count() + 2)],
+        # Make, unlike Ninja, does not parallelize by default; run_target() applies this as -j.
+        'default_jobs': multiprocessing.cpu_count() + 2,
+        'command': [MAKE_CMD],
         'version': [MAKE_CMD, '--version'],
         'dry_run': [MAKE_CMD, '-n'],
         'verbose_flag': 'VERBOSE=1',

tools/idf_py_actions/core_ext.py

@@ -537,6 +537,13 @@ def action_extensions(base_actions: dict, project_path: str) -> Any:
                 'help': 'CMake generator.',
                 'type': click.Choice(GENERATORS.keys()),
             },
+            {
+                'names': ['-j', '--jobs'],
+                'help': 'Number of parallel build jobs passed to the build tool (Ninja or Make).',
+                'envvar': 'IDF_PY_BUILD_JOBS',
+                'type': click.IntRange(min=1),
+                'default': None,
+            },
             {
                 'names': ['--dry-run'],
                 'help': "Only process arguments, but don't execute actions.",

tools/idf_py_actions/global_options.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+# SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
 # SPDX-License-Identifier: Apache-2.0
 global_options = [{
     'names': ['-D', '--define-cache-entry'],

tools/idf_py_actions/tools.py

@@ -667,18 +667,13 @@ def run_target(
 
     generator_cmd = list(GENERATORS[args.generator]['command'])
 
-    if args.generator == 'Ninja':
-        parallel_level = os.environ.get('IDF_PY_BUILD_JOBS')
-        if parallel_level:
-            try:
-                jobs = int(parallel_level)
-            except ValueError as e:
-                raise FatalError('Environment variable IDF_PY_BUILD_JOBS must be a positive integer') from e
+    # Parallel jobs from -j/--jobs (or IDF_PY_BUILD_JOBS), falling back to the generator's default.
+    jobs = getattr(args, 'jobs', None)
+    if jobs is None:
+        jobs = GENERATORS[args.generator].get('default_jobs')
 
-            if jobs <= 0:
-                raise FatalError('Environment variable IDF_PY_BUILD_JOBS must be a positive integer')
-
-            generator_cmd += ['-j', str(jobs)]
+    if jobs is not None:
+        generator_cmd += ['-j', str(jobs)]
 
     if args.verbose:
         generator_cmd += [GENERATORS[args.generator]['verbose_flag']]