platformio configuration file

platformio.ini (configuration file)

Each PlatformIO project has a configuration file named platformio.ini in the root directory for the project.
platformio.ini has sections (each denoted by a [header]) and key / value pairs within the sections. Lines beginning with ; are ignored and may be used to provide comments.
Multiple value options can be specified in two ways:

Split values with “, ” (comma + space)
Multi-line format, where each new line starts with at least two spaces

there are two main sections
1- PlatformIO Core (CLI) settings: Section [platformio]
2- Environment settings: Section [env]

[platformio]

description : Short description of the project

default_envs : The platformio run command processes all environments [env:***] by default if the platformio run --environment option is not specified.

extra_configs : This option allows extending a base “platformio.ini” (Project Configuration File) with extra configuration files.

Base “platformio.ini”

[platformio]
description = this is new project 
default_envs = esp32dev
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}

src_dir: The path to the project’s directory with source code. Default: “Project/src”
lib_dir : You can put your own/private libraries here. The source code of each library should be placed in a separate directory Default: “Project/data”

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>

[env]

Common [env]
Environment [env:NAME]
NAME are letters a-z, numbers 0-9, special char _ (underscore)
Options

Each project may have multiple configuration environments defining the available project tasks for building, programming, debugging, unit testing, device monitoring, library dependencies, etc.

Common [env] : An optional configuration environment with common options that will be shared between all [env:NAME] environments in the platform.ini file.
example:

[env]
platform = ststm32
framework = stm32cube
board = nucleo_l152re
lib_deps = Dep1, Dep2

[env:release]
build_flags = -D RELEASE
lib_deps =
    ${env.lib_deps}
    Dep3

[env:debug]
build_type = debug
build_flags = -D DEBUG
lib_deps = DepCustom

Environment [env:NAME] : A section with an env: prefix defines a working environment for platformio run, platformio test, platformio check, platformio debug and other commands. Multiple [env:NAME] environments with different NAME are allowed. Every project must define at least one working environment.
Each environment must have a unique NAME. The valid chars for NAME are letters a-z, numbers 0-9, special char _ (underscore). For example, [env:hello_world].

you can use options inside [env] the next link for all available options
https://docs.platformio.org/en/latest/projectconf/section_env.html#options

Dynamic variables

Dynamic variables (interpolations) are useful when you have a custom configuration data between build environments. For examples, extra build_flags or project dependencies lib_deps.

Each variable should have a next format: ${<section>.<option>}, where <section> is a value from [<section>] group, and <option> is a first item from pair <option> = value.

You can inject system environment variable using sysenv as a section. For example, ${sysenv.HOME}.

Variable can be applied only for the option’s value
Multiple variables 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.

[env]
; Unix
lib_extra_dirs = ${sysenv.HOME}/Documents/Arduino/libraries
; Windows
lib_extra_dirs = ${sysenv.HOMEDRIVE}${sysenv.HOMEPATH}\Documents\Arduino\libraries

; You MUST inject these options into [env:] section
; using ${extra.***} (see below)
[extra]
build_flags = -D VERSION=1.2.3 -D DEBUG=1
lib_deps_builtin =
  SPI
  Wire
lib_deps_external = ArduinoJson@>5.6.0

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

[env:nodemcuv2]
platform = espressif8266
framework = arduino
board = nodemcuv2
build_flags = ${extra.build_flags} -Wall
lib_deps =
  ${extra.lib_deps_builtin}
  ${extra.lib_deps_external}
  PubSubClient@2.6
  OneWire

; 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 =
  -DWIFI_SSID=${sysenv.WIFI_SSID}
  -DWIFI_PASS=${sysenv.WIFI_PASS}