From 795904a41c22a7ef3ccfc2753090d5d109226847 Mon Sep 17 00:00:00 2001 From: Frantisek Hrbata Date: Mon, 9 Feb 2026 13:11:51 +0100 Subject: [PATCH] fix(build): ensure the main component exists when MINIMAL_BUILD is enabled The minimal build property is simply a shorthand for `set(COMPONENTS main)`. The issue is that there is currently no check to verify whether the `main` component actually exists or is known to the build system. If the `main` component is not present, print an error message along with suggestions on how to fix this inconsistency. Closes https://github.com/espressif/esp-idf/issues/18219 Signed-off-by: Frantisek Hrbata --- docs/en/api-guides/build-system.rst | 3 +++ tools/cmake/project.cmake | 11 +++++++++++ tools/test_build_system/test_components.py | 23 +++++++++++++++++++++- 3 files changed, 36 insertions(+), 1 deletion(-) diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst index 5fc8159977..788a174c75 100644 --- a/docs/en/api-guides/build-system.rst +++ b/docs/en/api-guides/build-system.rst @@ -264,6 +264,9 @@ The build system provides special treatment to the ``main`` component. It is a c 2. Set ``EXTRA_COMPONENT_DIRS`` in the project CMakeLists.txt to include the renamed ``main`` directory. 3. Specify the dependencies in the renamed component's CMakeLists.txt file via REQUIRES or PRIV_REQUIRES arguments :ref:`on component registration `. +.. note:: + + A project without a ``main`` component cannot use the ``MINIMAL_BUILD`` :ref:`build property `, as this property explicitly relies on the presence of the ``main`` component. Ensure that the ``MINIMAL_BUILD`` build property is not set for projects that do not include a ``main`` component. Overriding Default Build Specifications --------------------------------------- diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake index b3da621083..24a0e466b7 100644 --- a/tools/cmake/project.cmake +++ b/tools/cmake/project.cmake @@ -506,6 +506,17 @@ function(__project_init components_var test_components_var) set(minimal_build OFF) idf_build_set_property(MINIMAL_BUILD OFF) else() + # The minimal build feature is enabled; check whether the 'main' + # component target exists, ensuring that the component is + # recognized by the build system. + idf_build_get_property(prefix __PREFIX) + set(main_component_target ___${prefix}_main) + if(NOT TARGET ${main_component_target}) + message(FATAL_ERROR "MINIMAL_BUILD is enabled but component main was not found. " + "Please ensure the main component exists (in '${CMAKE_CURRENT_LIST_DIR}/main' " + "or disable MINIMAL_BUILD, or explicitly set the COMPONENTS variable.") + endif() + set(COMPONENTS main ${TEST_COMPONENTS}) set(minimal_build ON) endif() diff --git a/tools/test_build_system/test_components.py b/tools/test_build_system/test_components.py index 9828bec316..777fe87650 100644 --- a/tools/test_build_system/test_components.py +++ b/tools/test_build_system/test_components.py @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD +# SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD # SPDX-License-Identifier: Apache-2.0 import json import logging @@ -579,3 +579,24 @@ def test_component_validation_with_common_platform_example(idf_py: IdfPyFunc, te assert re_source.search(ret.stderr) is None, ( f'Unexpected source file ownership warning for common path: {ret.stderr}' ) + + +def test_minimal_build_without_main_component(idf_py: IdfPyFunc, test_app_copy: Path) -> None: + logging.info('Verify that the build fails when using `MINIMAL_BUILD` without main component') + + # Rename main to no_main + shutil.move(test_app_copy / 'main', test_app_copy / 'no_main') + + # Set minimal build property + replace_in_file( + (test_app_copy / 'CMakeLists.txt'), + '# placeholder_after_include_project_cmake', + 'idf_build_set_property(MINIMAL_BUILD ON)', + ) + + # Reconfigure should fail + ret = idf_py('reconfigure', check=False) + + assert 'MINIMAL_BUILD is enabled but component main was not found.' in ret.stderr, ( + 'Reconfiguration should fail with missing main component and MINIMAL_BUILD ON' + )