Section [platformio]¶

description¶

Type: String | Multiple: No

Describe a project with a short information. PlatformIO uses it for PlatformIO Home in the multiple places.

default_envs¶

Type: String | Multiple: Yes

platformio run command processes all environments [env:***] by default if platformio run --environment option is not specified. default_envs allows one to define environments which should be processed by default.

Also, PIO Unified Debugger checks this option when looking for debug environment.

This option can also be configured by the global environment variable PLATFORMIO_DEFAULT_ENVS.

Example:

[platformio]
default_envs = uno, nodemcu

[env:uno]
platform = atmelavr
framework = arduino
board = uno

[env:nodemcu]
platform = espressif8266
framework = arduino
board = nodemcu

[env:teensy31]
platform = teensy
framework = arduino
board = teensy31

[env:lpmsp430g2553]
platform = timsp430
framework = arduino
board = lpmsp430g2553
build_flags = -D LED_BUILTIN=RED_LED

extra_configs¶

Type: String (Pattern) | Multiple: Yes

This option allows extending a base “platformio.ini” (Project Configuration File) with extra configuration files. The format and rules are the same as for the “platformio.ini” (Project Configuration File). A name of the configuration file can be any.

extra_configs can be a single path to an extra configuration file or a list of them. Please note that you can use Unix shell-style wildcards:

Example

Base “platformio.ini”

[platformio]
extra_configs =
  extra_envs.ini
  extra_debug.ini

; Global data for all [env:***]
[env]
platform = espressif32
framework = espidf

; Custom data group
; can be use in [env:***] via ${common.***}
[common]
debug_flags = -D RELEASE
lib_flags = -lc -lm

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

“extra_envs.ini”

[env:esp32dev]
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

core_dir¶

Type: DirPath | Multiple: No

Is used to store development platform packages (toolchains, frameworks, SDKs, upload and debug tools), global libraries for Library Dependency Finder (LDF), and other PlatformIO Core service data. The size of this folder will depend on number of installed development platforms.

A default value is User’s home directory:

• Unix ~/.platformio

• Windows %HOMEPATH%\.platformio

This option can also be configured by the global environment variable PLATFORMIO_CORE_DIR.

Example:

[platformio]
core_dir = /path/to/custom/pio-core/storage

globallib_dir¶

Type: DirPath | Multiple: No | Default: “core_dir/lib”

Global library storage for PlatfrmIO projects and Library Manager where Library Dependency Finder (LDF) looks for dependencies.

This option can also be configured by the global environment variable PLATFORMIO_GLOBALLIB_DIR.

platforms_dir¶

Type: DirPath | Multiple: No | Default: “core_dir/platforms”

Global storage where PlatformIO Package Manager installs Development Platforms.

This option can also be configured by the global environment variable PLATFORMIO_PLATFORMS_DIR.

packages_dir¶

Type: DirPath | Multiple: No | Default: “core_dir/packages”

Global storage where PlatformIO Package Manager installs Development Platforms dependencies (toolchains, Frameworks, SDKs, upload and debug tools).

This option can also be configured by the global environment variable PLATFORMIO_PACKAGES_DIR.

cache_dir¶

Type: DirPath | Multiple: No | Default: “core_dir/cache”

PlatformIO Core (CLI) uses this folder to store caching information (requests to PlatformIO Registry, downloaded packages and other service information).

To reset a cache, please run platformio update command.

This option can also be configured by the global environment variable PLATFORMIO_CACHE_DIR.

build_cache_dir¶

Type: DirPath | Multiple: No | Default: None (Disabled)

PlatformIO Core (CLI) uses this folder to store derived files from a build system (objects, firmwares, ELFs). These files are shared between all build environments. To speed up a build process, you can use the same cache folder between different projects if they depend on the same development platform and framework.

This option can also be configured by the global environment variable PLATFORMIO_BUILD_CACHE_DIR.

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 =

; Examples:
; (Unix) build_cache_dir = /path/to/cache/folder
; (Windows) build_cache_dir = C:/path/to/cache/folder

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

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

workspace_dir¶

Type: DirPath | Multiple: No | Default: “Project/.pio”

A path to a project workspace directory where PlatformIO keeps by default compiled objects, static libraries, firmwares, and external library dependencies. It is used by the next options:

• build_dir

• libdeps_dir.

A default value is .pio and means that folder is located in the root of project.

This option can also be configured by the global environment variable PLATFORMIO_WORKSPACE_DIR.

build_dir¶

Type: DirPath | Multiple: No | Default: “workspace_dir/build”

PlatformIO Build System uses this folder for project environments to store compiled object files, static libraries, firmwares and other cached information. It allows PlatformIO to build source code extremely fast!

You can delete this folder without any risk! If you modify “platformio.ini” (Project Configuration File), then PlatformIO will remove this folder automatically. It will be created on the next build operation.

This option can also be configured by the global environment variable PLATFORMIO_BUILD_DIR.

libdeps_dir¶

Type: DirPath | Multiple: No | Default: “workspace_dir/libdeps”

Internal storage where Library Manager will install project dependencies (lib_deps).

This option can also be configured by the global environment variable PLATFORMIO_LIBDEPS_DIR.

include_dir¶

Type: DirPath | Multiple: No | Default: “Project/include”

A path to project’s default header files. PlatformIO uses it for platformio run command. A default value is include that means that folder is located in the root of project. This path will be added to CPPPATH of build environment.

If you need to add extra include directories to CPPPATH scope, please use build_flags with -I /path/to/extra/dir option.

This option can also be configured by the global environment variable PLATFORMIO_INCLUDE_DIR.

src_dir¶

Type: DirPath | Multiple: No | Default: “Project/src”

A path to project’s source directory. PlatformIO uses it for platformio run command. A default value is src that means that folder is located in the root of project.

This option can also be configured by the global environment variable PLATFORMIO_SRC_DIR.

lib_dir¶

Type: DirPath | Multiple: No | Default: “Project/lib”

You can put here your own/private libraries. The source code of each library should be placed in separate directory, like lib/private_lib/[here are source files]. This directory has the highest priority for Library Dependency Finder (LDF).

A default value is lib that means that folder is located in the root of project.

This option can also be configured by the global environment variable PLATFORMIO_LIB_DIR.

For example, see how can be organized Foo and Bar libraries:

|--lib
|  |--Bar
|  |  |--docs
|  |  |--examples
|  |  |--src
|  |     |- Bar.c
|  |     |- Bar.h
|  |--Foo
|  |  |- Foo.c
|  |  |- Foo.h
|- platformio.ini
|--src
   |- main.c

Then in src/main.c you should use:

#include <Foo.h>
#include <Bar.h>

// rest H/C/CPP code

PlatformIO will find your libraries automatically, configure preprocessor’s include paths and build them.

data_dir¶

Type: DirPath | Multiple: No | Default: “Project/data”

Data directory to store contents and Uploading files to file system SPIFFS. A default value is data that means that folder is located in the root of project.

This option can also be configured by the global environment variable PLATFORMIO_DATA_DIR.

test_dir¶

Type: DirPath | Multiple: No | Default: “Project/test”

Directory where PIO Unit Testing engine will look for the tests. A default value is test that means that folder is located in the root of project.

This option can also be configured by the global environment variable PLATFORMIO_TEST_DIR.

boards_dir¶

Type: DirPath | Multiple: No | Default: “Project/boards”

Custom board settings per project. You can change this path with your own. A default value is boards that means that folder is located in the root of project.

By default, PlatformIO looks for boards in this order:

1. Project boards_dir

2. Global core_dir/boards

3. Development platform core_dir/platforms/*/boards.

This option can also be configured by the global environment variable PLATFORMIO_BOARDS_DIR.

shared_dir¶

Type: DirPath | Multiple: No | Default: “Project/shared”

PIO Remote uses this folder to synchronize extra files between remote machine. For example, you can share extra_scripts.

Please note that these folders are automatically shared between remote machine with platformio remote run --force-remote or platformio remote test --force-remote commands:

• lib_dir

• include_dir

• src_dir

• boards_dir

• data_dir

• test_dir

A default value is shared that means that folder is located in the root of project.

This option can also be configured by the global environment variable PLATFORMIO_SHARED_DIR.