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 <frantisek.hrbata@espressif.com>

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

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