Build options¶

`build_type`¶

New in version 4.0.

Type: String | Multiple: No | Default: release

See extended documentation for Build Configurations.

`build_flags`¶

Type: String | Multiple: Yes

These flags/options control preprocessing, compilation, assembly and linking processes:

Format	Scope	Description
`-D name`	CPPDEFINES	Predefine name as a macro, with definition 1.
`-D name=definition`	CPPDEFINES	The contents of definition are tokenized and processed as if they appeared during translation phase three in a `#define` directive.
`-U name`	CPPDEFINES	Cancel any previous definition of name, either built in or provided with a `-D` option.
`-Wp,option`	CPPFLAGS	Bypass the compiler driver and pass option directly through to the preprocessor
`-Wall`	CCFLAGS	Turns on all optional warnings which are desirable for normal code.
`-Werror`	CCFLAGS	Make all warnings into hard errors. Source code which triggers warnings will be rejected.
`-w`	CCFLAGS	Suppress all warnings, including those which GNU CPP issues by default.
`-include file`	CCFLAGS	Process file as if `#include "file"` appeared as the first line of the primary source file.
`-Idir`	CPPPATH	Add the directory dir to the list of directories to be searched for header files.
`-Wa,option`	ASFLAGS, CCFLAGS	Pass option as an option to the assembler. If option contains commas, it is split into multiple options at the commas.
`-Wl,option`	LINKFLAGS	Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas.
`-llibrary`	LIBS	Search the library named library when linking
`-Ldir`	LIBPATH	Add directory dir to the list of directories to be searched for `-l`.

This option can also be set by global environment variable PLATFORMIO_BUILD_FLAGS.

For more detailed information about available flags/options go to:

Examples:

[env:specific_defines]
build_flags =
  -DFOO -DBAR=1
  -D BUILD_ENV_NAME=$PIOENV
  -D CURRENT_TIME=$UNIX_TIME
  -DFLOAT_VALUE=1.23457e+07

[env:string_defines]
build_flags =
  -DHELLO="World!"
  '-DWIFI_PASS="My password"'
  ; Password with special chars: My pass'word
  -DWIFI_PASS=\"My\ pass\'word\"

[env:specific_inclibs]
build_flags =
  -I/opt/include
  -L/opt/lib
  -lfoo

[env:specific_ld_script]
build_flags = -Wl,-T/path/to/ld_script.ld

[env:ignore_incremental_builds]
; We dynamically change the value of "LAST_BUILD_TIME" macro,
; PlatformIO will not cache objects
build_flags = -DLAST_BUILD_TIME=$UNIX_TIME

Built-in Variables ¶

You can inject into build flags built-in variables, such as:

$PYTHONEXE, full path to current Python interpreter
$UNIX_TIME, current time in Unix format
$PIOENV, name of build environment from “platformio.ini” (Project Configuration File)
$PIOPLATFORM, name of development platform
$PIOFRAMEWORK, name of framework
$PROJECT_DIR, project directory
$PROJECTCORE_DIR, PlatformIO Core directory, see core_dir
$PROJECTBUILD_DIR, project build directory per all environments
$BUILD_DIR, build directory per current environment
Need more PlatformIO variables?

Please use target envdump for platformio run --target command to see ALL variables from a build environment.

Dynamic build flags ¶

PlatformIO allows one to run external command/script which outputs build flags into STDOUT. PlatformIO will automatically parse this output and append flags to a build environment.

You can use any shell or programming language.

This external command will be called on each platformio run command before building/uploading process.

Use Cases:

Macro with the latest VCS revision/tag “on-the-fly”

Generate dynamic headers (*.h)

Process media content before generating SPIFFS image

Make some changes to source code or related libraries

Note

If you need more advanced control and would like to apply changes to PlatformIO Build System environment, please refer to Advanced Scripting.

Example:

[env:generate_flags_with_external_command]
build_flags = !cmd_or_path_to_script

; Unix only, get output from internal command
build_flags = !echo "-DSOME_MACRO="$(some_cmd arg1 --option1)

Use Case: Create “PIO_SRC_REV” macro with the latest Git revision

You will need to create a separate file named git_rev_macro.py and place it near platformio.ini.

platformio.ini:

[env:git_revision_macro]
build_flags = !python git_rev_macro.py

git_rev_macro.py:

import subprocess

revision = subprocess.check_output(["git", "rev-parse", "HEAD"]).strip()
print("-DPIO_SRC_REV=%s" % revision)

`src_build_flags`¶

Type: String | Multiple: Yes

An option src_build_flags has the same behavior like build_flags but will be applied only for the project source code from src_dir directory.

This option can also be set by global environment variable PLATFORMIO_SRC_BUILD_FLAGS.

`build_unflags`¶

Type: String | Multiple: Yes

Remove base/initial flags which were set by development platform.

[env:unflags]
build_unflags = -Os -std=gnu++11
build_flags = -O2

`src_filter`¶

Type: String (Templates) | Multiple: Yes

This option allows one to specify which source files should be included/excluded from src_dir for a build process. Filter supports 2 templates:

+<PATH> include template
-<PATH> exclude template

PATH MUST BE related from src_dir. All patterns will be applied in theirs order. GLOB Patterns are allowed.

By default, src_filter is predefined to +<*> -<.git/> -<.svn/> -<example/> -<examples/> -<test/> -<tests/>, that means “includes ALL files, then exclude .git and svn repository folders, example … folder.

This option can also be set by global environment variable PLATFORMIO_SRC_FILTER.

`targets`¶

Type: String | Multiple: Yes

A list of targets which will be processed by platformio run command by default. You can enter more than one target, please split them with comma+space “, “.

The list with available targets is located in platformio run --target.

Examples

Build a project using Release Configuration, upload firmware, and start Serial Monitor automatically:
[env:upload_and_monitor] targets = upload, monitor
Build a project using Debug Configuration.

Tip! You can use these targets like an option to platformio run --target command. For example:

# clean project
platformio run -t clean

# dump current build environment
platformio run --target envdump

When no targets are defined, PlatformIO will build only sources by default.