Section [platformio]¶

description¶

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

env_default¶

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

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

Multiple environments are allowed if they are separated with “, ” (comma+space). For example.

[platformio]
env_default = 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 = energia
board = lpmsp430g2553
build_flags = -D LED_BUILTIN=RED_LED

home_dir¶

Is used to store platform toolchains, frameworks, global libraries for Library Dependency Finder (LDF), service data and etc. 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 be overridden by global environment variable PLATFORMIO_HOME_DIR.

Example:

[platformio]
home_dir = /path/to/custom/pio/storage

build_dir¶

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.

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

There is a $PROJECT_HASH template variable. You can use it in a path. It will by replaced by a SHA1[0:10] hash of a full project path. This is very useful to declare a global storage for project artifacts. For example, /tmp/pio-build/$PROJECT_HASH (Unix) or %TEMP%/pio-build/$PROJECT_HASH (Windows). You can set a global build directory using system environment variable PLATFORMIO_BUILD_DIR.

This option can be overridden by global environment variable PLATFORMIO_BUILD_DIR.

include_dir¶

A path to project’s headers 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.

This option can be overridden by global environment variable PLATFORMIO_INCLUDE_DIR.

src_dir¶

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 be overridden by global environment variable PLATFORMIO_SRC_DIR.

lib_dir¶

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 be overridden by 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.

libdeps_dir¶

Internal storage where Library Manager will install project dependencies (lib_deps). A default value is .piolibdeps that means that folder is located in the root of project.

This option can be overridden by global environment variable PLATFORMIO_LIBDEPS_DIR.

lib_extra_dirs¶

A list with extra storages for a project where Library Dependency Finder (LDF) will look for libraries.

This option has the same behavior as lib_extra_dirs option for a specific build environment defined in [env:] section. The main difference is that the option which is defined in [platofrmio] section will be extra applied automatically for all [env:] sections.

For the possible values and examples please follow to lib_extra_dirs.

data_dir¶

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 be overridden by global environment variable PLATFORMIO_DATA_DIR.

test_dir¶

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 be overridden by global environment variable PLATFORMIO_TEST_DIR.

boards_dir¶

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 home_dir/boards

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

This option can be overridden by global environment variable PLATFORMIO_BOARDS_DIR.