Migrating from 4.x to 5.0¶
Guidance on how to upgrade from PlatformIO Core (CLI) v4.x to v5.x with emphasis on major changes, what is new, and what has been removed.
PlatformIO Core 5.0 is fully backward compatible with PlatformIO 4.0 projects.
Please read PlatformIO 5.0 Release Notes before.
Contents
Migration Steps¶
- Ensure that you do not use a short version of the Github declaration in lib_deps.
Please use
https://github.com/username/repo.git
instead ofusername/repo
. - We recommend updating your project dependency declarations in lib_deps using a new owner-based syntax. See the Library Manager section for details.
What is new¶
In this section, we are going to highlight the most important changes and features introduced in PlatformIO Core (CLI) 5.0. Please visit PlatformIO 5.0 Release Notes for more detailed information.
PlatformIO Trusted Registry¶
PlatformIO Core 5.0 has been switched to the official PlatformIO Trusted Registry:
- Enterprise-grade package storage with high availability (multi replicas)
- Secure, fast, and reliable global content delivery network (CDN)
- Universal support for all packages:
- Libraries
- Development platforms
- Toolchains
- Built-in fine-grained access control (role-based, teams, organizations).
The new Web front-end and upgraded PlatformIO Home are coming soon.
Collaborative Platform¶
PlatformIO Core 5.0 is fully unlocked for developers and teams. They can now share their packages (libraries, Development Platforms, toolchains) with team members or collaborate on open source projects. There are new CLI commands that help you to manage organizations, teams, team memberships, and resource access:
- pio package – manage packages in the registry
- pio org - manage organizations
- pio team - manage teams and team memberships
- pio access – manage package access for users, teams, and maintainers.
Package Management¶
The package management infrastructure has been rewritten from scratch. It is based now on the new PlatformIO Trusted Registry that supports a strict dependency declaration using the package owner. This improvement resolves the issues when package maintainers publish packages under the same name.
PlatformIO Core 5.0 does not handle packages from unofficial repositories declared via
packageRepositories
in platform.json
. There were a lot of security issues and
reports when PlatformIO Core 4.0 hangs when you manage external dependencies.
PlatformIO Core 5.0 uses THE ONLY official PlatformIO Trusted Registry that supports not only the libraries but also Development Platforms and toolchains.
Package maintainers can publish their libraries, development platforms, and toolchains to the registry using pio package CLI.
Library Manager¶
The biggest improvement for Library Management is the owner-based dependency declaration.
You can finally forget about conflicts with library names in the registry. Use the new
syntax ownername/pkgname
to declare an owner-based dependency in “platformio.ini” (Project Configuration File)
via lib_deps:
[env:myenv]
platform = ...
framework = ...
board = ...
lib_deps =
bblanchon/ArduinoJson @ ^6.16.1
knolleary/PubSubClient @ ^2.8
You can find an owner name of a library in the registry using PlatformIO Home > Libraries > Some Library > Installation tab.
Build System¶
SCons 4.0¶
PlatformIO Core 5.0 build engine has been upgraded to the latest SCons 4.0 - a next-generation software construction tool:
- Configuration files are Python scripts – use the power of a real programming language to solve build problems
- Built-in reliable and automatic dependency analysis
- Improved support for parallel builds
- Ability to share built files in a cache to speed up multiple builds.
Custom Targets¶
PlatformIO Core 5.0 gives more freedom to developers and Development Platforms maintainers. They can now declare the Custom Targets:
- Pre/Post processing based on dependent sources (another target, source file, etc.)
- Command launcher with own arguments
- Launch command with custom options declared in “platformio.ini” (Project Configuration File)
- Python callback as a target (use the power of Python interpreter and PlatformIO Build API)
- List available project targets (including dev-platform specific and custom targets) with a new
pio run --list-targets
command
See Build System section in PlatformIO Core 5 release notes for more details.
What is changed or removed¶
Introducing Strict SSL/TLS¶
The setting strict_ssl
has been removed from pio settings. Now, PlatformIO Core 5.0
communicates over the encrypted SSL/TLS by default with the PlatformIO Registry and
other services such as Remote Development.
At PlatformIO, we are always looking for ways to improve the security of our services.
packageRepositories¶
PlatformIO Core 5.0 does not support unofficial package repositories declared through
packageRepositories
in platform.json
that was introduced in PlatformIO 3.0.
Please publish your development platforms and toolchains to the PlatformIO Trusted Registry using pio package CLI.
Command Line Interface¶
The following commands have been changed in v5.0.
Command | Description |
---|---|
pio access | New. Manage package access for users, teams, and maintainers |
pio package | New. Manage packages in the registry (publish, unpublish) |
pio project data | New. Dump build system data intended for IDE extensions/plugins |
pio system info | New. Display system-wide information |
pio system prune | New. Remove unused data |
pio project init | Update project configuration for the specific environment using pio project init --environment option |
pio run | List projects targets with pio run --list-targets option |
pio account destroy | New command to remove permanently PlatformIO Account and related data |