Merge branch 'contrib/github_pr_18871' into 'master'

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

Closes IDFGH-18013

See merge request espressif/esp-idf!51409

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

@@ -536,6 +536,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,8 +1,10 @@
-# 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'],
-    'help': 'Create a cmake cache entry.',
-    'scope': 'global',
-    'multiple': True,
-}]
+global_options = [
+    {
+        'names': ['-D', '--define-cache-entry'],
+        'help': 'Create a cmake cache entry.',
+        'scope': 'global',
+        'multiple': True,
+    }
+]

tools/idf_py_actions/tools.py

@@ -646,18 +646,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']]