How to Use the `pio ci` Command (with Examples)

The pio ci command is an essential tool in the PlatformIO ecosystem for Continuous Integration (CI). It allows users to build PlatformIO projects while working with an arbitrary source code structure, which is particularly useful in environments where the conventional project structure isn’t maintained. The command creates a temporary project where the core source code is copied, compiled, and then, by default, discarded after the build process. This flexibility makes it a powerful tool for developers who need to prototype, test, or deploy applications in a structured and automated manner.

Use Case 1: Build a PlatformIO Project in the Default System Temporary Directory and Delete It Afterwards

Code:

pio ci path/to/project

Motivation:

This use case is ideal for scenarios where a developer needs to quickly verify that a project’s source code is correctly configured and compiles without errors. By building in the default system temporary directory and deleting it afterwards, it reduces clutter on the system and ensures that the build environment doesn’t affect other projects.

Explanation:

• pio ci: This is the command to invoke the build process using PlatformIO’s CI utility.
• path/to/project: This argument specifies the path to the project that needs to be built. The command copies the project files into a temporary directory, compiles them, and then deletes the temporary files upon completion.

Example Output:

Building project in /tmp/tmpabcs1234
Compiling...
... 
Build completed successfully.
Temporary files have been deleted.

Use Case 2: Build a PlatformIO Project and Specify Specific Libraries

Code:

pio ci --lib path/to/library_directory path/to/project

Motivation:

Specifying libraries manually is beneficial when a project depends on specific versions of libraries or custom libraries not available in the PlatformIO repository. This use case is crucial in scenarios that require precise control over the dependencies included in the build.

Explanation:

• --lib path/to/library_directory: This flag allows users to point to a directory containing the required libraries. It’s particularly useful for projects that need specialized libraries or certain library versions.
• path/to/project: This specifies the project directory to be built, as usual.

Example Output:

Using local library in /path/to/library_directory
Building project...
Compiling...
...
Build completed successfully.

Use Case 3: Build a PlatformIO Project and Specify a Specific Board

Code:

pio ci --board board path/to/project

Motivation:

Different projects target different hardware platforms. By specifying a specific board, the developer ensures that the build process aligns with the board’s architecture and capabilities, yielding a correctly configured binary.

Explanation:

• --board board: This parameter specifies the target hardware board to use from PlatformIO’s list of supported boards.
• path/to/project: Indicates the project to be built.

Example Output:

Selected board: Arduino Uno
Building project for Arduino Uno...
Compiling...
...
Build completed successfully.

Use Case 4: Build a PlatformIO Project in a Specific Directory

Code:

pio ci --build-dir path/to/build_directory path/to/project

Motivation:

For developers needing to organize build artifacts and outputs in a specific location, perhaps for sharing with a team or deploying to another environment, setting a custom build directory is essential.

Explanation:

• --build-dir path/to/build_directory: This option specifies the directory where the build process should output its files, contrary to the default temporary directory.
• path/to/project: The path to the project as input.

Example Output:

Building project in /path/to/build_directory
Compiling...
...
Build completed successfully.
Artifacts saved in /path/to/build_directory

Use Case 5: Build a PlatformIO Project and Don’t Delete the Build Directory

Code:

pio ci --keep-build-dir path/to/project

Motivation:

Keeping the build directory is useful for debugging. By examining the intermediate files and outputs, developers can gain insight into build errors and warnings, facilitating better troubleshooting.

Explanation:

• --keep-build-dir: This flag instructs the command not to delete the build directory, preserving all generated files for inspection.
• path/to/project: This points again to the project directory to be built.

Example Output:

Building project in /tmp/tmpdefg5678
Compiling...
...
Build completed successfully.
Build artifacts have been retained in /tmp/tmpdefg5678

Use Case 6: Build a PlatformIO Project Using a Specific Configuration File

Code:

pio ci --project-conf path/to/platformio.ini

Motivation:

Projects often have multiple configurations (e.g., debug vs. release), and specifying the configuration file allows developers to enforce a particular setup or build mode without modifying any source files directly.

Explanation:

• --project-conf path/to/platformio.ini: This argument allows the user to specify an alternative platformio.ini configuration file, overriding the default settings.
• By providing this file, different build settings, environments, or options can be specified.

Example Output:

Loading configuration from /path/to/platformio.ini
Building according to specified configurations...
Compiling...
...
Build completed successfully.

Conclusion:

The pio ci command provides considerable flexibility when building PlatformIO projects, making it indispensable for developers who need to work in automated or unconventional environments. By leveraging its various options and arguments, developers can control their build processes to suit specific needs, focusing on efficiency and productivity.