Migrating from 2.x to 3.0

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.

Major PlatformIO CLI changes

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 platform

platformio serialports

platformio device

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.

What is new

Development Platforms

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.

  • Manifest File platform.json

  • 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

Library Manager and Intelligent Build System

  • 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

Command Line Interface

We have added new commands and changed some existing ones. Here are the new or updated commands and options.

Command

Description

platformio boards

Returns all supported boards by PlatformIO

platformio boards --installed

Returns currently installed boards

platformio ci --project-option

Pass custom option from “platformio.ini” (Project Configuration File)

platformio ci --verbose

Print detailed information about build process

platformio init --project-option

Pass custom option from “platformio.ini” (Project Configuration File)

platformio lib --global

Manage PlatformIO Global Library Storage

platformio lib --storage-dir

Manage Custom Library Storage

platformio lib install

New PlatformIO 3.0 Library Manager! Semantic Versioning, VCS support and external URL support

platformio lib install --silent

Suppress progress reporting when install library

platformio lib install --interactive

Allow to make a choice for all prompts when install library

platformio lib search --header

Search library by specific header file name (include)

platformio lib update --only-check

Do not update, only check for new version

platformio platform

New PlatformIO 3.0 Platform Manager! Semantic Versioning, VCS support and external URL support.

platformio platform update --only-packages

Update only platform packages

platformio platform update --only-check

Do not update, only check for new version

platformio run

By default, prints only human-readable information when processing environments

platformio run --verbose

Print detailed processing information

platformio settings set force_verbose true

Force verbose output when processing environments (globally)

platformio test

PIO Plus Unit Testing

platformio update --only-check

Do not update, only check for new version

“platformio.ini” (Project Configuration File)

We have added new options and changed some existing ones. Here are the new or updated options.

Section

Option

Description

platformio

libdeps_dir

Internal storage where Library Manager will install project dependencies

platformio

test_dir

Directory where PIO Unit Testing engine will look for the tests

env

lib_deps

Specify project dependencies that should be installed automatically to libdeps_dir before environment processing.

env

platform

PlatformIO 3.0 allows to use specific version of platform using Semantic Versioning (X.Y.Z=MAJOR.MINOR.PATCH).

env

lib_extra_dirs

A list with extra directories/storages where Library Dependency Finder (LDF) will look for dependencies

env

lib_ldf_mode

This option specifies how does Library Dependency Finder (LDF) should analyze dependencies (#include directives)

env

lib_compat_mode

Library compatibility mode allows to control strictness of Library Dependency Finder (LDF)

env

test_ignore

Ignore tests where the name matches specified patterns

What is removed

Command Line Interface

The following commands have been dropped or changed in v3.0.

Command

Description

platformio init –enable-auto-uploading

Use platformio init --project-option instead of it with targets = upload value

“platformio.ini” (Project Configuration File)

The following options have been dropped or changed in v3.0.

Section

Option

Description

platformio

lib_dir

Changed: Project’s own/private libraries, where in PlatformIO 2.x it was global library storage