docs: add section on renaming main component

diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
index e142b2a71e121192b5be2c500673a677e2fdeda5..3d16539e93b38d41873a296a5f16569770280321 100644 (file)
--- a/docs/en/api-guides/build-system-cmake.rst
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -209,7 +209,7 @@ This example "myProject" contains the following elements:
 
 - Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
 
-- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS`` in the top-level CMakeLists.txt) to look for components in other places. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
+- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the CMake variable ``COMPONENT_DIRS`` includes this component but you can modify this variable. Alternatively, ``EXTRA_COMPONENT_DIRS`` can be set in the top-level CMakeLists.txt to look for components in other places. See the :ref:`renaming main <rename-main-cmake>` section for more info. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
 
 - "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
 
@@ -263,8 +263,25 @@ Any paths in these variables can be absolute paths, or set relative to the proje
 
 To set these variables, use the `cmake set command <cmake set_>`_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line.
 
+.. _rename-main-cmake:
+
+Renaming ``main`` component
+----------------------------
+
+The build system provides special treatment to the ``main`` component. It is a component that gets automatically added to the build provided
+that it is in the expected location, `${PROJECT_PATH}/main`. All other components in the build are also added as its dependencies,
+saving the user from hunting down dependencies and providing a build that works right out of the box. Renaming the ``main`` component
+causes the loss of these behind-the-scences heavy lifting, requiring the user to specify the location of the newly renamed component
+and manually specifying its dependencies. Specifically, the steps to renaming ``main`` are as follows:
+
+1. Rename ``main`` directory.
+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 ``COMPONENT_REQUIRES`` or ``COMPONENT_PRIV_REQUIRES``.
+
+
 .. _component-directories-cmake:
 
+
 Component CMakeLists Files
 ==========================