idf_build_apps package

Subpackages

Submodules

class idf_build_apps.app.App(app_dir: str, target: str, *, work_dir: Optional[str] = None, build_dir: str = 'build', build_log_filename: Optional[str] = None, size_json_filename: Optional[str] = None, build_system: typing_extensions.Literal[unknown] = 'unknown', sdkconfig_path: Optional[str] = None, config_name: Optional[str] = None, sdkconfig_defaults_str: Optional[str] = None, dry_run: bool = False, verbose: bool = False, check_warnings: bool = False, preserve: bool = True, copy_sdkconfig: bool = False, index: Optional[int] = None, build_status: BuildStatus = BuildStatus.UNKNOWN, build_comment: Optional[str] = None)

Bases: BaseModel

TARGET_PLACEHOLDER: ClassVar[str] = '@t'
WILDCARD_PLACEHOLDER: ClassVar[str] = '@w'
NAME_PLACEHOLDER: ClassVar[str] = '@n'
FULL_NAME_PLACEHOLDER: ClassVar[str] = '@f'
IDF_VERSION_PLACEHOLDER: ClassVar[str] = '@v'
INDEX_PLACEHOLDER: ClassVar[str] = '@i'
SDKCONFIG_LINE_REGEX: ClassVar[Pattern] = re.compile('^([^=]+)=\\"?([^\\"\\n]*)\\"?\\n*$')
MANIFEST: ClassVar[Optional[Manifest]] = None
LOG_ERROR_WARNING_REGEX: ClassVar[Pattern] = re.compile('(?:error|warning):', re.IGNORECASE|re.MULTILINE)
LOG_DEBUG_LINES: ClassVar[int] = 25
IGNORE_WARNS_REGEXES: ClassVar[List[Pattern]] = []
build_system: typing_extensions.Literal[unknown]
app_dir: str
target: str
sdkconfig_path: Optional[str]
config_name: Optional[str]
sdkconfig_defaults_str: Optional[str]
dry_run: bool
verbose: bool
check_warnings: bool
preserve: bool
copy_sdkconfig: bool
index: Optional[int]
build_status: BuildStatus
build_comment: Optional[str]
classmethod from_another(other: App, **kwargs) → App

Init New App from another, with different parameters.

eg: new_app = [Cmake]App.from_another(app, config=’debug’)

property sdkconfig_defaults_candidates: List[str]
property name: str
property work_dir: str
Returns:

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

property build_dir: str
Returns:

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

property build_path: str
property build_log_filename: Optional[str]
property build_log_path: str
property size_json_filename: Optional[str]
property size_json_path: Optional[str]
property sdkconfig_files_defined_idf_target: Optional[str]
property sdkconfig_files: List[str]
property depends_components: List[str]
property depends_filepatterns: List[str]
property supported_targets: List[str]
property verified_targets: List[str]
record_build_duration()
build(*, manifest_rootpath: Optional[str] = None, modified_components: Optional[Union[List[str], str]] = None, modified_files: Optional[Union[List[str], str]] = None, check_app_dependencies: bool = False) → None
write_size_json() → None
to_json() → str
is_error_or_warning(line: str) → Tuple[bool, bool]
classmethod is_app(path: str) → bool
is_modified(modified_files: Optional[List[str]]) → bool
check_should_build(*, manifest_rootpath: Optional[str] = None, modified_manifest_rules_folders: Optional[Set[str]] = None, check_app_dependencies: bool = False, modified_components: Optional[List[str]] = None, modified_files: Optional[List[str]] = None) → None
class idf_build_apps.app.MakeApp(app_dir: str, target: str, *, work_dir: Optional[str] = None, build_dir: str = 'build', build_log_filename: Optional[str] = None, size_json_filename: Optional[str] = None, build_system: typing_extensions.Literal[make] = 'make', sdkconfig_path: Optional[str] = None, config_name: Optional[str] = None, sdkconfig_defaults_str: Optional[str] = None, dry_run: bool = False, verbose: bool = False, check_warnings: bool = False, preserve: bool = True, copy_sdkconfig: bool = False, index: Optional[int] = None, build_status: BuildStatus = BuildStatus.UNKNOWN, build_comment: Optional[str] = None)

Bases: App

MAKE_PROJECT_LINE: ClassVar[str] = 'include $(IDF_PATH)/make/project.mk'
build_system: typing_extensions.Literal[make]
property supported_targets: List[str]
classmethod is_app(path: str) → bool
class idf_build_apps.app.CMakeApp(app_dir: str, target: str, *, work_dir: Optional[str] = None, build_dir: str = 'build', build_log_filename: Optional[str] = None, size_json_filename: Optional[str] = None, build_system: typing_extensions.Literal[cmake] = 'cmake', sdkconfig_path: Optional[str] = None, config_name: Optional[str] = None, sdkconfig_defaults_str: Optional[str] = None, dry_run: bool = False, verbose: bool = False, check_warnings: bool = False, preserve: bool = True, copy_sdkconfig: bool = False, index: Optional[int] = None, build_status: BuildStatus = BuildStatus.UNKNOWN, build_comment: Optional[str] = None, cmake_vars: Dict[str, str] = {})

Bases: App

SDKCONFIG_TEST_OPTS: ClassVar[List[str]] = ['EXCLUDE_COMPONENTS', 'TEST_EXCLUDE_COMPONENTS', 'TEST_COMPONENTS']
SDKCONFIG_IGNORE_OPTS: ClassVar[List[str]] = ['TEST_GROUPS']
CMAKE_PROJECT_LINE: ClassVar[str] = 'include($ENV{IDF_PATH}/tools/cmake/project.cmake)'
build_system: typing_extensions.Literal[cmake]
cmake_vars: Dict[str, str]
classmethod is_app(path: str) → bool
class idf_build_apps.app.AppDeserializer(*, app: Union[App, CMakeApp, MakeApp])

Bases: BaseModel

app: Union[App, CMakeApp, MakeApp]
classmethod from_json(json_data: Union[str, bytes, bytearray]) → App
class idf_build_apps.args.ValidateMethod(value)

Bases: str, Enum

An enumeration.

TO_LIST = 'to_list'
class idf_build_apps.args.FieldMetadata(validate_method: Optional[List[str]] = None, deprecates: Optional[Dict[str, Dict[str, Any]]] = None, shorthand: Optional[str] = None, action: Optional[str] = None, nargs: Optional[str] = None, choices: Optional[List[str]] = None, type: Optional[Callable] = None, required: bool = False, default: Optional[Any] = None, hidden: bool = False)

Bases: object

dataclass field metadata. All fields are optional. Some fields are used in argparse while running add_args_to_parser().

Parameters:

  • validate_method – validate method for the field

  • deprecates – deprecates field names, used in argparse

  • shorthand – shorthand for the argument, used in argparse

  • action – action for the argument, used in argparse

  • nargs – nargs for the argument, used in argparse

  • choices – choices for the argument, used in argparse

  • type – type for the argument, used in argparse

  • required – whether the argument is required, used in argparse

  • default – default value for the argument, used in argparse

  • hidden – whether the argument is hidden, used in argparse

validate_method: Optional[List[str]] = None
deprecates: Optional[Dict[str, Dict[str, Any]]] = None
shorthand: Optional[str] = None
action: Optional[str] = None
nargs: Optional[str] = None
choices: Optional[List[str]] = None
type: Optional[Callable] = None
required: bool = False
default: Any = None
hidden: bool = False
idf_build_apps.args.field(meta: Optional[FieldMetadata], *args, **kwargs)

field with metadata

idf_build_apps.args.get_meta(f: FieldInfo) → Optional[FieldMetadata]

Get the metadata of the field

Parameters:

f – field

Returns:

metadata of the field if exists, None otherwise

class idf_build_apps.args.BaseArguments(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_nested_delimiter: str | None = None, _secrets_dir: str | Path | None = None)

Bases: BaseSettings

Base settings class for all settings classes

classmethod settings_customise_sources(settings_cls: Type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) → Tuple[PydanticBaseSettingsSource, ...]

Define the sources and their order for loading the settings values.

Args:

settings_cls: The Settings class. init_settings: The InitSettingsSource instance. env_settings: The EnvSettingsSource instance. dotenv_settings: The DotEnvSettingsSource instance. file_secret_settings: The SecretsSettingsSource instance.

Returns:

A tuple containing the sources and their order for loading the settings values.

classmethod validate_by_validate_methods(v: Any, info: ValidationInfo)
class idf_build_apps.args.GlobalArguments(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_nested_delimiter: str | None = None, _secrets_dir: str | Path | None = None, *, verbose: int[int] = 0, log_file: Optional[str][Optional[str]] = None, no_color: bool[bool] = False)

Bases: BaseArguments

verbose: int
log_file: Optional[str]
no_color: bool
class idf_build_apps.args.DependencyDrivenBuildArguments(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_nested_delimiter: str | None = None, _secrets_dir: str | Path | None = None, *, verbose: int[int] = 0, log_file: Optional[str][Optional[str]] = None, no_color: bool[bool] = False, manifest_files: Optional[List[Union[pathlib.Path, str]]][Optional[List[Union[Path, str]]]] = None, manifest_filepatterns: Optional[List[str]][Optional[List[str]]] = None, manifest_rootpath: str[str] = '.', modified_components: Optional[List[str]][Optional[List[str]]] = None, modified_files: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_components: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_filepatterns: Optional[List[str]][Optional[List[str]]] = None, check_manifest_rules: bool[bool] = False, compare_manifest_sha_filepath: Optional[str][Optional[str]] = None)

Bases: GlobalArguments

manifest_files: Optional[List[Union[Path, str]]]
manifest_filepatterns: Optional[List[str]]
manifest_rootpath: str
modified_components: Optional[List[str]]
modified_files: Optional[List[str]]
deactivate_dependency_driven_build_by_components: Optional[List[str]]
deactivate_dependency_driven_build_by_filepatterns: Optional[List[str]]
check_manifest_rules: bool
compare_manifest_sha_filepath: Optional[str]
property dependency_driven_build_enabled: bool

Check if the dependency-driven build feature is enabled

Returns:

True if enabled, False otherwise

property modified_manifest_rules_folders: Optional[Set[str]]
class idf_build_apps.args.FindBuildArguments(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_nested_delimiter: str | None = None, _secrets_dir: str | Path | None = None, *, verbose: int[int] = 0, log_file: Optional[str][Optional[str]] = None, no_color: bool[bool] = False, manifest_files: Optional[List[Union[pathlib.Path, str]]][Optional[List[Union[Path, str]]]] = None, manifest_filepatterns: Optional[List[str]][Optional[List[str]]] = None, manifest_rootpath: str[str] = '.', modified_components: Optional[List[str]][Optional[List[str]]] = None, modified_files: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_components: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_filepatterns: Optional[List[str]][Optional[List[str]]] = None, check_manifest_rules: bool[bool] = False, compare_manifest_sha_filepath: Optional[str][Optional[str]] = None, paths: List[str][List[str]] = '.', target: str[str] = 'all', build_system: Union[str, Type[idf_build_apps.app.App]][Union[str, Type[App]]] = 'cmake', recursive: bool[bool] = False, exclude: Optional[List[str]][Optional[List[str]]] = None, work_dir: Optional[str][Optional[str]] = None, build_dir: str[str] = 'build', build_log_filename: Optional[str][Optional[str]] = None, size_json_filename: Optional[str][Optional[str]] = None, config_rules: Optional[List[str]][Optional[List[str]]] = None, override_sdkconfig_items: Optional[str][Optional[str]] = None, override_sdkconfig_files: Optional[str][Optional[str]] = None, sdkconfig_defaults: Optional[str][Optional[str]] = None, check_warnings: bool[bool] = False, default_build_targets: Optional[List[str]][Optional[List[str]]] = None, enable_preview_targets: bool[bool] = False, include_skipped_apps: bool[bool] = False, include_disabled_apps: bool[bool] = False, include_all_apps: bool[bool] = False)

Bases: DependencyDrivenBuildArguments

paths: List[str]
target: str
build_system: Union[str, Type[App]]
recursive: bool
exclude: Optional[List[str]]
work_dir: Optional[str]
build_dir: str
build_log_filename: Optional[str]
size_json_filename: Optional[str]
config_rules: Optional[List[str]]
override_sdkconfig_items: Optional[str]
override_sdkconfig_files: Optional[str]
sdkconfig_defaults: Optional[str]
check_warnings: bool
default_build_targets: Optional[List[str]]
enable_preview_targets: bool
include_skipped_apps: bool
include_disabled_apps: bool
include_all_apps: bool
class idf_build_apps.args.FindArguments(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_nested_delimiter: str | None = None, _secrets_dir: str | Path | None = None, *, verbose: int[int] = 0, log_file: Optional[str][Optional[str]] = None, no_color: bool[bool] = False, manifest_files: Optional[List[Union[pathlib.Path, str]]][Optional[List[Union[Path, str]]]] = None, manifest_filepatterns: Optional[List[str]][Optional[List[str]]] = None, manifest_rootpath: str[str] = '.', modified_components: Optional[List[str]][Optional[List[str]]] = None, modified_files: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_components: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_filepatterns: Optional[List[str]][Optional[List[str]]] = None, check_manifest_rules: bool[bool] = False, compare_manifest_sha_filepath: Optional[str][Optional[str]] = None, paths: List[str][List[str]] = '.', target: str[str] = 'all', build_system: Union[str, Type[idf_build_apps.app.App]][Union[str, Type[App]]] = 'cmake', recursive: bool[bool] = False, exclude: Optional[List[str]][Optional[List[str]]] = None, work_dir: Optional[str][Optional[str]] = None, build_dir: str[str] = 'build', build_log_filename: Optional[str][Optional[str]] = None, size_json_filename: Optional[str][Optional[str]] = None, config_rules: Optional[List[str]][Optional[List[str]]] = None, override_sdkconfig_items: Optional[str][Optional[str]] = None, override_sdkconfig_files: Optional[str][Optional[str]] = None, sdkconfig_defaults: Optional[str][Optional[str]] = None, check_warnings: bool[bool] = False, default_build_targets: Optional[List[str]][Optional[List[str]]] = None, enable_preview_targets: bool[bool] = False, include_skipped_apps: bool[bool] = False, include_disabled_apps: bool[bool] = False, include_all_apps: bool[bool] = False, output: Optional[str][Optional[str]] = None, output_format: str[str] = 'raw')

Bases: FindBuildArguments

Parameters:

  • verbose (int) – Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

  • log_file (Union[str, NoneType]) – Path to the log file, if not specified logs will be printed to stderr

  • no_color (bool) – Disable colored output

  • manifest_files (Union[List[Union[pathlib.Path, str]], NoneType]) – Path to the manifest files which contains the build test rules of the apps

  • manifest_filepatterns (Union[List[str], NoneType]) – space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

  • manifest_rootpath (str) – Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

  • modified_components (Union[List[str], NoneType]) – semicolon-separated list of modified 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 (Union[List[str], NoneType]) – semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

  • deactivate_dependency_driven_build_by_components (Union[List[str], NoneType]) – semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified 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.

  • deactivate_dependency_driven_build_by_filepatterns (Union[List[str], NoneType]) – semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified 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.

  • check_manifest_rules (bool) – Check if all folders defined in the manifest files exist. Fail if not

  • compare_manifest_sha_filepath (Union[str, NoneType]) – Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

  • paths (List[str]) – Paths to the directories containing the apps. By default set to the current directory

  • target (str) – Filter the apps by target. By default set to “all”

  • build_system (Union[str, Type[idf_build_apps.app.App]]) – Filter the apps by build system. By default set to “cmake”

  • recursive (bool) – Search for apps recursively under the specified paths

  • exclude (Union[List[str], NoneType]) – Ignore the specified directories while searching recursively

  • work_dir (Union[str, NoneType]) – Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

  • build_dir (str) – Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

  • build_log_filename (Union[str, NoneType]) – Log filename under the build directory instead of stdout. Can expand placeholders

  • size_json_filename (Union[str, NoneType]) – idf.py size output file under the build directory when specified. Can expand placeholders

  • config_rules (Union[List[str], NoneType]) – Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

  • override_sdkconfig_items (Union[str, NoneType]) – A comma-separated list of key=value pairs to override the sdkconfig items

  • override_sdkconfig_files (Union[str, NoneType]) – A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

  • sdkconfig_defaults (Union[str, NoneType]) – A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

  • check_warnings (bool) – Check for warnings in the build output. Fail if any warnings are found

  • default_build_targets (Union[List[str], NoneType]) – space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

  • enable_preview_targets (bool) – When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

  • include_skipped_apps (bool) – Include the skipped apps in the output, together with the enabled ones

  • include_disabled_apps (bool) – Include the disabled apps in the output, together with the enabled ones

  • include_all_apps (bool) – Include skipped, and disabled apps in the output, together with the enabled ones

  • output (Union[str, NoneType]) – Record the found apps to the specified file instead of stdout

  • output_format (str) – Output format of the found apps. In “raw” format, each line is a json string serialized from the app model. In “json” format, the output is a json list of the serialized app models

output: Optional[str]
output_format: str
class idf_build_apps.args.BuildArguments(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_nested_delimiter: str | None = None, _secrets_dir: str | Path | None = None, *, verbose: int[int] = 0, log_file: Optional[str][Optional[str]] = None, no_color: bool[bool] = False, manifest_files: Optional[List[Union[pathlib.Path, str]]][Optional[List[Union[Path, str]]]] = None, manifest_filepatterns: Optional[List[str]][Optional[List[str]]] = None, manifest_rootpath: str[str] = '.', modified_components: Optional[List[str]][Optional[List[str]]] = None, modified_files: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_components: Optional[List[str]][Optional[List[str]]] = None, deactivate_dependency_driven_build_by_filepatterns: Optional[List[str]][Optional[List[str]]] = None, check_manifest_rules: bool[bool] = False, compare_manifest_sha_filepath: Optional[str][Optional[str]] = None, paths: List[str][List[str]] = '.', target: str[str] = 'all', build_system: Union[str, Type[idf_build_apps.app.App]][Union[str, Type[App]]] = 'cmake', recursive: bool[bool] = False, exclude: Optional[List[str]][Optional[List[str]]] = None, work_dir: Optional[str][Optional[str]] = None, build_dir: str[str] = 'build', build_log_filename: Optional[str][Optional[str]] = None, size_json_filename: Optional[str][Optional[str]] = None, config_rules: Optional[List[str]][Optional[List[str]]] = None, override_sdkconfig_items: Optional[str][Optional[str]] = None, override_sdkconfig_files: Optional[str][Optional[str]] = None, sdkconfig_defaults: Optional[str][Optional[str]] = None, check_warnings: bool[bool] = False, default_build_targets: Optional[List[str]][Optional[List[str]]] = None, enable_preview_targets: bool[bool] = False, include_skipped_apps: bool[bool] = False, include_disabled_apps: bool[bool] = False, include_all_apps: bool[bool] = False, build_verbose: bool[bool] = False, parallel_count: int[int] = 1, parallel_index: int[int] = 1, dry_run: bool[bool] = False, keep_going: bool[bool] = False, no_preserve: bool[bool] = False, ignore_warning_strs: Optional[List[str]][Optional[List[str]]] = None, ignore_warning_files: Optional[List[Union[str, _io.TextIOWrapper]]][Optional[List[Union[str, TextIOWrapper]]]] = None, copy_sdkconfig: bool[bool] = False, collect_size_info_filename: Optional[str][Optional[str]] = None, collect_app_info_filename: Optional[str][Optional[str]] = None, junitxml_filename: Optional[str][Optional[str]] = None)

Bases: FindBuildArguments

Parameters:

  • verbose (int) – Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

  • log_file (Union[str, NoneType]) – Path to the log file, if not specified logs will be printed to stderr

  • no_color (bool) – Disable colored output

  • manifest_files (Union[List[Union[pathlib.Path, str]], NoneType]) – Path to the manifest files which contains the build test rules of the apps

  • manifest_filepatterns (Union[List[str], NoneType]) – space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

  • manifest_rootpath (str) – Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

  • modified_components (Union[List[str], NoneType]) – semicolon-separated list of modified 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 (Union[List[str], NoneType]) – semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

  • deactivate_dependency_driven_build_by_components (Union[List[str], NoneType]) – semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified 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.

  • deactivate_dependency_driven_build_by_filepatterns (Union[List[str], NoneType]) – semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified 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.

  • check_manifest_rules (bool) – Check if all folders defined in the manifest files exist. Fail if not

  • compare_manifest_sha_filepath (Union[str, NoneType]) – Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

  • paths (List[str]) – Paths to the directories containing the apps. By default set to the current directory

  • target (str) – Filter the apps by target. By default set to “all”

  • build_system (Union[str, Type[idf_build_apps.app.App]]) – Filter the apps by build system. By default set to “cmake”

  • recursive (bool) – Search for apps recursively under the specified paths

  • exclude (Union[List[str], NoneType]) – Ignore the specified directories while searching recursively

  • work_dir (Union[str, NoneType]) – Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

  • build_dir (str) – Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

  • build_log_filename (Union[str, NoneType]) – Log filename under the build directory instead of stdout. Can expand placeholders

  • size_json_filename (Union[str, NoneType]) – idf.py size output file under the build directory when specified. Can expand placeholders

  • config_rules (Union[List[str], NoneType]) – Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

  • override_sdkconfig_items (Union[str, NoneType]) – A comma-separated list of key=value pairs to override the sdkconfig items

  • override_sdkconfig_files (Union[str, NoneType]) – A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

  • sdkconfig_defaults (Union[str, NoneType]) – A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

  • check_warnings (bool) – Check for warnings in the build output. Fail if any warnings are found

  • default_build_targets (Union[List[str], NoneType]) – space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

  • enable_preview_targets (bool) – When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

  • include_skipped_apps (bool) – Include the skipped apps in the output, together with the enabled ones

  • include_disabled_apps (bool) – Include the disabled apps in the output, together with the enabled ones

  • include_all_apps (bool) – Include skipped, and disabled apps in the output, together with the enabled ones

  • build_verbose (bool) – Enable verbose output of the build system

  • parallel_count (int) – Number of parallel build jobs in total. Specified together with –parallel-index. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

  • parallel_index (int) – Index (1-based) of the parallel build job. Specified together with –parallel-count. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

  • dry_run (bool) – Skip the actual build, only print the build process

  • keep_going (bool) – Continue building the next app when the current build fails

  • no_preserve (bool) – Do not preserve the build directory after a successful build

  • ignore_warning_strs (Union[List[str], NoneType]) – space-separated list of patterns. Ignore the warnings in the build output that match the patterns

  • ignore_warning_files (Union[List[Union[str, _io.TextIOWrapper]], NoneType]) – Path to the files containing the patterns to ignore the warnings in the build output

  • copy_sdkconfig (bool) – Copy the sdkconfig file to the build directory

  • collect_size_info_filename (Union[str, NoneType]) – Record size json filepath of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

  • collect_app_info_filename (Union[str, NoneType]) – Record serialized app model of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

  • junitxml_filename (Union[str, NoneType]) – Path to the junitxml file to record the build results. Can expand placeholder @p

build_verbose: bool
parallel_count: int
parallel_index: int
dry_run: bool
keep_going: bool
no_preserve: bool
ignore_warning_strs: Optional[List[str]]
ignore_warning_files: Optional[List[Union[str, TextIOWrapper]]]
copy_sdkconfig: bool
collect_size_info_filename: Optional[str]
collect_app_info_filename: Optional[str]
junitxml_filename: Optional[str]
PARALLEL_INDEX_PLACEHOLDER: ClassVar[str] = '@p'
property collect_size_info: Optional[str]
property collect_app_info: Optional[str]
property junitxml: Optional[str]
class idf_build_apps.args.DumpManifestShaArguments(_case_sensitive: bool | None = None, _env_prefix: str | None = None, _env_file: DotenvType | None = PosixPath('.'), _env_file_encoding: str | None = None, _env_nested_delimiter: str | None = None, _secrets_dir: str | Path | None = None, *, verbose: int[int] = 0, log_file: Optional[str][Optional[str]] = None, no_color: bool[bool] = False, manifest_files: Optional[List[str]][Optional[List[str]]] = None, output: Optional[str][Optional[str]] = None)

Bases: GlobalArguments

manifest_files: Optional[List[str]]
output: Optional[str]
idf_build_apps.args.add_args_to_parser(argument_cls: Type[BaseArguments], parser: ArgumentParser) → None

Add arguments to the parser from the argument class.

FieldMetadata is used to set the argparse options.

Parameters:

  • argument_cls – argument class

  • parser – argparse parser

idf_build_apps.args.add_args_to_obj_doc_as_params(argument_cls: Type[GlobalArguments], obj: Optional[Any] = None) → None

Add arguments to the function as parameters.

Parameters:

  • argument_cls – argument class

  • obj – object to add the docstring to

idf_build_apps.args.apply_config_file(config_file: Optional[str]) → None
idf_build_apps.autocompletions.append_to_file(file_path: str, content: str) → None

Add commands to shell configuration file

Parameters:

  • file_path – path to shell configurations file

  • content – commands to add

idf_build_apps.autocompletions.activate_completions(shell_type: Optional[str]) → None

Activates autocompletion for supported shells.

Raises:

AutocompleteActivationError – if the $SHELL env variable is empty, or if the detected shell is unsupported.

class idf_build_apps.constants.BuildStatus(value)

Bases: str, Enum

An enumeration.

UNKNOWN = 'unknown'
DISABLED = 'disabled'
SKIPPED = 'skipped'
SHOULD_BE_BUILT = 'should be built'
FAILED = 'build failed'
SUCCESS = 'build success'
class idf_build_apps.constants.BuildStage(value)

Bases: str, Enum

An enumeration.

DRY_RUN = 'Dry Run'
PRE_BUILD = 'Pre Build'
BUILD = 'Build'
POST_BUILD = 'Post Build'
classmethod max_length() → int
class idf_build_apps.log.ColoredFormatter(colored: bool = True)

Bases: Formatter

grey: str = '\x1b[37;20m'
yellow: str = '\x1b[33;20m'
red: str = '\x1b[31;20m'
bold_red: str = '\x1b[31;1m'
reset: str = '\x1b[0m'
fmt: str = '%(asctime)s %(levelname)8s %(message)s'
app_fmt: str = '%(asctime)s %(levelname)8s [%(build_stage)10s] %(message)s'
datefmt: str = '%Y-%m-%d %H:%M:%S'
FORMATS: Dict[int, str] = {10: '\x1b[37;20m{}\x1b[0m', 20: '{}', 30: '\x1b[33;20m{}\x1b[0m', 40: '\x1b[31;20m{}\x1b[0m', 50: '\x1b[31;1m{}\x1b[0m'}
format(record: LogRecord) → str

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

idf_build_apps.log.setup_logging(verbose: int = 0, log_file: Optional[str] = None, colored: bool = True) → None

Setup logging stream handler

Parameters:

  • verbose – 0 - WARNING, 1 - INFO, 2 - DEBUG

  • log_file – log file path

  • colored – colored output or not

Returns:

None

idf_build_apps.main.find_apps(paths: Optional[Union[List[str], str]] = None, target: Optional[str] = None, *, find_arguments: Optional[FindArguments] = None, config_file: Optional[str] = None, **kwargs) → List[App]

Find apps in the given paths for the specified target. For all kwargs, please refer to FindArguments

Returns:

list of found apps

Parameters:

  • verbose (int) – Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

  • log_file (Union[str, NoneType]) – Path to the log file, if not specified logs will be printed to stderr

  • no_color (bool) – Disable colored output

  • manifest_files (Union[List[Union[pathlib.Path, str]], NoneType]) – Path to the manifest files which contains the build test rules of the apps

  • manifest_filepatterns (Union[List[str], NoneType]) – space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

  • manifest_rootpath (str) – Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

  • modified_components (Union[List[str], NoneType]) – semicolon-separated list of modified 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 (Union[List[str], NoneType]) – semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

  • deactivate_dependency_driven_build_by_components (Union[List[str], NoneType]) – semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified 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.

  • deactivate_dependency_driven_build_by_filepatterns (Union[List[str], NoneType]) – semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified 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.

  • check_manifest_rules (bool) – Check if all folders defined in the manifest files exist. Fail if not

  • compare_manifest_sha_filepath (Union[str, NoneType]) – Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

  • paths (List[str]) – Paths to the directories containing the apps. By default set to the current directory

  • target (str) – Filter the apps by target. By default set to “all”

  • build_system (Union[str, Type[idf_build_apps.app.App]]) – Filter the apps by build system. By default set to “cmake”

  • recursive (bool) – Search for apps recursively under the specified paths

  • exclude (Union[List[str], NoneType]) – Ignore the specified directories while searching recursively

  • work_dir (Union[str, NoneType]) – Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

  • build_dir (str) – Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

  • build_log_filename (Union[str, NoneType]) – Log filename under the build directory instead of stdout. Can expand placeholders

  • size_json_filename (Union[str, NoneType]) – idf.py size output file under the build directory when specified. Can expand placeholders

  • config_rules (Union[List[str], NoneType]) – Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

  • override_sdkconfig_items (Union[str, NoneType]) – A comma-separated list of key=value pairs to override the sdkconfig items

  • override_sdkconfig_files (Union[str, NoneType]) – A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

  • sdkconfig_defaults (Union[str, NoneType]) – A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

  • check_warnings (bool) – Check for warnings in the build output. Fail if any warnings are found

  • default_build_targets (Union[List[str], NoneType]) – space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

  • enable_preview_targets (bool) – When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

  • include_skipped_apps (bool) – Include the skipped apps in the output, together with the enabled ones

  • include_disabled_apps (bool) – Include the disabled apps in the output, together with the enabled ones

  • include_all_apps (bool) – Include skipped, and disabled apps in the output, together with the enabled ones

  • output (Union[str, NoneType]) – Record the found apps to the specified file instead of stdout

  • output_format (str) – Output format of the found apps. In “raw” format, each line is a json string serialized from the app model. In “json” format, the output is a json list of the serialized app models

idf_build_apps.main.build_apps(apps: Optional[Union[List[App], App]] = None, *, build_arguments: Optional[BuildArguments] = None, config_file: Optional[str] = None, **kwargs) → int

Build all the specified apps. For all kwargs, please refer to BuildArguments

Returns:

exit code

Parameters:

  • verbose (int) – Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

  • log_file (Union[str, NoneType]) – Path to the log file, if not specified logs will be printed to stderr

  • no_color (bool) – Disable colored output

  • manifest_files (Union[List[Union[pathlib.Path, str]], NoneType]) – Path to the manifest files which contains the build test rules of the apps

  • manifest_filepatterns (Union[List[str], NoneType]) – space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

  • manifest_rootpath (str) – Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

  • modified_components (Union[List[str], NoneType]) – semicolon-separated list of modified 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 (Union[List[str], NoneType]) – semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

  • deactivate_dependency_driven_build_by_components (Union[List[str], NoneType]) – semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified 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.

  • deactivate_dependency_driven_build_by_filepatterns (Union[List[str], NoneType]) – semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified 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.

  • check_manifest_rules (bool) – Check if all folders defined in the manifest files exist. Fail if not

  • compare_manifest_sha_filepath (Union[str, NoneType]) – Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

  • paths (List[str]) – Paths to the directories containing the apps. By default set to the current directory

  • target (str) – Filter the apps by target. By default set to “all”

  • build_system (Union[str, Type[idf_build_apps.app.App]]) – Filter the apps by build system. By default set to “cmake”

  • recursive (bool) – Search for apps recursively under the specified paths

  • exclude (Union[List[str], NoneType]) – Ignore the specified directories while searching recursively

  • work_dir (Union[str, NoneType]) – Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

  • build_dir (str) – Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

  • build_log_filename (Union[str, NoneType]) – Log filename under the build directory instead of stdout. Can expand placeholders

  • size_json_filename (Union[str, NoneType]) – idf.py size output file under the build directory when specified. Can expand placeholders

  • config_rules (Union[List[str], NoneType]) – Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

  • override_sdkconfig_items (Union[str, NoneType]) – A comma-separated list of key=value pairs to override the sdkconfig items

  • override_sdkconfig_files (Union[str, NoneType]) – A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

  • sdkconfig_defaults (Union[str, NoneType]) – A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

  • check_warnings (bool) – Check for warnings in the build output. Fail if any warnings are found

  • default_build_targets (Union[List[str], NoneType]) – space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

  • enable_preview_targets (bool) – When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

  • include_skipped_apps (bool) – Include the skipped apps in the output, together with the enabled ones

  • include_disabled_apps (bool) – Include the disabled apps in the output, together with the enabled ones

  • include_all_apps (bool) – Include skipped, and disabled apps in the output, together with the enabled ones

  • build_verbose (bool) – Enable verbose output of the build system

  • parallel_count (int) – Number of parallel build jobs in total. Specified together with –parallel-index. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

  • parallel_index (int) – Index (1-based) of the parallel build job. Specified together with –parallel-count. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

  • dry_run (bool) – Skip the actual build, only print the build process

  • keep_going (bool) – Continue building the next app when the current build fails

  • no_preserve (bool) – Do not preserve the build directory after a successful build

  • ignore_warning_strs (Union[List[str], NoneType]) – space-separated list of patterns. Ignore the warnings in the build output that match the patterns

  • ignore_warning_files (Union[List[Union[str, _io.TextIOWrapper]], NoneType]) – Path to the files containing the patterns to ignore the warnings in the build output

  • copy_sdkconfig (bool) – Copy the sdkconfig file to the build directory

  • collect_size_info_filename (Union[str, NoneType]) – Record size json filepath of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

  • collect_app_info_filename (Union[str, NoneType]) – Record serialized app model of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

  • junitxml_filename (Union[str, NoneType]) – Path to the junitxml file to record the build results. Can expand placeholder @p

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.get_parser() → ArgumentParser
idf_build_apps.main.handle_completions(args: Namespace) → None
idf_build_apps.main.main()
idf_build_apps.main.json_to_app(json_str: str, extra_classes: Optional[List[Type[App]]] = None) → App

Deserialize json string to App object

Note

You can pass extra_cls to support custom App class. A custom App class must be a subclass of App, and have a different value of build_system. For example, a custom CMake app

class CustomApp(CMakeApp):
    build_system: Literal['custom_cmake'] = 'custom_cmake'

Then you can pass the CustomApp class to the extra_cls argument

json_str = CustomApp('.', 'esp32').to_json()
json_to_app(json_str, extra_classes=[CustomApp])
Parameters:

  • json_str – json string

  • extra_classes – extra App class

Returns:

App object

class idf_build_apps.session_args.SessionArgs

Bases: object

workdir: str = '/home/docs/checkouts/readthedocs.org/user_builds/espressif-idf-build-apps/checkouts/latest/docs/en'
override_sdkconfig_items: Dict[str, Any] = {}
override_sdkconfig_file_path: Optional[str] = None
set(parsed_args, *, workdir=None)
clean()
class idf_build_apps.utils.ConfigRule(file_name: str, config_name: str = '')

Bases: object

idf_build_apps.utils.config_rules_from_str(rule_strings: Optional[List[str]]) → List[ConfigRule]

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

Parameters:

rule_strings – list of rules as strings or a single rule string

Returns:

list of ConfigRules

idf_build_apps.utils.get_parallel_start_stop(total: int, parallel_count: int, parallel_index: int) → Tuple[int, int]

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

Parameters:

  • total – total number of tasks

  • parallel_count – number of parallel tasks to run

  • parallel_index – index of the parallel task to run

Returns:

start and stop indices, [start, stop]

exception idf_build_apps.utils.BuildError

Bases: RuntimeError

exception idf_build_apps.utils.AutocompleteActivationError

Bases: SystemExit

exception idf_build_apps.utils.InvalidCommand(msg: str)

Bases: SystemExit

exception idf_build_apps.utils.InvalidInput

Bases: SystemExit

Invalid input from user

exception idf_build_apps.utils.InvalidIfClause

Bases: SystemExit

Invalid if clause in manifest file

exception idf_build_apps.utils.InvalidManifest

Bases: SystemExit

Invalid manifest file

idf_build_apps.utils.rmdir(path: Union[Path, str], exclude_file_patterns: Optional[Union[List[str], str]] = None) → None
idf_build_apps.utils.find_first_match(pattern: str, path: str) → Optional[str]
idf_build_apps.utils.subprocess_run(cmd: List[str], log_terminal: bool = True, log_fs: Optional[Union[IO[str], str]] = None, check: bool = False, additional_env_dict: Optional[Dict[str, str]] = None, **kwargs) → int

Subprocess.run for older python versions

Parameters:

  • cmd – cmd

  • log_terminal – print to sys.stdout if set to True

  • log_fs – write to this file stream if not None

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

  • additional_env_dict – additional environment variables

Returns:

return code

idf_build_apps.utils.to_list(s: None) → None
idf_build_apps.utils.to_list(s: Iterable[_T]) → List[_T]
idf_build_apps.utils.to_list(s: _T) → List[_T]

Turn all objects to lists

Parameters:

s – anything

Returns:

  • None, if s is None

  • itself, if s is a list

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

  • [s], if s is other type

idf_build_apps.utils.to_set(s: None) → None
idf_build_apps.utils.to_set(s: Iterable[_T]) → Set[_T]
idf_build_apps.utils.to_set(s: _T) → Set[_T]

Turn all objects to sets

Parameters:

s – anything

Returns:

  • None, if s is None

  • itself, if s is a set

  • set(to_list(s)), if s is other type

idf_build_apps.utils.semicolon_separated_str_to_list(s: Optional[str]) → Optional[List[str]]

Split a string by semicolon and strip each part

Args:

s: string to split

Returns:

list of strings

idf_build_apps.utils.to_absolute_path(s: str, rootpath: Optional[str] = None) → str
idf_build_apps.utils.to_version(s: Any) → Version
idf_build_apps.utils.files_matches_patterns(files: Union[List[str], str], patterns: Union[List[str], str], rootpath: Optional[str] = None) → bool
class idf_build_apps.utils.BaseModel

Bases: BaseModel

BaseModel that is hashable

idf_build_apps.utils.drop_none_kwargs(d: dict) → dict

Module contents

Tools for building ESP-IDF related apps.

class idf_build_apps.App(app_dir: str, target: str, *, work_dir: Optional[str] = None, build_dir: str = 'build', build_log_filename: Optional[str] = None, size_json_filename: Optional[str] = None, build_system: typing_extensions.Literal[unknown] = 'unknown', sdkconfig_path: Optional[str] = None, config_name: Optional[str] = None, sdkconfig_defaults_str: Optional[str] = None, dry_run: bool = False, verbose: bool = False, check_warnings: bool = False, preserve: bool = True, copy_sdkconfig: bool = False, index: Optional[int] = None, build_status: BuildStatus = BuildStatus.UNKNOWN, build_comment: Optional[str] = None)

Bases: BaseModel

TARGET_PLACEHOLDER: ClassVar[str] = '@t'
WILDCARD_PLACEHOLDER: ClassVar[str] = '@w'
NAME_PLACEHOLDER: ClassVar[str] = '@n'
FULL_NAME_PLACEHOLDER: ClassVar[str] = '@f'
IDF_VERSION_PLACEHOLDER: ClassVar[str] = '@v'
INDEX_PLACEHOLDER: ClassVar[str] = '@i'
SDKCONFIG_LINE_REGEX: ClassVar[Pattern] = re.compile('^([^=]+)=\\"?([^\\"\\n]*)\\"?\\n*$')
MANIFEST: ClassVar[Optional[Manifest]] = None
LOG_ERROR_WARNING_REGEX: ClassVar[Pattern] = re.compile('(?:error|warning):', re.IGNORECASE|re.MULTILINE)
LOG_DEBUG_LINES: ClassVar[int] = 25
IGNORE_WARNS_REGEXES: ClassVar[List[Pattern]] = []
build_system: typing_extensions.Literal[unknown]
app_dir: str
target: str
sdkconfig_path: Optional[str]
config_name: Optional[str]
sdkconfig_defaults_str: Optional[str]
dry_run: bool
verbose: bool
check_warnings: bool
preserve: bool
copy_sdkconfig: bool
index: Optional[int]
build_status: BuildStatus
build_comment: Optional[str]
classmethod from_another(other: App, **kwargs) → App

Init New App from another, with different parameters.

eg: new_app = [Cmake]App.from_another(app, config=’debug’)

property sdkconfig_defaults_candidates: List[str]
property name: str
property work_dir: str
Returns:

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

property build_dir: str
Returns:

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

property build_path: str
property build_log_filename: Optional[str]
property build_log_path: str
property size_json_filename: Optional[str]
property size_json_path: Optional[str]
property sdkconfig_files_defined_idf_target: Optional[str]
property sdkconfig_files: List[str]
property depends_components: List[str]
property depends_filepatterns: List[str]
property supported_targets: List[str]
property verified_targets: List[str]
record_build_duration()
build(*, manifest_rootpath: Optional[str] = None, modified_components: Optional[Union[List[str], str]] = None, modified_files: Optional[Union[List[str], str]] = None, check_app_dependencies: bool = False) → None
write_size_json() → None
to_json() → str
is_error_or_warning(line: str) → Tuple[bool, bool]
classmethod is_app(path: str) → bool
is_modified(modified_files: Optional[List[str]]) → bool
check_should_build(*, manifest_rootpath: Optional[str] = None, modified_manifest_rules_folders: Optional[Set[str]] = None, check_app_dependencies: bool = False, modified_components: Optional[List[str]] = None, modified_files: Optional[List[str]] = None) → None
class idf_build_apps.AppDeserializer(*, app: Union[App, CMakeApp, MakeApp])

Bases: BaseModel

app: Union[App, CMakeApp, MakeApp]
classmethod from_json(json_data: Union[str, bytes, bytearray]) → App
class idf_build_apps.CMakeApp(app_dir: str, target: str, *, work_dir: Optional[str] = None, build_dir: str = 'build', build_log_filename: Optional[str] = None, size_json_filename: Optional[str] = None, build_system: typing_extensions.Literal[cmake] = 'cmake', sdkconfig_path: Optional[str] = None, config_name: Optional[str] = None, sdkconfig_defaults_str: Optional[str] = None, dry_run: bool = False, verbose: bool = False, check_warnings: bool = False, preserve: bool = True, copy_sdkconfig: bool = False, index: Optional[int] = None, build_status: BuildStatus = BuildStatus.UNKNOWN, build_comment: Optional[str] = None, cmake_vars: Dict[str, str] = {})

Bases: App

SDKCONFIG_TEST_OPTS: ClassVar[List[str]] = ['EXCLUDE_COMPONENTS', 'TEST_EXCLUDE_COMPONENTS', 'TEST_COMPONENTS']
SDKCONFIG_IGNORE_OPTS: ClassVar[List[str]] = ['TEST_GROUPS']
CMAKE_PROJECT_LINE: ClassVar[str] = 'include($ENV{IDF_PATH}/tools/cmake/project.cmake)'
build_system: typing_extensions.Literal[cmake]
app_dir: str
target: str
sdkconfig_path: t.Optional[str]
config_name: t.Optional[str]
sdkconfig_defaults_str: t.Optional[str]
dry_run: bool
verbose: bool
check_warnings: bool
preserve: bool
copy_sdkconfig: bool
index: t.Optional[int]
build_status: BuildStatus
build_comment: t.Optional[str]
cmake_vars: Dict[str, str]
classmethod is_app(path: str) → bool
class idf_build_apps.MakeApp(app_dir: str, target: str, *, work_dir: Optional[str] = None, build_dir: str = 'build', build_log_filename: Optional[str] = None, size_json_filename: Optional[str] = None, build_system: typing_extensions.Literal[make] = 'make', sdkconfig_path: Optional[str] = None, config_name: Optional[str] = None, sdkconfig_defaults_str: Optional[str] = None, dry_run: bool = False, verbose: bool = False, check_warnings: bool = False, preserve: bool = True, copy_sdkconfig: bool = False, index: Optional[int] = None, build_status: BuildStatus = BuildStatus.UNKNOWN, build_comment: Optional[str] = None)

Bases: App

MAKE_PROJECT_LINE: ClassVar[str] = 'include $(IDF_PATH)/make/project.mk'
build_system: typing_extensions.Literal[make]
property supported_targets: List[str]
classmethod is_app(path: str) → bool
app_dir: str
target: str
sdkconfig_path: t.Optional[str]
config_name: t.Optional[str]
sdkconfig_defaults_str: t.Optional[str]
dry_run: bool
verbose: bool
check_warnings: bool
preserve: bool
copy_sdkconfig: bool
index: t.Optional[int]
build_status: BuildStatus
build_comment: t.Optional[str]
idf_build_apps.build_apps(apps: Optional[Union[List[App], App]] = None, *, build_arguments: Optional[BuildArguments] = None, config_file: Optional[str] = None, **kwargs) → int

Build all the specified apps. For all kwargs, please refer to BuildArguments

Returns:

exit code

Parameters:

  • verbose (int) – Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

  • log_file (Union[str, NoneType]) – Path to the log file, if not specified logs will be printed to stderr

  • no_color (bool) – Disable colored output

  • manifest_files (Union[List[Union[pathlib.Path, str]], NoneType]) – Path to the manifest files which contains the build test rules of the apps

  • manifest_filepatterns (Union[List[str], NoneType]) – space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

  • manifest_rootpath (str) – Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

  • modified_components (Union[List[str], NoneType]) – semicolon-separated list of modified 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 (Union[List[str], NoneType]) – semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

  • deactivate_dependency_driven_build_by_components (Union[List[str], NoneType]) – semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified 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.

  • deactivate_dependency_driven_build_by_filepatterns (Union[List[str], NoneType]) – semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified 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.

  • check_manifest_rules (bool) – Check if all folders defined in the manifest files exist. Fail if not

  • compare_manifest_sha_filepath (Union[str, NoneType]) – Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

  • paths (List[str]) – Paths to the directories containing the apps. By default set to the current directory

  • target (str) – Filter the apps by target. By default set to “all”

  • build_system (Union[str, Type[idf_build_apps.app.App]]) – Filter the apps by build system. By default set to “cmake”

  • recursive (bool) – Search for apps recursively under the specified paths

  • exclude (Union[List[str], NoneType]) – Ignore the specified directories while searching recursively

  • work_dir (Union[str, NoneType]) – Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

  • build_dir (str) – Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

  • build_log_filename (Union[str, NoneType]) – Log filename under the build directory instead of stdout. Can expand placeholders

  • size_json_filename (Union[str, NoneType]) – idf.py size output file under the build directory when specified. Can expand placeholders

  • config_rules (Union[List[str], NoneType]) – Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

  • override_sdkconfig_items (Union[str, NoneType]) – A comma-separated list of key=value pairs to override the sdkconfig items

  • override_sdkconfig_files (Union[str, NoneType]) – A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

  • sdkconfig_defaults (Union[str, NoneType]) – A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

  • check_warnings (bool) – Check for warnings in the build output. Fail if any warnings are found

  • default_build_targets (Union[List[str], NoneType]) – space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

  • enable_preview_targets (bool) – When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

  • include_skipped_apps (bool) – Include the skipped apps in the output, together with the enabled ones

  • include_disabled_apps (bool) – Include the disabled apps in the output, together with the enabled ones

  • include_all_apps (bool) – Include skipped, and disabled apps in the output, together with the enabled ones

  • build_verbose (bool) – Enable verbose output of the build system

  • parallel_count (int) – Number of parallel build jobs in total. Specified together with –parallel-index. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

  • parallel_index (int) – Index (1-based) of the parallel build job. Specified together with –parallel-count. The given apps will be divided into parallel_count parts, and the current run will build the parallel_index-th part

  • dry_run (bool) – Skip the actual build, only print the build process

  • keep_going (bool) – Continue building the next app when the current build fails

  • no_preserve (bool) – Do not preserve the build directory after a successful build

  • ignore_warning_strs (Union[List[str], NoneType]) – space-separated list of patterns. Ignore the warnings in the build output that match the patterns

  • ignore_warning_files (Union[List[Union[str, _io.TextIOWrapper]], NoneType]) – Path to the files containing the patterns to ignore the warnings in the build output

  • copy_sdkconfig (bool) – Copy the sdkconfig file to the build directory

  • collect_size_info_filename (Union[str, NoneType]) – Record size json filepath of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

  • collect_app_info_filename (Union[str, NoneType]) – Record serialized app model of the built apps to the specified file. Each line is a json string. Can expand placeholders @p

  • junitxml_filename (Union[str, NoneType]) – Path to the junitxml file to record the build results. Can expand placeholder @p

idf_build_apps.find_apps(paths: Optional[Union[List[str], str]] = None, target: Optional[str] = None, *, find_arguments: Optional[FindArguments] = None, config_file: Optional[str] = None, **kwargs) → List[App]

Find apps in the given paths for the specified target. For all kwargs, please refer to FindArguments

Returns:

list of found apps

Parameters:

  • verbose (int) – Verbosity level. By default set to WARNING. Specify -v for INFO, -vv for DEBUG

  • log_file (Union[str, NoneType]) – Path to the log file, if not specified logs will be printed to stderr

  • no_color (bool) – Disable colored output

  • manifest_files (Union[List[Union[pathlib.Path, str]], NoneType]) – Path to the manifest files which contains the build test rules of the apps

  • manifest_filepatterns (Union[List[str], NoneType]) – space-separated list of file patterns to search for the manifest files. The matched files will be loaded as the manifest files.

  • manifest_rootpath (str) – Root path to resolve the relative paths defined in the manifest files. By default set to the current directory

  • modified_components (Union[List[str], NoneType]) – semicolon-separated list of modified 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 (Union[List[str], NoneType]) – semicolon-separated list of modified files. If set to “”, the value would be considered as None. If set to “;”, the value would be considered as an empty list.

  • deactivate_dependency_driven_build_by_components (Union[List[str], NoneType]) – semicolon-separated list of components. dependency-driven build feature will be deactivated when any of these components are modified. Must be specified 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.

  • deactivate_dependency_driven_build_by_filepatterns (Union[List[str], NoneType]) – semicolon-separated list of file patterns. dependency-driven build feature will be deactivated when any of matched files are modified. Must be specified 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.

  • check_manifest_rules (bool) – Check if all folders defined in the manifest files exist. Fail if not

  • compare_manifest_sha_filepath (Union[str, NoneType]) – Path to the file containing the hash of the manifest rules. Compare the hash with the current manifest rules. All matched apps will be built if the corresponding manifest rule is modified

  • paths (List[str]) – Paths to the directories containing the apps. By default set to the current directory

  • target (str) – Filter the apps by target. By default set to “all”

  • build_system (Union[str, Type[idf_build_apps.app.App]]) – Filter the apps by build system. By default set to “cmake”

  • recursive (bool) – Search for apps recursively under the specified paths

  • exclude (Union[List[str], NoneType]) – Ignore the specified directories while searching recursively

  • work_dir (Union[str, NoneType]) – Copy the app to this directory before building. By default set to the app directory. Can expand placeholders

  • build_dir (str) – Build directory for the app. By default set to “build”. When set to relative path, it will be treated as relative to the app directory. Can expand placeholders

  • build_log_filename (Union[str, NoneType]) – Log filename under the build directory instead of stdout. Can expand placeholders

  • size_json_filename (Union[str, NoneType]) – idf.py size output file under the build directory when specified. Can expand placeholders

  • config_rules (Union[List[str], NoneType]) – Defines the rules of building the project with pre-set sdkconfig files. Supports FILENAME[=NAME] or FILEPATTERN format. FILENAME is the filename of the sdkconfig file, relative to the app directory. Optional NAME is the name of the configuration. if not specified, the filename is used as the name. FILEPATTERN is the filename of the sdkconfig file with a single wildcard character (*). The NAME is the value matched by the wildcard

  • override_sdkconfig_items (Union[str, NoneType]) – A comma-separated list of key=value pairs to override the sdkconfig items

  • override_sdkconfig_files (Union[str, NoneType]) – A comma-separated list of sdkconfig files to override the sdkconfig items. When set to relative path, it will be treated as relative to the current directory

  • sdkconfig_defaults (Union[str, NoneType]) – A semicolon-separated list of sdkconfig files passed to idf.py -DSDKCONFIG_DEFAULTS. SDKCONFIG_DEFAULTS environment variable is used when not specified

  • check_warnings (bool) – Check for warnings in the build output. Fail if any warnings are found

  • default_build_targets (Union[List[str], NoneType]) – space-separated list of the default enabled build targets for the apps. When not specified, the default value is the targets listed by idf.py –list-targets

  • enable_preview_targets (bool) – When enabled, the default build targets will be set to all apps, including the preview targets. As the targets defined in idf.py –list-targets –preview

  • include_skipped_apps (bool) – Include the skipped apps in the output, together with the enabled ones

  • include_disabled_apps (bool) – Include the disabled apps in the output, together with the enabled ones

  • include_all_apps (bool) – Include skipped, and disabled apps in the output, together with the enabled ones

  • output (Union[str, NoneType]) – Record the found apps to the specified file instead of stdout

  • output_format (str) – Output format of the found apps. In “raw” format, each line is a json string serialized from the app model. In “json” format, the output is a json list of the serialized app models

idf_build_apps.json_to_app(json_str: str, extra_classes: Optional[List[Type[App]]] = None) → App

Deserialize json string to App object

Note

You can pass extra_cls to support custom App class. A custom App class must be a subclass of App, and have a different value of build_system. For example, a custom CMake app

class CustomApp(CMakeApp):
    build_system: Literal['custom_cmake'] = 'custom_cmake'

Then you can pass the CustomApp class to the extra_cls argument

json_str = CustomApp('.', 'esp32').to_json()
json_to_app(json_str, extra_classes=[CustomApp])
Parameters:

  • json_str – json string

  • extra_classes – extra App class

Returns:

App object

idf_build_apps.setup_logging(verbose: int = 0, log_file: Optional[str] = None, colored: bool = True) → None

Setup logging stream handler

Parameters:

  • verbose – 0 - WARNING, 1 - INFO, 2 - DEBUG

  • log_file – log file path

  • colored – colored output or not

Returns:

None