From 11924d76cb8b81c0b060bb1cd4b3a40ef44caff2 Mon Sep 17 00:00:00 2001 From: Renz Christian Bagaporo Date: Mon, 17 Jun 2019 12:14:02 +0800 Subject: [PATCH] cmake: clarify build trimming docs How idf_build_component and the COMPONENTS argument to idf_build_process interact is not clear/misleading. Clarify their interaction in the docs. Closes: https://github.com/espressif/esp-idf/issues/3630 --- docs/en/api-guides/build-system-cmake.rst | 10 ++++++++-- tools/cmake/build.cmake | 21 ++++++++++++++++----- 2 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst index 08f9e3a396..455149fec5 100644 --- a/docs/en/api-guides/build-system-cmake.rst +++ b/docs/en/api-guides/build-system-cmake.rst @@ -943,7 +943,10 @@ the first element/member instead. idf_build_component(component_dir) -Add a directory *component_dir* that contains a component to the build. +Present a directory *component_dir* that contains a component to the build system. Relative paths are converted to absolute paths with respect to current directory. +All calls to this command must be performed before `idf_build_process`. + +This command does not guarantee that the component will be processed during build (see the `COMPONENTS` argument description for `idf_build_process`) .. code-block:: none @@ -970,7 +973,10 @@ The call requires the target chip to be specified with *target* argument. Option - SDKCONFIG - output path of generated sdkconfig file; defaults to PROJECT_DIR/sdkconfig or CMAKE_SOURCE_DIR/sdkconfig depending if PROJECT_DIR is set - SDKCONFIG_DEFAULTS - defaults file to use for the build; defaults to empty - BUILD_DIR - directory to place ESP-IDF build-related artifacts, such as generated binaries, text files, components; defaults to CMAKE_BINARY_DIR -- COMPONENTS - starting components for trimming the build; components not in the list are automatically if they are required in the expanded dependency tree +- COMPONENTS - select components to process among the components known by the build system (added via `idf_build_component`). This argument is used to trim the build. + Other components are automatically added if they are required in the dependency chain, i.e. + the public and private requirements of the components in this list are automatically added, and in turn the public and private requirements of those requirements, + so on and so forth. If not specified, all components known to the build system are processed. .. code-block:: none diff --git a/tools/cmake/build.cmake b/tools/cmake/build.cmake index ff43ba1023..5383581f12 100644 --- a/tools/cmake/build.cmake +++ b/tools/cmake/build.cmake @@ -163,12 +163,14 @@ endfunction() # idf_build_component # -# @brief Specify component directory for the build system to process. +# @brief Present a directory that contains a component to the build system. # Relative paths are converted to absolute paths with respect to current directory. -# Any component that needs to be processed has to be specified using this -# command before calling idf_build_process. +# All calls to this command must be performed before idf_build_process. # -# @param[in] component_dir directory of the component to process +# @note This command does not guarantee that the component will be processed +# during build (see the COMPONENTS argument description for command idf_build_process) +# +# @param[in] component_dir directory of the component function(idf_build_component component_dir) idf_build_get_property(prefix __PREFIX) __component_add(${component_dir} ${prefix} 0) @@ -335,7 +337,16 @@ endfunction() # @param[in, optional] SDKCONFIG_DEFAULTS (single value) config defaults file to use for the build; defaults # to none (Kconfig defaults or previously generated config are used) # @param[in, optional] BUILD_DIR (single value) directory for build artifacts; defautls to CMAKE_BINARY_DIR -# @param[in, optional] COMPONENTS (multivalue) starting components for trimming build +# @param[in, optional] COMPONENTS (multivalue) select components to process among the components +# known by the build system +# (added via `idf_build_component`). This argument is used to trim the build. +# Other components are automatically added if they are required +# in the dependency chain, i.e. +# the public and private requirements of the components in this list +# are automatically added, and in +# turn the public and private requirements of those requirements, +# so on and so forth. If not specified, all components known to the build system +# are processed. macro(idf_build_process target) set(options) set(single_value PROJECT_DIR PROJECT_VER PROJECT_NAME BUILD_DIR SDKCONFIG SDKCONFIG_DEFAULTS)