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.
Contents
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 | :ref:`platformio platform <userguide_platform>` |
| platformio serialports | :ref:`cmd_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.
We have introduced :ref:`platform_creating_manifest_file` 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 :ref:`platform_creating` guide for details.
- :ref:`platform_creating_manifest_file`
espressifdevelopment platform has been renamed to :ref:`platform_espressif8266`- PlatformIO 3.0 :ref:`userguide_platform`
- Custom package repositories
- External embedded board configuration files, isolated build scripts
- Embedded Board compatibility with more than one development platform
- Powerful and super-fast :ref:`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 :ref:`library_config` to specify sources other than PlatformIO's Repository
- Check library compatibility with project environment before building
- Control Library Dependency Finder for compatibility using :ref:`projectconf_lib_compat_mode` option
- Custom library storages/directories with :ref:`projectconf_lib_extra_dirs` option
- Handle extra build flags, source filters and build script from :ref:`library_config`
- 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 :ref:`projectconf_extra_script`
We have added new commands and changed some existing ones. Here are the new or updated commands and options.
| Command | Description |
|---|---|
| :ref:`cmd_boards` | Returns all supported boards by PlatformIO |
| :option:`platformio boards --installed` | Returns currently installed boards |
| :option:`platformio ci --project-option` | Pass custom option from :ref:`projectconf` |
| :option:`platformio ci --verbose` | Print detailed information about build process |
| :option:`platformio init --project-option` | Pass custom option from :ref:`projectconf` |
| :option:`platformio lib --global` | Manage PlatformIO :ref:`Global Library Storage <ldf_storage>` |
| :option:`platformio lib --storage-dir` | Manage :ref:`Custom Library Storage <ldf_storage>` |
| :ref:`cmd_lib_install` | New PlatformIO 3.0 Library Manager! Semantic Versioning, VCS support and external URL support |
| :option:`platformio lib install --silent` | Suppress progress reporting when install library |
| :option:`platformio lib install --interactive` | Allow to make a choice for all prompts when install library |
| :option:`platformio lib search --header` | Search library by specific header file name (include) |
| :option:`platformio lib update --only-check` | Do not update, only check for new version |
| :ref:`platformio platform <userguide_platform>` | New PlatformIO 3.0 Platform Manager! Semantic Versioning, VCS support and external URL support. |
| :option:`platformio platform update --only-packages` | Update only platform packages |
| :option:`platformio platform update --only-check` | Do not update, only check for new version |
| :ref:`cmd_run` | By default, prints only human-readable information when processing environments |
| :option:`platformio run --verbose` | Print detailed processing information |
| :ref:`platformio settings set force_verbose true <setting_force_verbose>` | Force verbose output when processing environments (globally) |
| :ref:`cmd_test` | PlatformIO Plus Unit Testing |
| :option:`platformio update --only-check` | 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 | :ref:`projectconf_pio_libdeps_dir` | Internal storage where :ref:`librarymanager` will install project dependencies |
| platformio | :ref:`projectconf_pio_test_dir` | Directory where :ref:`unit_testing` engine will look for the tests |
| env | :ref:`projectconf_lib_deps` | Specify project dependencies that should be installed automatically to :ref:`projectconf_pio_libdeps_dir` before environment processing. |
| env | :ref:`projectconf_env_platform` | PlatformIO 3.0 allows to use specific version of platform using Semantic Versioning (X.Y.Z=MAJOR.MINOR.PATCH). |
| env | :ref:`projectconf_lib_extra_dirs` | A list with extra directories/storages where :ref:`ldf` will look for dependencies |
| env | :ref:`projectconf_lib_ldf_mode` | This option specifies how does :ref:`ldf` should analyze dependencies (#include directives) |
| env | :ref:`projectconf_lib_compat_mode` | Library compatibility mode allows to control strictness of :ref:`ldf` |
| env | :ref:`projectconf_test_ignore` | 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 :option:`platformio init --project-option` instead of it with targets = upload value |
The following options have been dropped or changed in v3.0.
| Section | Option | Description |
|---|---|---|
| platformio | :ref:`projectconf_pio_lib_dir` | Changed: Project's own/private libraries, where in PlatformIO 2.x it was global library storage |