Build options¶

Scopes (SCons Variables)¶

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 pio run --target command to see ALL variable values for a build environment.

Stringification¶

Sometimes you may want to convert a macro argument into a valid C string constant. In this case, you need to wrap a value with double quotes (") and escape double quotes (" -> \\") in the constant value.

Here is an example of a macro definition that uses stringification and build_flags. Please note that we enclosed the flag in the single quotes to prevent the shell from removing double quotes:

platformio.ini

[env:myenv]
build_flags =
    '-DMYSTRING="Text is \\"Quoted\\""'

src/main.cpp

#include <stdio.h>

int main(void) {
    printf("MYSTRING=<%s>\n", MYSTRING);
    return(0);
}

If you use Advanced Scripting, we recommend benefiting from the env.StringifyMacro(value) helper function. In this case, you don’t need to apply any escaping, PlatformIO will do this for you:

platformio.ini

[env:myenv]
extra_scripts = myscript.py

myscript.py

Import("env")

env.Append(CPPDEFINES=[
    ("MYSTRING", env.StringifyMacro('Text is "Quoted"')),
])

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

Example:

[env:generate_flags_with_external_command]
build_flags = !cmd_or_path_to_script

; Unix only, get output from internal command
build_flags = !echo '-D COMMIT_HASH=\\"'$(git log -1 --format=%%h)'\\"'

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()
    .decode("utf-8")
)
print("'-DGIT_REV=\"%s\"'" % revision)

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