Manifest File

A .build-test-rules.yml file is the manifest file to control whether the app will be built or tested under the rules.

One typical manifest file look like this:

[folder]:
  enable:
    - if: [if clause]
      temporary: true  # optional, default to false. `reason` is required if `temporary` is true
      reason: [your reason]  # optional
    - ...
  disable:
    - if: [if clause]
    - ...
  disable_test:
    - if: [if clause]
    - ...

if Clauses

Operands

  • Capitalized Words

    • Variables defined in IDF_PATH/components/soc/[TARGET]/include/soc/*_caps.h or in IDF_PATH/components/esp_rom/[TARGET]/*_caps.h. e.g., SOC_WIFI_SUPPORTED, ESP_ROM_HAS_SPI_FLASH

    • IDF_TARGET

    • IDF_VERSION (IDF_VERSION_MAJOR.IDF_VERSION_MINOR.IDF_VERSION_PATCH. e.g., 5.2.0. Will convert to Version object to do a version comparison instead of a string comparison)

    • IDF_VERSION_MAJOR

    • IDF_VERSION_MINOR

    • IDF_VERSION_PATCH

    • INCLUDE_DEFAULT (The default value of officially supported targets is 1, otherwise is 0)

    • CONFIG_NAME (config name defined in Config Rules)

    • environment variables, default to 0 if not set

  • String, must be double-quoted. e.g., "esp32", "12345"

  • Integer, support decimal and hex. e.g., 1, 0xAB

  • List of strings or integers, or both types at the same time. e.g., ["esp32", 1]

Operators

  • ==, !=, >, >=, <, <=

  • and, or

  • in, not in with list

  • parentheses

Limitations

All operators are binary operators. For more than two operands, you may use the nested parentheses trick. For example:

  • A == 1 or (B == 2 and C in [1,2,3])

  • (A == 1 and B == 2) or (C not in ["3", "4", 5])

Enable/Disable Rules

By default, we enable build and test for all supported targets. In other words, if an app supports all supported targets, it does not need to be added in a manifest file. The manifest files are files that set the violation rules for apps.

Three rules (disable rules are calculated after the enable rule):

  • enable: run CI build/test jobs for targets that match any of the specified conditions only

  • disable: will not run CI build/test jobs for targets that match any of the specified conditions

  • disable_test: will not run CI test jobs for targets that match any of the specified conditions

Each key is a folder. The rule will recursively apply to all apps inside.

Overrides Rules

If one sub folder is in a special case, you can overwrite the rules for this folder by adding another entry for this folder itself. Each folder’s rules are standalone, and will not inherit its parent’s rules. (YAML inheritance is too complicated for reading)

For example, in the following code block, only disable rule exists in examples/foo/bar. It’s unaware of its parent’s enable rule.

examples/foo:
  enable:
    - if: IDF_TARGET == "esp32"

examples/foo/bar:
  disable:
    - if: IDF_TARGET == "esp32s2"

Practical Example

Here’s a practical example:

examples/foo:
  enable:
    - if IDF_TARGET in ["esp32", 1, 2, 3]
    - if IDF_TARGET not in ["4", "5", 6]
  # should be run under all targets!

examples/bluetooth:
  disable:  # disable both build and tests jobs
    - if: SOC_BT_SUPPORTED != 1
    # reason is optional if there's no `temporary: true`
  disable_test:
    - if: IDF_TARGET == "esp32"
      temporary: true
      reason: lack of ci runners  # required when `temporary: true`

examples/bluetooth/test_foo:
  # each folder's settings are standalone
  disable:
    - if: IDF_TARGET == "esp32s2"
      temporary: true
      reason: no idea
  # unlike examples/bluetooth, the apps under this folder would not be build nor test for "no idea" under target esp32s2

examples/get-started/hello_world:
  enable:
    - if: IDF_TARGET == "linux"
      reason: this one only supports linux!

examples/get-started/blink:
  enable:
    - if: INCLUDE_DEFAULT == 1 or IDF_TARGET == "linux"
      reason: This one supports all supported targets and linux

Check App Dependencies

idf-build-apps also supports building only related apps by checking app dependencies via modified components and modified files.

Basic Usage

To enable this feature, you need to declare the modified files or components using the CLI option:

  • --modified-files

  • --modified-components

To declare the dependencies for an app, you could add two more keywords in the corresponding manifest file:

  • depends_components

  • depends_filepatterns

One app will be built when:

  • The app itself is modified (.md files are excluded)

  • Any of the specified depends_components in the corresponding manifest file are modified

  • Files that matches any of the specified depends_filepatterns in the corresponding manifest file are modified

  • Any of the build_components are modified. build_components are defined in the project_description.json, which is generated by running idf.py reconfigure or idf.py build

For example, this is an app example/foo, which depends on comp1, comp2, comp3 and all files under common_header_files:

examples/foo:
  depends_components:
    - comp1
    - comp2
    - comp3
  depends_files:
    - "common_header_files/**/*"

This app will be built with the following CLI options:

  • --modified-files examples/foo/main/foo.c

  • --modified-components comp1

  • --modified-components comp2 comp3

  • --modified-files common_header_files/foo.h

This app will not be built with the following CLI options:

  • --modified-files examples/foo/main/foo.md

  • --modified-components bar

  • /tmp/foo.c

Advanced Usage

Sometimes, we have some root dependencies. All apps should be built if these root dependencies are modified.

After adding --ignore-app-dependencies-filepatterns to the CLI options, if files that matches any of the specified patterns are modified, the check app dependency feature will be disabled.