CLI Reference
Tools for building ESP-IDF related apps.Some CLI options can be expanded by the following placeholders, like “–work-dir”, “–build-dir”, etc.: - @t: would be replaced by the target chip type - @w: would be replaced by the wildcard, usually the sdkconfig - @n: would be replaced by the app name - @f: would be replaced by the escaped app path (replaced “/” to “_”) - @v: Would be replaced by the ESP-IDF version like 5_3_0 - @i: would be replaced by the build index (only available in build command) - @p: would be replaced by the parallel index (only available in build command)
usage: idf-build-apps [-h] {find,build} ...
Positional Arguments
- action
Possible choices: find, build
Sub-commands
find
Undocumented
idf-build-apps find [-h] [-c CONFIG_FILE] [-p PATHS [PATHS ...]] [-t TARGET]
[--build-system {cmake,make}] [--recursive]
[--exclude EXCLUDE [EXCLUDE ...]] [--work-dir WORK_DIR]
[--build-dir BUILD_DIR] [--build-log BUILD_LOG]
[--size-file SIZE_FILE] [--config CONFIG [CONFIG ...]]
[--override-sdkconfig-items [OVERRIDE_SDKCONFIG_ITEMS]]
[--override-sdkconfig-files [OVERRIDE_SDKCONFIG_FILES]]
[--sdkconfig-defaults SDKCONFIG_DEFAULTS] [-v]
[--log-file LOG_FILE] [--check-warnings]
[--manifest-file MANIFEST_FILE [MANIFEST_FILE ...]]
[--manifest-rootpath MANIFEST_ROOTPATH]
[--check-manifest-rules]
[--default-build-targets DEFAULT_BUILD_TARGETS [DEFAULT_BUILD_TARGETS ...]]
[--modified-components MODIFIED_COMPONENTS]
[--modified-files MODIFIED_FILES]
[-ic IGNORE_APP_DEPENDENCIES_COMPONENTS]
[-if IGNORE_APP_DEPENDENCIES_FILEPATTERNS] [--no-color]
[-o OUTPUT]
Named Arguments
- -c, --config-file
Path to the default configuration file, toml file
- -p, --paths
One or more paths to look for apps
- -t, --target
filter apps by given target
- --build-system
Possible choices: cmake, make
filter apps by given build system
Default: “cmake”
- --recursive
Look for apps in the specified paths recursively
Default: False
- --exclude
Ignore specified path (if –recursive is given)
- --work-dir
If set, the app is first copied into the specified directory, and then built. If not set, the work directory is the directory of the app. Can expand placeholders
- --build-dir
If set, specifies the build directory name. Can be either a name relative to the work directory, or an absolute path. Can expand placeholders
Default: “build”
- --build-log
Relative to build dir. The build log will be written to this file instead of sys.stdout if specified. Can expand placeholders
- --size-file
Relative to build dir. The size json will be written to this file if specified. Can expand placeholders
- --config
Adds configurations (sdkconfig file names) to build. This can either be FILENAME[=NAME] or FILEPATTERN. FILENAME is the name of the sdkconfig file, relative to the project directory, to be used. Optional NAME can be specified, which can be used as a name of this configuration. FILEPATTERN is the name of the sdkconfig file, relative to the project directory, with at most one wildcard. The part captured by the wildcard is used as the name of the configuration
- --override-sdkconfig-items
The –override-sdkconfig-items option is a comma-separated list that permits the overriding of specific configuration items defined in the SDK’s sdkconfig file and Kconfig using a command-line argument. The sdkconfig items specified here override the same sdkconfig item defined in the –override-sdkconfig-files, if exists.
- --override-sdkconfig-files
“The –override-sdkconfig-files option is a comma-separated list, which provides an alternative (alt: –override-sdkconfig-items) approach for overriding SDK configuration items. The filepath may be global or relative to the root.
- --sdkconfig-defaults
semicolon-separated string, pass to idf.py -DSDKCONFIG_DEFAULTS if specified, also could be set via environment variables “SDKCONFIG_DEFAULTS”
- -v, --verbose
Increase the logging level of the whole process. Can be specified multiple times. By default set to WARNING level. Specify once to set to INFO level. Specify twice or more to set to DEBUG level
Default: 0
- --log-file
Write the log to the specified file, instead of stderr
- --check-warnings
If set, fail the build if warnings are found
Default: False
- --manifest-file
Manifest files which specify the build test rules of the apps
- --manifest-rootpath
Root directory for calculating the realpath of the relative path defined in the manifest files. Would use the current directory if not set
- --check-manifest-rules
Exit with error if any of the manifest rules does not exist on your filesystem
Default: False
- --default-build-targets
space-separated list of supported targets. Targets supported in current ESP-IDF branch (except preview ones) would be used if this option is not set.
- --modified-components
semicolon-separated string which specifies the modified components. app with depends_components set in the corresponding manifest files would only be built if depends on any of the specified components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- --modified-files
semicolon-separated string which specifies the modified files. app with depends_filepatterns set in the corresponding manifest files would only be built if any of the specified file pattern matches any of the specified modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- -ic, --ignore-app-dependencies-components
semicolon-separated string which specifies the modified components used for ignoring checking the app dependencies. The depends_components and depends_filepatterns set in the manifest files will be ignored when any of the specified components matches any of the modified components. Must be used together with –modified-components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- -if, --ignore-app-dependencies-filepatterns
semicolon-separated string which specifies the file patterns used for ignoring checking the app dependencies. The depends_components and depends_filepatterns set in the manifest files will be ignored when any of the specified file patterns matches any of the modified files. Must be used together with –modified-files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- --no-color
enable colored output by default on UNIX-like systems. enable this flag to make the logs uncolored.
Default: False
- -o, --output
Print the found apps to the specified file instead of stdout
build
Undocumented
idf-build-apps build [-h] [-c CONFIG_FILE] [-p PATHS [PATHS ...]] [-t TARGET]
[--build-system {cmake,make}] [--recursive]
[--exclude EXCLUDE [EXCLUDE ...]] [--work-dir WORK_DIR]
[--build-dir BUILD_DIR] [--build-log BUILD_LOG]
[--size-file SIZE_FILE] [--config CONFIG [CONFIG ...]]
[--override-sdkconfig-items [OVERRIDE_SDKCONFIG_ITEMS]]
[--override-sdkconfig-files [OVERRIDE_SDKCONFIG_FILES]]
[--sdkconfig-defaults SDKCONFIG_DEFAULTS] [-v]
[--log-file LOG_FILE] [--check-warnings]
[--manifest-file MANIFEST_FILE [MANIFEST_FILE ...]]
[--manifest-rootpath MANIFEST_ROOTPATH]
[--check-manifest-rules]
[--default-build-targets DEFAULT_BUILD_TARGETS [DEFAULT_BUILD_TARGETS ...]]
[--modified-components MODIFIED_COMPONENTS]
[--modified-files MODIFIED_FILES]
[-ic IGNORE_APP_DEPENDENCIES_COMPONENTS]
[-if IGNORE_APP_DEPENDENCIES_FILEPATTERNS] [--no-color]
[--build-verbose] [--parallel-count PARALLEL_COUNT]
[--parallel-index PARALLEL_INDEX] [--dry-run]
[--keep-going] [--no-preserve]
[--collect-size-info COLLECT_SIZE_INFO]
[--collect-app-info COLLECT_APP_INFO]
[--ignore-warning-str IGNORE_WARNING_STR [IGNORE_WARNING_STR ...]]
[--ignore-warning-file IGNORE_WARNING_FILE]
[--copy-sdkconfig] [--junitxml JUNITXML]
Named Arguments
- -c, --config-file
Path to the default configuration file, toml file
- -p, --paths
One or more paths to look for apps
- -t, --target
filter apps by given target
- --build-system
Possible choices: cmake, make
filter apps by given build system
Default: “cmake”
- --recursive
Look for apps in the specified paths recursively
Default: False
- --exclude
Ignore specified path (if –recursive is given)
- --work-dir
If set, the app is first copied into the specified directory, and then built. If not set, the work directory is the directory of the app. Can expand placeholders
- --build-dir
If set, specifies the build directory name. Can be either a name relative to the work directory, or an absolute path. Can expand placeholders
Default: “build”
- --build-log
Relative to build dir. The build log will be written to this file instead of sys.stdout if specified. Can expand placeholders
- --size-file
Relative to build dir. The size json will be written to this file if specified. Can expand placeholders
- --config
Adds configurations (sdkconfig file names) to build. This can either be FILENAME[=NAME] or FILEPATTERN. FILENAME is the name of the sdkconfig file, relative to the project directory, to be used. Optional NAME can be specified, which can be used as a name of this configuration. FILEPATTERN is the name of the sdkconfig file, relative to the project directory, with at most one wildcard. The part captured by the wildcard is used as the name of the configuration
- --override-sdkconfig-items
The –override-sdkconfig-items option is a comma-separated list that permits the overriding of specific configuration items defined in the SDK’s sdkconfig file and Kconfig using a command-line argument. The sdkconfig items specified here override the same sdkconfig item defined in the –override-sdkconfig-files, if exists.
- --override-sdkconfig-files
“The –override-sdkconfig-files option is a comma-separated list, which provides an alternative (alt: –override-sdkconfig-items) approach for overriding SDK configuration items. The filepath may be global or relative to the root.
- --sdkconfig-defaults
semicolon-separated string, pass to idf.py -DSDKCONFIG_DEFAULTS if specified, also could be set via environment variables “SDKCONFIG_DEFAULTS”
- -v, --verbose
Increase the logging level of the whole process. Can be specified multiple times. By default set to WARNING level. Specify once to set to INFO level. Specify twice or more to set to DEBUG level
Default: 0
- --log-file
Write the log to the specified file, instead of stderr
- --check-warnings
If set, fail the build if warnings are found
Default: False
- --manifest-file
Manifest files which specify the build test rules of the apps
- --manifest-rootpath
Root directory for calculating the realpath of the relative path defined in the manifest files. Would use the current directory if not set
- --check-manifest-rules
Exit with error if any of the manifest rules does not exist on your filesystem
Default: False
- --default-build-targets
space-separated list of supported targets. Targets supported in current ESP-IDF branch (except preview ones) would be used if this option is not set.
- --modified-components
semicolon-separated string which specifies the modified components. app with depends_components set in the corresponding manifest files would only be built if depends on any of the specified components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- --modified-files
semicolon-separated string which specifies the modified files. app with depends_filepatterns set in the corresponding manifest files would only be built if any of the specified file pattern matches any of the specified modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- -ic, --ignore-app-dependencies-components
semicolon-separated string which specifies the modified components used for ignoring checking the app dependencies. The depends_components and depends_filepatterns set in the manifest files will be ignored when any of the specified components matches any of the modified components. Must be used together with –modified-components. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- -if, --ignore-app-dependencies-filepatterns
semicolon-separated string which specifies the file patterns used for ignoring checking the app dependencies. The depends_components and depends_filepatterns set in the manifest files will be ignored when any of the specified file patterns matches any of the modified files. Must be used together with –modified-files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list
- --no-color
enable colored output by default on UNIX-like systems. enable this flag to make the logs uncolored.
Default: False
- --build-verbose
Enable verbose output of the build system
Default: False
- --parallel-count
Number of parallel build jobs. Note that this script doesn’t start all jobs simultaneously. It needs to be executed multiple times with same value of –parallel-count and different values of –parallel-index
Default: 1
- --parallel-index
Index (1-based) of the job, out of the number specified by –parallel-count
Default: 1
- --dry-run
Don’t actually build, only print the build commands
Default: False
- --keep-going
Don’t exit immediately when a build fails
Default: False
- --no-preserve
Don’t preserve the build directory after a successful build
Default: False
- --collect-size-info
write size info json file while building into the specified file. each line is a json object. Can expand placeholder @p
- --collect-app-info
write app info json file while building into the specified file. each line is a json object. Can expand placeholder @p
- --ignore-warning-str
Ignore the warning string that match the specified regex in the build output
- --ignore-warning-file
Ignore the warning strings in the specified file. Each line should be a regex string
- --copy-sdkconfig
Copy the sdkconfig file to the build directory
Default: False
- --junitxml
Path to the junitxml file. If specified, the junitxml file will be generated. Can expand placeholder @p