Migrating from 3.x to 4.0¶

Global scope [env]¶

One of the most requested features was a “global” or “common” project environment (Section [env]) where developers can share common configuration between all declared build environments [env:NAME].

The previous solution in PlatformIO Core 3.0 was using Dynamic variables. As practice has shown, this approach was not good and more advanced “platformio.ini” (Project Configuration File) looked so complicated and hard for managing (for example, open source projects MarlinFirmware, Espurna).

PlatformIO Core 4.0 introduces a new global scope named [env] which allows declaring global options that will be shared between all [env:NAME] sections in “platformio.ini” (Project Configuration File). For example,

[env]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
lib_deps = Dep1, Dep2

[env:release]
build_flags = -D RELEASE
lib_deps =
    ${env.lib_deps}
    Dep3

[env:debug]
build_type = debug
build_flags = -D DEBUG
lib_deps = DepCustom

In this example we have 2 build environments release and debug. This is the same if you duplicate all options (PlatformIO Core 3.0 compatible):

[env:release]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
build_flags = -D RELEASE
lib_deps = Dep1, Dep2, Dep3

[env:debug]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
build_type = debug
build_flags = -D DEBUG
lib_deps = DepCustom

External Configuration Files¶

To simplify the project configuration process, PlatformIO Core 4.0 adds support for external “platformio.ini” (Project Configuration File). Yes! You can finally extend one configuration file with another or with a list of them. The cool feature is a support for Unix shell-style wildcards. So, you can dynamically generate “platformio.ini” (Project Configuration File) files or load bunch of them from a folder. See extra_configs option for details and a simple example below:

Base “platformio.ini”

[platformio]
extra_configs =
  extra_envs.ini
  extra_debug.ini

[common]
debug_flags = -D RELEASE
lib_flags = -lc -lm

[env:esp-wrover-kit]
platform = espressif32
framework = espidf
board = esp-wrover-kit
build_flags = ${common.debug_flags}

“extra_envs.ini”

[env:esp32dev]
platform = espressif32
framework = espidf
board = esp32dev
build_flags = ${common.lib_flags} ${common.debug_flags}

[env:lolin32]
platform = espressif32
framework = espidf
board = lolin32
build_flags = ${common.debug_flags}

“extra_debug.ini”

# Override base "common.debug_flags"
[common]
debug_flags = -D DEBUG=1

[env:lolin32]
build_flags = -Og

After a parsing process, configuration state will be the next:

[common]
debug_flags = -D DEBUG=1
lib_flags = -lc -lm

[env:esp-wrover-kit]
platform = espressif32
framework = espidf
board = esp-wrover-kit
build_flags = ${common.debug_flags}

[env:esp32dev]
platform = espressif32
framework = espidf
board = esp32dev
build_flags = ${common.lib_flags} ${common.debug_flags}

[env:lolin32]
platform = espressif32
framework = espidf
board = lolin32
build_flags = -Og

New Options¶

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

Package Dependencies¶

PlatformIO has decentralized architecture and allows platform maintainers to create Custom Development Platforms for PlatformIO ecosystem. Each development platform depends on a list of packages (toolchains, SDKs, debugging servers, etc). PlatformIO Package Manager installs these packages automatically and PlatformIO Build System uses them later.

Starting from PlatformIO Core 4.0, developers can see which versions of a development platform or its dependent packages will be used. This is a great addition to track changes (Frameworks, SDKs) between Development Platforms updates. See an example with “staging” (Git) version of Espressif 8266 development platform:

Processing nodemcuv2 (platform: https://github.com/platformio/platform-espressif8266.git#feature/stage; board: nodemcuv2; framework: arduino)
-------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/espressif8266/nodemcuv2.html
PLATFORM: Espressif 8266 (Stage) 2.3.0-alpha.1 #990141d > NodeMCU 1.0 (ESP-12E Module)
HARDWARE: ESP8266 80MHz, 80KB RAM, 4MB Flash
PACKAGES: toolchain-xtensa 2.40802.190218 (4.8.2), tool-esptool 1.413.0 (4.13), tool-esptoolpy 1.20600.0 (2.6.0), framework-arduinoespressif8266 78a1a66
LDF: Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain+, Compatibility ~ soft
Found 35 compatible libraries
Scanning dependencies...

Custom Platform Packages¶

Sometimes you need to override default Development Platforms packages or add an extra. PlatformIO Core 4.0 introduces a new configuration option platform_packages per a build environment. Also, using this option you can install external packages and use them later as programmers or upload tools. See a few examples:

[env:override_default_toolchain]
platform = atmelavr
platform_packages =
  ; use GCC AVR 5.0+
  toolchain-gccarmnoneeabi@>1.50000.0

[env:override_framework]
platform = espressif8266
platform_packages =
  ; use upstream Git version
  framework-arduinoespressif8266 @ https://github.com/esp8266/Arduino.git

[env:external_package]
platform = ststm32
platform_packages =
  ; latest openOCD from PlatformIO Package Registry
  tool-openocd

  ; source code of ST-Link
  tool-stlink-source @ https://github.com/texane/stlink.git

Custom Upload Command¶

PlatformIO’s Development Platforms have pre-configured settings to program boards or devices. They depend on a type of bootloader or programming interface. PlatformIO Core 4.0 allows you to override default upload command using upload_command option in “platformio.ini” (Project Configuration File):

[env:custom_upload_cmd]
platform = ...
framework = ...
board = ...
upload_command = /my/flasher arg1 arg2 --flag1 $SOURCE

See real examples for upload_command.

Shared Cache Directory¶

PlatformIO Core 4.0 allows you to configure a shared folder for the derived files (objects, firmwares, ELFs) from a build system using build_cache_dir. You can use it in multi-environments project configuration to avoid multiple compilations of the same source code files.

The example of “platformio.ini” (Project Configuration File) below instructs PlatformIO Build System to check build_cache_dir for already compiled objects for STM32Cube and project source files. The cached object will not be used if the original source file was modified or build environment has a different configuration (new build flags, etc):

[platformio]
; set a path to a cache folder
build_cache_dir = /tmp/platformio-shared-cache

[env:bluepill_f103c6]
platform = ststm32
framework = stm32cube
board = bluepill_f103c6

[env:nucleo_f411re]
platform = ststm32
framework = stm32cube
board = nucleo_f411re

You can also use the same build_cache_dir between different projects if they use the same Development Platforms and Frameworks.