Build Commands

The IDF CI tool provides commands for building applications. The idf-ci build commands allow you to build applications and manage build configurations.

Build Commands

Run Build

To execute the build process for applications, use the run command:

idf-ci build run [OPTIONS]

This command builds applications based on the specified options and paths.

Options:

--paths PATHS - Paths to process
--target TARGET - Target to be processed (default: all)
--parallel-count COUNT - Number of parallel builds
--parallel-index INDEX - Index of parallel build (1-based)
--modified-files FILES - List of modified files
--only-test-related - Run build only for test-related apps
--only-non-test-related - Run build only for non-test-related apps
--dry-run - Run build in dry-run mode
--build-system SYSTEM - Filter the apps by build system. Can be “cmake”, “make” or a custom App class path (default: cmake)
--marker-expr EXPR - Pytest marker expression
--filter-expr EXPR - Pytest filter expression

Examples:

# Build all applications
idf-ci build run

# Build specific applications
idf-ci build run --paths /path/to/app1 /path/to/app2

# Build for a specific target
idf-ci build run --target esp32

# Build only test-related applications
idf-ci build run --only-test-related

# Build applications using make build system
idf-ci build run --build-system make

# Build with parallel processing
idf-ci build run --parallel-count 4 --parallel-index 1

Initialize Build Configuration

To create a build configuration file with default values, use the init command:

idf-ci build init [OPTIONS]

Options:

--path PATH - Path to create the config file

Example:

# Create build configuration file in current directory
idf-ci build init

# Create build configuration file in specific directory
idf-ci build init --path /path/to/config

Collect Applications

This command collects all applications, corresponding test cases and outputs the result in JSON format.

idf-ci build collect [OPTIONS]

Options:

--paths PATHS - Paths to search for applications. If not provided, current directory is used
--output OUTPUT - Output destination. If not provided, stdout is used
--include-only-enabled - Include only enabled applications

Output format:

{
    "summary": {
        "total_projects": 1,
        "total_apps": 1,
        "total_test_cases": 4,
        "total_test_cases_used": 1,
        "total_test_cases_disabled": 2,
        "total_test_cases_requiring_nonexistent_app": 1
    },
    "projects": {
        "path/to/project": {
            "apps": [
                {
                    "target": "esp32",
                    "sdkconfig": "release",
                    "build_status": "should be built",
                    "build_comment": "",
                    "test_comment": "Disabled by manifest rule: IDF_TARGET == \"esp32\" (reason: Disabled test for esp32)",
                    "test_cases": [
                        {
                            "name": "test_case_1",
                            "caseid": "esp32.release.test_case_1"
                        },
                        {
                            "name": "test_case_2",
                            "caseid": "esp32.release.test_case_2",
                            "disabled": true,
                            "disabled_by_manifest": false,
                            "disabled_by_marker": true,
                            "skip_reason": "skipped by marker"
                        },
                        {
                            "name": "test_case_3",
                            "caseid": "esp32.release.test_case_3",
                            "disabled": true,
                            "disabled_by_manifest": true,
                            "disabled_by_marker": false,
                            "test_comment": "Disabled by manifest rule: IDF_TARGET == \"esp32\" (reason: Disabled test for esp32)"
                        }
                    ]
                }
            ],
            "test_cases_requiring_nonexistent_app": [
                "esp32.default.test_case_4"
            ]
        }
    }
}

Examples:

# Collect applications in current directory
idf-ci build collect

# Collect applications in specified directories
idf-ci build collect --paths /path/to/dir1 /path/to/dir2

# Collect applications and output to a file
idf-ci build collect --output /path/to/output.json

# Collect only enabled applications
idf-ci build collect --include-only-enabled