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 Project Configuration File platformio.ini
platformio ci --verbose Print detailed information about build process
platformio init --project-option Pass custom option from Project Configuration File platformio.ini
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 PlatformIO Plus Unit Testing
platformio update --only-check Do not update, only check for new version

Project Configuration File platformio.ini

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

Project Configuration File platformio.ini

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