Skip to content

Latest commit

 

History

History
256 lines (194 loc) · 7.58 KB

build_flags.rst

File metadata and controls

256 lines (194 loc) · 7.58 KB
Raw

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. Despite the name, CPPDEFINES (C PreProcesor) rows also apply to the C compiler.

For more detailed information about available compiler flags/options, please visit GCC Command Options official documentation.

This option can also be set by the global environment variable :envvar:`PLATFORMIO_BUILD_FLAGS`.

Contents

Scopes (SCons Variables)

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.

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
  -I"relative/path with space"
  -I"C:\windows\dir"
  -I"${platformio.packages_dir}/framework-foo/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 :ref:`projectconf_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 :ref:`projectconf`
  • $PIOPLATFORM, name of development platform
  • $PIOFRAMEWORK, a list of frameworks
  • $PROJECT_DIR, project directory
  • $PROJECT_CORE_DIR, PlatformIO Core directory, see :ref:`projectconf_pio_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 :option:`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 :ref:`projectconf_build_flags`. Please note that we enclosed the flag in the single quotes to prevent the shell evaluation:

platformio.ini

[env:myenv]
build_flags =
    '-D MYSTRING="Text is \\"Quoted\\""'
    '-D MYFONT=&roboto14'

src/main.cpp

#include <stdio.h>

#define CONFIG_LV_FONT_DEFAULT MYFONT

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

If you use :ref:`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 :ref:`cmd_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 :ref:`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 '-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)