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 affect the preprocessing, compilation, assembly and linking processes for C and C++ code. All compiler and linker flags can be used. Here is a list of some common options.

In spite of the name, CPPDEFINES rows also applies to the C compiler.

Format	Affects build variable	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	Turn on all optional warnings which are desirable for normal code.
-Werror	CCFLAGS	Make all warnings into hard errors. With this option, if any source code triggers warnings, the compilation will be aborted.
-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:

• Options to Request or Suppress Warnings

• Options for Debugging Your Program

• Options That Control Optimization

• Options Controlling the Preprocessor

• Passing Options to the Assembler

• Options for Linking

• Options for Directory Search

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: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

Note

If you need to control build flags that are specific for debug configuration please refer to debug_build_flags.

Built-in Variables

You can inject the built-in variables into your build flags, 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, a list of frameworks

• $PROJECT_DIR, project directory

• $PROJECT_CORE_DIR, PlatformIO Core directory, see core_dir

• $PROJECT_BUILD_DIR, project build directory per all environments

• $BUILD_DIR, build directory per current environment

See the full list of PlatformIO variables.

Please use target envdump for the platformio run --target command to see ALL variable values for a build environment.

Dynamic build flags

PlatformIO allows users to run an external command/script which outputs build flags into STDOUT by prepending the shell command with a ! character. PlatformIO will automatically replace commands with their output when appending flags to build environments.

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 a 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 a “PIO_SRC_REV” macro with the latest Git revision

This example includes a separate file named git_rev_macro.py, to be placed in the same directory as 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 as build_flags but will be applied only for project source files in the src_dir directory.

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

build_unflags

Type: String | Multiple: Yes

Selectively remove base/initial flags that were set by the 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 or excluded from src_dir for a build process. Filter supports two templates:

• +<PATH> include template

• -<PATH> exclude template

PATH is relative to src_dir. All patterns will be applied in their order of definition. GLOB Patterns are allowed.

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

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

targets

Type: String | Multiple: Yes

A list of targets which will be processed by the platformio run command by default. You can enter more than one target, if separated by comma+space “, “.

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

Examples

1. Build a project using Release Configuration, upload the firmware, and start Serial Monitor automatically:

   [env:upload_and_monitor]
   targets = upload, monitor
   

2. 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.