How to use the command 'pio run' (with examples)
The pio run command is a fundamental tool in the PlatformIO ecosystem for building and managing project tasks. PlatformIO is an open-source ecosystem used for IoT development, compatible with over 40 development platforms, 800+ embedded boards, and 35+ development frameworks. The pio run command enables developers to compile, upload, and perform various tasks defined within a PlatformIO project. It provides control over different environments and configurations, allowing for tailored and efficient project management.
Use case 1: List all available project targets
Code:
pio run --list-targets
Motivation:
Listing all available project targets is essential for understanding what actions can be performed on your project. In a complex project, numerous targets might be defined, such as building, uploading, and cleaning. By listing these targets, you gain clarity on the tasks that can be executed automatically, streamlining your workflow.
Explanation:
pio run: Initiates the command to run PlatformIO tasks.--list-targets: This argument specifies that the command should list all the potential tasks or actions available in the project, without actually performing them.
Example Output:
Environment/Target Action
----------------------- --------------
env:esp32dev:build Compile project
env:esp32dev:upload Upload program to device
env:esp32dev:clean Clean project output files
Use case 2: List all available project targets of a specific environment
Code:
pio run --list-targets --environment environment
Motivation:
Focusing on a specific environment’s targets can be beneficial when a project is set up for multiple platforms or frameworks. Each environment might have different requirements or targets, and you might only be interested in the targets for a specific environment. This command helps you zero in on the actions available for a particular setup.
Explanation:
pio run: Executes the core command for managing PlatformIO tasks.--list-targets: Instructs the tool to display available tasks.--environment environment: Restricts the output to the specified environment, where “environment” should be replaced with the actual environment name you are investigating.
Example Output:
Target Action
----------------------- --------------
build Compile project
upload Upload program to device
clean Clean project output files
Use case 3: Run all targets
Code:
pio run
Motivation:
Running all targets is particularly useful for fully managing the lifecycle of a project. This is often necessary for building all components, uploading them to the device, and ensuring the system is clean and ready for use in one smooth action.
Explanation:
pio run: The default execution of this command without additional arguments runs all defined targets for the current environment(s). It will consider the targets defined in the default or active PlatformIO environments specified in the project’s configuration file.
Example Output:
Processing esp32dev (platform: espressif32; board: esp32dev)
-----------------------------------------------------------------
Building...
Uploading...
Done!
Use case 4: Run all targets of specified environments
Code:
pio run --environment environment1 --environment environment2
Motivation:
In a multi-environment setup, you may need to build and execute targets only for a particular subset. This command allows for executing all targets across several specified environments in one command execution, streamlining work for projects with diverse hardware targets.
Explanation:
pio run: Initiates the command to perform tasks.--environment environment1: Directs the command to execute all targets within “environment1”.--environment environment2: Additionally processes all targets within “environment2”, thus enabling multi-environment processing simultaneously.
Example Output:
Processing environment1 (platform: platformA; board: boardA)
-----------------------------------------------------------------
Building...
Uploading...
Processing environment2 (platform: platformB; board: boardB)
-----------------------------------------------------------------
Building...
Uploading...
Done!
Use case 5: Run specified targets
Code:
pio run --target target1 --target target2
Motivation:
Sometimes, specific targets need to be run without the overhead of executing all available ones. This selective execution can save time and resources, making it optimal for iterative testing or deployment tasks that do not require a full sequence of operations.
Explanation:
pio run: Conducts the core operation of running tasks.--target target1: Identifies “target1” as a task to execute, where “target1” should be replaced with the actual name of the target you wish to perform.--target target2: Executes an additional specified task labeled as “target2.”
Example Output:
Executing target1...
Executing target2...
Done!
Use case 6: Run the targets of a specified configuration file
Code:
pio run --project-conf path/to/platformio.ini
Motivation:
When a project requires a specific set of configurations distinct from the default settings, specifying an alternate configuration file enables developers to easily switch contexts or requirements, ensuring the correct targets are built according to unique project demands.
Explanation:
pio run: Begins the process to run defined tasks.--project-conf path/to/platformio.ini: Specifies a path to an alternate PlatformIO configuration file (ini), allowing the command to use custom settings and targets defined within it.
Example Output:
Reading custom configuration file: path/to/platformio.ini
Processing with specified configuration...
Building...
Uploading...
Done!
Conclusion:
Using pio run effectively allows developers to manage and execute tasks within their PlatformIO projects with precision. By understanding and utilizing its various options, such as environment specification and target selection, developers can optimize their workflows for complex IoT and embedded applications. Each provided use case demonstrates how this command can enhance productivity and control within diverse project scenarios.
