pio-ci

Build a PlatformIO project in the default system temporary directory and delete it afterwards

$ pio ci [path/to/project]

$ pio ci [[-l|--lib]] [path/to/library_directory] [path/to/project]

$ pio ci [[-b|--board]] [board] [path/to/project]

$ pio ci --build-dir [path/to/build_directory] [path/to/project]

$ pio ci --keep-build-dir [path/to/project]

$ pio ci [[-c|--project-conf]] [path/to/platformio.ini]

pio ci [OPTIONS] [PATH]

PATH
    Path to the project directory or a specific source file to build. If omitted, the current working directory is used.

-l, --lib <path>
    Specify a path to a library that should be used during the build process. This option can be used multiple times for different libraries.

-c, --project-conf <path>
    Provide a custom path to the platformio.ini project configuration file, overriding the default location.

-e, --environment <name>
    Build against a specific PlatformIO environment defined in the platformio.ini file. Can be specified multiple times to build for several environments.

-b, --board <id>
    Build for a specific board ID. This is useful when an environment is not explicitly defined or to override an environment's board setting.

-s, --src <path>
    Specify a path to a source file or directory within the project to build, rather than compiling the entire project.

-k, --keep-storage
    Prevent the .pio build environment storage directory from being cleaned after the CI run completes.

--skip-library-check
    Skip the check for whether all project dependencies (external libraries) are installed before initiating the build process.

-D, --project-option <key=value>
    Add or override project options for the current CI run. For example, `-D debug_level=3`.

--test
    Execute unit tests after the project has been successfully built. Requires tests to be configured within the platformio.ini file.

--test-filter <pattern>
    When `--test` is used, this option filters the unit tests to be run based on a specified pattern.

The pio ci command, part of the PlatformIO Core CLI, is specifically designed for Continuous Integration (CI) of embedded software projects. It enables developers to automate the compilation, static analysis, and unit testing of their firmware directly within CI/CD pipelines (e.g., Travis CI, GitHub Actions, GitLab CI, Jenkins).

It allows building projects against specific PlatformIO environments, for particular boards, and with custom configurations, making it invaluable for ensuring code quality and functionality throughout the development lifecycle without requiring a full IDE. It can also run unit tests configured within the project, providing immediate feedback on code changes and helping to catch regressions early.

The pio ci command is part of the PlatformIO Core CLI and requires PlatformIO to be installed and configured on the system. It is primarily designed for embedded software development workflows and may not be applicable for general-purpose Linux programming tasks. Its effectiveness is highly dependent on a correctly structured platformio.ini file and proper integration with a CI/CD service.

PlatformIO projects are configured using environments defined within the platformio.ini file. Each environment specifies unique settings such as the target board, development framework, upload protocol, and build flags. The pio ci command leverages these environments, enabling developers to build and test the same codebase for different hardware targets or toolchains within a single CI job, enhancing flexibility and coverage.

The primary benefit of pio ci stems from its seamless integration with external CI/CD services. By executing pio ci commands within a CI script (e.g., .travis.yml, .github/workflows/*.yml), developers can automate the compilation and testing of their code every time changes are pushed to the repository. This automated process ensures code quality and helps to identify and fix regressions early in the development cycle. The command's exit code (0 for success, non-zero for failure) is used by CI services to determine the job's overall status.

PlatformIO, an open-source ecosystem founded by Ivan Kravets, was created to streamline and standardize IoT and embedded development. The pio ci command was introduced as a key feature to integrate modern DevOps and Continuous Integration/Delivery (CI/CD) practices into the embedded software development lifecycle. Its ongoing development focuses on providing a versatile and robust tool that integrates seamlessly with various CI services, addressing the unique challenges of building and testing firmware across diverse hardware and software configurations.

pio run (PlatformIO CLI), pio test (PlatformIO CLI), git(1) (for version control and CI triggers), make(1) (general build automation tool), cmake(1) (cross-platform build system generator)