Section [platformio]

A platformio section is used for overriding default configuration options for PlatformIO Core.

Note

Relative path is allowed for directory option:

  • ~ will be expanded to user’s home directory
  • ../ or ..\ go up to one folder

Options

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.

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

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

New in version 3.2.

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.

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.

Note

This option is useful for people who migrate from Arduino/Energia IDEs where source directory should have the same name like the main source file. See example project with own source directory.

envs_dir

Warning

PLEASE DO NOT EDIT FILES IN THIS FOLDER. PlatformIO will overwrite your changes on the next build. THIS IS A CACHE DIRECTORY.

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 Project Configuration File platformio.ini, 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.

This option can be overridden by global environment variable PLATFORMIO_ENVS_DIR.

Note

If you have any problems with building your Project environments which are defined in Project Configuration File platformio.ini, then TRY TO DELETE this folder. In this situation you will remove all cached files without any risk.

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.