[platformio]¶The platformio section in the platformio.ini file is used for overriding the
default configuration options for PlatformIO Core (CLI).
Note
Relative path is allowed for directory option:
~ will be expanded to user’s home directory
../ or ..\ go up to one folder
There is a $PROJECT_HASH template variable. You can use it in a directory
path. It will by replaced by a SHA1[0:10] hash of the full project path.
This is very useful to declare a global storage for project workspaces.
For example, /tmp/pio-workspaces/$PROJECT_HASH (Unix) or
$[sysenv.TEMP}/pio-workspaces/$PROJECT_HASH (Windows).
You can set a global workspace directory using the system environment
variable PLATFORMIO_WORKSPACE_DIR.
See the available directory ***_dir options below.
description¶Type: String | Multiple: No
Short description of the project. PlatformIO uses it for PlatformIO Home in the multiple places.
default_envs¶Type: String | Multiple: Yes
The pio run command processes all environments [env:***] by default
if the pio run --environment option is not specified.
default_envs allows one to define which environments that
should be processed by default.
Also, Debugging 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:
Pattern |
Meaning |
|---|---|
|
matches everything |
|
matches any single character |
|
matches any character in seq |
|
matches any character not in seq |
Note
If you declare the same pair of “group” + “option” in an extra configuration file which was previously declared in a base “platformio.ini” (Project Configuration File), it will be overwritten with a value from extra configuration.
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
The core_dir variable points out the directory used for all 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 the number of installed development platforms.
The default value is the 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 Management 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 pio 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”
The path to a project workspace directory where PlatformIO keeps by default compiled objects, static libraries, firmwares, and external library dependencies. It is used by these options:
The 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¶Warning
PLEASE DO NOT EDIT FILES IN THIS FOLDER. PlatformIO will overwrite your changes on the next build. THIS IS A CACHE DIRECTORY.
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.
Note
If you have any problems with building your project environments which
are defined in “platformio.ini” (Project Configuration File), then TRY TO DELETE this folder. In
this situation you will remove all cached files without any risk. Also,
you can use “clean” target for pio run --target command.
libdeps_dir¶Type: DirPath | Multiple: No | Default: “workspace_dir/libdeps”
Internal storage where Library Management 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”
The path to project’s default header files. PlatformIO uses it for the
pio run command. The default value is include meaning an
include directory located under the root directory of the project. This
path will be added to CPPPATH of the 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”
The path to the project’s directory with source code. PlatformIO uses
it for the pio run command. The default value is src
meaning a src directory located in the root directory of the project.
This option can also be configured by the global environment variable
PLATFORMIO_SRC_DIR.
Note
This option is useful for people who migrate from Arduino IDE where the source directory should have the same name as the main source file. See example project with own source directory.
lib_dir¶Type: DirPath | Multiple: No | Default: “<Project>/lib”
You can put your own/private libraries here. 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).
The default value is lib, meaning a lib directory located in
the root of the project.
This option can also be configured by the global environment variable
PLATFORMIO_LIB_DIR.
For example, see how the Foo and Bar libraries are organized:
|--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 of H/C/CPP code
PlatformIO will find your libraries automatically, configure the preprocessor’s include paths and build them.
data_dir¶Type: DirPath | Multiple: No | Default: “<Project>/data”
Data directory to store contents and Using Filesystem.
The default value is data that means that folder is located in the root of
the project.
This option can also be configured by the global environment variable
PLATFORMIO_DATA_DIR.
test_dir¶Type: DirPath | Multiple: No | Default: “<Project>/test”
The directory where Unit Testing engine will look for the
tests. The default value is test, meaning a test directory
located in the root of the project.
This option can also be configured by the global environment variable
PLATFORMIO_TEST_DIR.
boards_dir¶Type: DirPath | Multiple: No | Default: “<Project>/boards”
The location of project-specific board definitions. Each project may
choose a suitable directory name. The default value is boards,
meaning a “boards” directory located in the root of the project.
By default, PlatformIO looks for boards in this order:
Project boards_dir (as defined by this setting)
Global core_dir/boards
Development platform core_dir/platforms/*/boards.
This option can also be configured by the global environment variable
PLATFORMIO_BOARDS_DIR.
monitor_dir¶Type: DirPath | Multiple: No | Default: “<Project>/monitor”
The directory where pio device monitor will look for the
Custom Filters. The default value is monitor,
meaning a monitor directory located in the root of the project.
This option can also be configured by the global environment variable
PLATFORMIO_MONITOR_DIR.