Interpolation of Values¶

On top of the core functionality, PlatformIO supports interpolation. It enables values to contain format strings which refer to other values from foreign sections.

Interpolation has the next syntax – ${<section>.<option>}, where <section> is a value from [<section>] group, and <option> is a first item from pair <option> = value.

Syntax	Meaning
`${sysenv.<name>}`	Embed system environment variable by a name. For example, `${sysenv.HOME}` refers to user home directory on Unix machine
`${platformio.<option>}`	Embed value from Section [platformio]. For example, `${platformio.packages_dir}` refers to a path of packages_dir
`${env.<option>}`	Embed default value from Section [env]. For example, `${env.debug_build_flags}` refers to the default debugging flags.
`${<section>.<option>}`	Embed value from another section. For example, `${extra.lib_deps}` embeds library dependencies declared in the section named `extra`.

Interpolation can span multiple levels
Interpolation can be applied only for the option’s value
Multiple interpolations are allowed
The Section [platformio] and Section [env] sections are reserved and could not be used as a custom section. Some good section names might be extra or custom.

Note

If you need to share common configuration options between build environments, please take a look at “Global scope” in Section [env] or extends option which allows extending of other sections.

Example:

; COMMON options
; Each "[env:***]" extends this "[env]" by default
[env]
framework = arduino
build_flags = -D VERSION=1.2.3

; CUSTOM options
; You need manually inject these options into a section
; using ${extra.<name_of_option>} (see below)
[extra]
lib_deps_builtin =
  SPI
  Wire
lib_deps_external =
  bblanchon/ArduinoJson@>5.6.0

[env:uno]
platform = atmelavr
board = uno
lib_deps =
  ${extra.lib_deps_builtin}
  ${extra.lib_deps_external}

[env:nodemcuv2]
platform = espressif8266
board = nodemcuv2
build_flags = ${env.build_flags} -Wall
lib_deps =
  ${extra.lib_deps_builtin}
  ${extra.lib_deps_external}
  knolleary/PubSubClient @ ~2.6
  paulstoffregen/OneWire @ ^2.3.5

; Keep sensitive data in environment variables
;
; Unix
; export WIFI_SSID='\"my\ ssid\ name\"'
; export WIFI_PASS='\"my\ password\"'
;
; Windows
; set WIFI_SSID='"my ssid name"'
; set WIFI_PASS='"my password"'

[env:esp32dev]
extends = env:nodemcuv2
platform = espressif32
board = esp32dev
build_flags =
  ${env.build_flags}
  -DWIFI_SSID=${sysenv.WIFI_SSID}
  -DWIFI_PASS=${sysenv.WIFI_PASS}

Warning

Be careful with special characters in system environment variables on Unix systems, especially when they are used as the value for preprocessor directives. Symbols like $, &, ~, etc must be explicitly escaped, for example:

export WIFI_PASS='\"my\~p\&a\\\$\$\$\$word\"'