From 2aee18d8275d20171fe2b765c4de3877cf341849 Mon Sep 17 00:00:00 2001 From: Fu Hanxi Date: Wed, 15 Apr 2026 13:24:16 +0200 Subject: [PATCH] feat(build): support env var IDF_PY_BUILD_JOBS for ninja jobs --- .gitlab/ci/common.yml | 4 ++++ docs/en/api-guides/build-system.rst | 8 ++++++++ docs/zh_CN/api-guides/build-system.rst | 8 ++++++++ tools/idf_py_actions/tools.py | 15 ++++++++++++++- 4 files changed, 34 insertions(+), 1 deletion(-) diff --git a/.gitlab/ci/common.yml b/.gitlab/ci/common.yml index 2a9bafa5fc..a0e3479392 100644 --- a/.gitlab/ci/common.yml +++ b/.gitlab/ci/common.yml @@ -19,6 +19,10 @@ variables: # Common parameters for the 'make' during CI tests MAKEFLAGS: "-j5 --no-keep-going" + # By default, CI build jobs request and limit 4 CPU cores and 4 GB of memory + # https://github.com/ninja-build/ninja/blob/def9560a0b6d755936e615ce443a0aec45c39bdb/src/ninja.cc#L262 + # cpu_cores + 2 + IDF_PY_BUILD_JOBS: "6" # GitLab-CI environment # Thanks to pack-objects cache, clone strategy should behave faster than fetch diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index ededb11ac0..3ec4b03488 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -77,6 +77,14 @@ In the above list, the ``cmake`` command configures the project and generates bu It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration. +When using ``idf.py`` with the Ninja generator, you can cap the number of parallel build jobs by setting the ``IDF_PY_BUILD_JOBS`` environment variable. For example: + +.. code-block:: bash + + IDF_PY_BUILD_JOBS=6 idf.py build + +If you invoke CMake, ``ninja``, or ``make`` directly instead of ``idf.py``, use their native options or environment variables to control parallelism. + If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands. For example, running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``. .. note:: diff --git a/docs/zh_CN/api-guides/build-system.rst b/docs/zh_CN/api-guides/build-system.rst index 65b2f7109e..c51a3e3498 100644 --- a/docs/zh_CN/api-guides/build-system.rst +++ b/docs/zh_CN/api-guides/build-system.rst @@ -77,6 +77,14 @@ idf.py 没有必要多次运行 ``cmake``。第一次构建后，往后每次只需运行 ``ninja`` 即可。如果项目需要重新配置，``ninja`` 会自动重新调用 ``cmake``。 +使用 Ninja 生成器配合 ``idf.py`` 时，可以通过设置环境变量 ``IDF_PY_BUILD_JOBS`` 来限制并行构建任务数。例如： + +.. code-block:: bash + + IDF_PY_BUILD_JOBS=6 idf.py build + +如果不是通过 ``idf.py``，而是直接调用 CMake、``ninja`` 或 ``make``，则请使用它们各自原生的并行控制选项或环境变量。 + 若在 CMake 中使用 ``ninja`` 或 ``make``，则多数 ``idf.py`` 子命令也会有其对应的目标，例如在构建目录下运行 ``make menuconfig`` 或 ``ninja menuconfig`` 与运行 ``idf.py menuconfig`` 是相同的。 .. note:: diff --git a/tools/idf_py_actions/tools.py b/tools/idf_py_actions/tools.py index 2ab73dc937..f85d47b4a7 100644 --- a/tools/idf_py_actions/tools.py +++ b/tools/idf_py_actions/tools.py @@ -592,7 +592,20 @@ def run_target( if env is None: env = {} - generator_cmd = GENERATORS[args.generator]['command'] + 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 + + if jobs <= 0: + raise FatalError('Environment variable IDF_PY_BUILD_JOBS must be a positive integer') + + generator_cmd += ['-j', str(jobs)] if args.verbose: generator_cmd += [GENERATORS[args.generator]['verbose_flag']]