Guidance on how to upgrade from PlatformIO v2.x to v3.x with emphasis on major changes, what is new, and what is been removed.
PlatformIO 3 is not backwards compatible with v2.x. Use this section as a general guide to upgrading from v2.x to v3.0. For a broader overview, see what is new in the v3.0 release announcement.
Note
PlatformIO 3.x is 100% non-blocking! You do not need to use --force
option or setup special PLATOFMRIO_SETTING_ENABLE_PROMPTS environment.
Use PlatformIO 3.0 with sub-processing without any risk!
This table shows the CLI changes between v2.x and v3.0.
PlatformIO 2.x |
PlatformIO 3.x |
|---|---|
platformio platforms |
|
platformio serialports |
|
platformio settings set enable_prompts false |
Removed! Now, all PlatformIO 3.0 CLI is 100% non-blocking! |
PlatformIO 2.x commands will be converted to PlatformIO 3.x automatically. Nevertheless, we recommend to use PlatformIO 3.x commands for the new projects.
We have introduced Manifest File platform.json and ported PlatformIO 2.x development platforms according PlatformIO 3.0 decentralized architecture. Now, platform related things (build scrips, LD scripts, board configs, package requirements) are located in own repository. Here is the full list with PlatformIO 3.0 open source development platforms. You can fork it, modify or create custom. See Custom Development Platform guide for details.
espressif development platform has been renamed to Espressif 8266
PlatformIO 3.0 Platform Manager
Custom package repositories
External embedded board configuration files, isolated build scripts
Embedded Board compatibility with more than one development platform
Powerful and super-fast Library Dependency Finder (LDF) that interprets C/C++ Preprocessor conditional macros with deep search behavior
Project dependencies per build environment using projectconf_lib_deps option
Depend on a library using VCS URL (GitHub, Git, ARM mbed code registry, Hg, SVN)
Install library by name
Strict search for library dependencies
Multiple library storages: Project’s Local, PlatformIO’s Global or Custom
Allowed library.json to specify sources other than PlatformIO’s Repository
Check library compatibility with project environment before building
Control Library Dependency Finder for compatibility using lib_compat_mode option
Custom library storages/directories with lib_extra_dirs option
Handle extra build flags, source filters and build script from library.json
Allowed to disable library archiving (*.ar)
Show detailed build information about dependent libraries (Library Dependency Graph)
Support for the 3rd party manifests (Arduino IDE “library.properties” and ARM mbed “module.json”)
Build System: Attach custom Before/Pre and After/Post actions for targets using extra_scripts
We have added new commands and changed some existing ones. Here are the new or updated commands and options.
Command |
Description |
|---|---|
Returns all supported boards by PlatformIO |
|
Returns currently installed boards |
|
Pass custom option from “platformio.ini” (Project Configuration File) |
|
Print detailed information about build process |
|
Pass custom option from “platformio.ini” (Project Configuration File) |
|
Manage PlatformIO Global Library Storage |
|
Manage Custom Library Storage |
|
New PlatformIO 3.0 Library Manager! Semantic Versioning, VCS support and external URL support |
|
Suppress progress reporting when install library |
|
Allow to make a choice for all prompts when install library |
|
Search library by specific header file name (include) |
|
Do not update, only check for new version |
|
New PlatformIO 3.0 Platform Manager! Semantic Versioning, VCS support and external URL support. |
|
Update only platform packages |
|
Do not update, only check for new version |
|
By default, prints only human-readable information when processing environments |
|
Print detailed processing information |
|
Force verbose output when processing environments (globally) |
|
PIO Plus Unit Testing |
|
Do not update, only check for new version |
We have added new options and changed some existing ones. Here are the new or updated options.
Section |
Option |
Description |
|---|---|---|
platformio |
Internal storage where Library Manager will install project dependencies |
|
platformio |
Directory where PIO Unit Testing engine will look for the tests |
|
env |
Specify project dependencies that should be installed automatically to libdeps_dir before environment processing. |
|
env |
PlatformIO 3.0 allows to use specific version of platform using Semantic Versioning (X.Y.Z=MAJOR.MINOR.PATCH). |
|
env |
A list with extra directories/storages where Library Dependency Finder (LDF) will look for dependencies |
|
env |
This option specifies how does Library Dependency Finder (LDF) should analyze dependencies ( |
|
env |
Library compatibility mode allows to control strictness of Library Dependency Finder (LDF) |
|
env |
Ignore tests where the name matches specified patterns |
The following commands have been dropped or changed in v3.0.
Command |
Description |
|---|---|
platformio init –enable-auto-uploading |
Use |
The following options have been dropped or changed in v3.0.
Section |
Option |
Description |
|---|---|---|
platformio |
Changed: Project’s own/private libraries, where in PlatformIO 2.x it was global library storage |