API Reference

class idf_build_apps.app.App(app_dir, target, sdkconfig_path=None, config_name=None, work_dir=None, build_dir='build', build_log_path=None, size_json_path=None, check_warnings=False, preserve=True, sdkconfig_defaults_str=None)

Bases: object

BUILD_SYSTEM = 'unknown'

FULL_NAME_PLACEHOLDER = '@f'

IDF_VERSION_PLACEHOLDER = '@v'

IGNORE_WARNS_REGEXES = []

INDEX_PLACEHOLDER = '@i'

LOG_DEBUG_LINES = 25

LOG_ERROR_WARNING_REGEX = re.compile('(?:error|warning):', re.IGNORECASE|re.MULTILINE)

MANIFEST = None

NAME_PLACEHOLDER = '@n'

PARALLEL_INDEX_PLACEHOLDER = '@p'

SDKCONFIG_LINE_REGEX = re.compile('^([^=]+)=\\"?([^\\"\\n]*)\\"?\\n*$')

TARGET_PLACEHOLDER = '@t'

WILDCARD_PLACEHOLDER = '@w'

property app_dir

Returns:

directory of the app

abstract build(manifest_rootpath=None, modified_components=None, modified_files=None, check_app_dependencies=False)

property build_dir

Returns:

build directory, either relative to the work directory (if relative path is used) or absolute path.

property build_log_path

property build_path

check_should_build(manifest_rootpath, check_app_dependencies, modified_components, modified_files)

property collect_app_info

property collect_size_info

property depends_components

property depends_filepatterns

classmethod is_app(path)

is_error_or_warning(line)

is_modified(modified_files)

property sdkconfig_files

property sdkconfig_files_defined_idf_target

property size_json_path

property supported_targets

to_json()

property verified_targets

property work_dir

Returns:

directory where the app should be copied to, prior to the build.

write_size_json()

class idf_build_apps.app.BuildOrNot

Bases: object

NO = 'no'

UNKNOWN = 'unknown'

YES = 'yes'

class idf_build_apps.app.CMakeApp(*args, **kwargs)

Bases: App

BUILD_SYSTEM = 'cmake'

CMAKE_PROJECT_LINE = 'include($ENV{IDF_PATH}/tools/cmake/project.cmake)'

SDKCONFIG_IGNORE_OPTS = ['TEST_GROUPS']

SDKCONFIG_TEST_OPTS = ['EXCLUDE_COMPONENTS', 'TEST_EXCLUDE_COMPONENTS', 'TEST_COMPONENTS']

build(manifest_rootpath=None, modified_components=None, modified_files=None, check_app_dependencies=False)

classmethod is_app(path)

class idf_build_apps.main.IdfBuildAppsCliFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: HelpFormatter

LINE_SEP = '$LINE_SEP$'

idf_build_apps.main.apply_config_args(args)

idf_build_apps.main.build_apps(apps, build_verbose=False, parallel_count=1, parallel_index=1, dry_run=False, keep_going=False, collect_size_info=None, collect_app_info=None, ignore_warning_strs=None, ignore_warning_file=None, copy_sdkconfig=False, manifest_rootpath=None, modified_components=None, modified_files=None, ignore_app_dependencies_filepatterns=None)

Build all the specified apps

Parameters:

• apps (list[App] | App) – list of apps to be built

• build_verbose (bool) – call --verbose in idf.py build or not

• parallel_count (int) – number of parallel tasks to run

• parallel_index (int) – index of the parallel task to run

• dry_run (bool) – simulate this run or not

• keep_going (bool) – keep building or not if one app’s build failed

• collect_size_info (TextIO | None) – file path to record all generated size files’ paths if specified

• collect_app_info (TextIO | None) – file path to record all the built apps’ info if specified

• ignore_warning_strs (list[str] | None) – ignore build warnings that matches any of the specified regex patterns

• ignore_warning_file (list[str] | None) – ignore build warnings that matches any of the lines of the regex patterns in the specified file

• copy_sdkconfig (bool) – copy the sdkconfig file to the build directory or not

• manifest_rootpath (str | None) – The root path of the manifest files. Usually the folders specified in the manifest files are relative paths. Use the current directory if not specified

• modified_components (list[str] | str | None) – modified components

• modified_files (list[str] | str | None) – modified files

• ignore_app_dependencies_filepatterns (list[str] | str | None) – file patterns that used for ignoring checking the component dependencies

Returns:

(exit_code, built_apps) if specified modified_components

Return type:

int, list[App]

Returns:

exit_code if not specified modified_components

Return type:

int

idf_build_apps.main.find_apps(paths, target, build_system='cmake', recursive=False, exclude_list=None, work_dir=None, build_dir='build', config_rules_str=None, build_log_path=None, size_json_path=None, check_warnings=False, preserve=True, manifest_rootpath=None, manifest_files=None, default_build_targets=None, modified_components=None, modified_files=None, ignore_app_dependencies_filepatterns=None, sdkconfig_defaults=None)

Find app directories in paths (possibly recursively), which contain apps for the given build system, compatible with the given target

Parameters:

• paths (list[str] | str) – list of app directories (can be / usually will be a relative path)

• target (str) – desired value of IDF_TARGET; apps incompatible with the given target are skipped.

• build_system (str) – name of the build system, now only support cmake

• recursive (bool) – Recursively search into the nested sub-folders if no app is found or not

• exclude_list (list[str] | None) – list of paths to be excluded from the recursive search

• work_dir (str | None) – directory where the app should be copied before building. Support placeholders

• build_dir (str) – directory where the build will be done. Support placeholders.

• config_rules_str (list[str] | str | None) – mapping of sdkconfig file name patterns to configuration names

• build_log_path (str | None) – path of the build log. Support placeholders. The logs will go to stdout/stderr if not specified

• size_json_path (str | None) – path of the size.json file. Support placeholders. Will not generate size file for each app if not specified

• check_warnings (bool) – Check for warnings in the build log or not

• preserve (bool) – Preserve the built binaries or not

• manifest_rootpath (str | None) – The root path of the manifest files. Usually the folders specified in the manifest files are relative paths. Use the current directory if not specified

• manifest_files (list[str] | str | None) – paths of the manifest files

• default_build_targets (list[str] | str | None) – default build targets used in manifest files

• modified_components (list[str] | str | None) – modified components

• modified_files (list[str] | str | None) – modified files

• ignore_app_dependencies_filepatterns (list[str] | str | None) – file patterns that used for ignoring checking the component dependencies

• sdkconfig_defaults (str | None) – semicolon-separated string, pass to idf.py -DSDKCONFIG_DEFAULTS if specified, also could be set via environment variables “SDKCONFIG_DEFAULTS”

Returns:

list of found apps

Return type:

list[App]

idf_build_apps.main.get_parser()

idf_build_apps.main.main()

idf_build_apps.main.validate_args(parser, args)

exception idf_build_apps.utils.BuildError

Bases: RuntimeError

class idf_build_apps.utils.ConfigRule(file_name, config_name)

Bases: object

exception idf_build_apps.utils.InvalidCommand(msg)

Bases: SystemExit

exception idf_build_apps.utils.InvalidIfClause

Bases: SystemExit

Invalid if clause in manifest file

exception idf_build_apps.utils.InvalidInput

Bases: SystemExit

Invalid input from user

exception idf_build_apps.utils.InvalidManifest

Bases: SystemExit

Invalid manifest file

idf_build_apps.utils.config_rules_from_str(rule_strings)

Helper function to convert strings like ‘file_name=config_name’ into ConfigRule objects

Parameters:

rule_strings (list[str] | str) – list of rules as strings or a single rule string

Returns:

list of ConfigRules

Return type:

list[ConfigRule]

idf_build_apps.utils.files_matches_patterns(files, patterns, rootpath=None)

idf_build_apps.utils.find_first_match(pattern, path)

idf_build_apps.utils.get_parallel_start_stop(total, parallel_count, parallel_index)

Calculate the start and stop indices for a parallel task (1-based).

Parameters:

• total (int) – total number of tasks

• parallel_count (int) – number of parallel tasks to run

• parallel_index (int) – index of the parallel task to run

Returns:

start and stop indices, [start, stop]

Return type:

(int, int)

idf_build_apps.utils.rmdir(path, exclude_file_patterns=None)

idf_build_apps.utils.subprocess_run(cmd, log_terminal=True, log_fs=None, check=False, additional_env_dict=None)

Subprocess.run for older python versions

Parameters:

• cmd (list[str]) – cmd

• log_terminal (bool) – print to sys.stdout if set to True

• log_fs (TextIO) – write to this file stream if not None

• check (bool) – raise BuildError when return code is non-zero

• additional_env_dict (dict[str, any] | None) – additional environment variables

Returns:

return code

Return type:

int

idf_build_apps.utils.to_absolute_path(s, rootpath=None)

idf_build_apps.utils.to_list(s)

Turn all objects to lists

Parameters:

s (any) – anything

Returns:

list(s), if s is a tuple or a set

Returns:

itself, if s is a list

Returns:

[s], if s is other type

Returns:

None, if s is None

Return type:

list | None

idf_build_apps.utils.to_version(s)