Merge branch 'fix/minimal_build_no_main' into 'master'

fix(build): ensure the main component exists when MINIMAL_BUILD is enabled

Closes IDFGH-17219 and DOC-13790

See merge request espressif/esp-idf!45770

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 <cmake_minimal_component_cmakelists>`.
 
+.. note::
+
+   A project without a ``main`` component cannot use the ``MINIMAL_BUILD`` :ref:`build property <cmake-build-properties>`, 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
 ---------------------------------------

docs/zh_CN/api-guides/build-system.rst

@@ -264,6 +264,9 @@ ESP-IDF 适用于 Python 3.10 以上版本。
 2. 在项目 CMakeLists.txt 文件中设置 ``EXTRA_COMPONENT_DIRS``，并添加重命名后的 ``main`` 目录。
 3. 在组件的 CMakeLists.txt 文件中设置 ``COMPONENT_REQUIRES`` 或 ``COMPONENT_PRIV_REQUIRES`` 以指定依赖项。
 
+.. note::
+
+   没有 ``main`` 组件的项目无法使用 ``MINIMAL_BUILD`` :ref:`构建属性 <cmake-build-properties>`，因为该属性的生效明确依赖 ``main`` 组件的存在。因此，请确保在未包含 ``main`` 组件的项目中不要设置 ``MINIMAL_BUILD`` 属性。
 
 覆盖默认的构建规范
 ---------------------------------------

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()

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'
+    )