Advanced options

New in version 3.4.1.

extra_scripts

Warning

This option is recommended for Advanced Users and requires Python language knowledge.

We highly recommend to take a look at Dynamic build flags option where you can use any programming language. Also, this option is useful if you need to apply changes to the project before building/uploading process:

  • 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

More details Dynamic build flags.

Allows to launch extra scripts (based on SCons software construction tool) while processing environment. For more details please follow to “Construction Environments” section of SCons documentation.

Warning

You can not run/debug these scripts directly with Python interpreter. They will be loaded automatically when processing project environment using platformio run command.

There 2 type of extra scripts:

  1. PRE - executes before a main script of Development Platforms
  2. POST - executes after a main script of Development Platforms

Multiple extra scripts are allowed. Please split them via ”, ” (comma + space) in the same line or use multi-line values.

For example,

[env:my_env_1]
platform = ...
; without prefix, POST script
extra_scripts = post_extra_script.py

[env:my_env_2]
platform = ...
extra_scripts = pre:pre_extra_script1.py, pre:pre_extra_script2.py

[env:my_env_3]
platform = ...
extra_scripts =
  pre:pre_extra_script.py
  post:post_extra_script1.py
  post_extra_script2.py

This option can be set by global environment variable PLATFORMIO_EXTRA_SCRIPTS.

Take a look at the multiple snippets/answers for the user questions:

Extra Linker Flags without -Wl, prefix

Sometimes you need to pass extra flags to GCC linker without Wl,. You could use build_flags option but it will not work. PlatformIO will not parse these flags to LINKFLAGS scope. In this case, simple extra script will help:

platformio.ini:

[env:env_extra_link_flags]
platform = windows_x86
extra_scripts = extra_script.py

extra_script.py (place it near platformio.ini):

Import('env')

env.Append(
  LINKFLAGS=[
      "-static",
      "-static-libgcc",
      "-static-libstdc++"
  ]
)

Custom Uploader

Example, specify own upload command for Atmel AVR:

platformio.ini:

[env:env_custom_uploader]
platform = atmelavr
extra_scripts = /path/to/extra_script.py
custom_option = hello

extra_script.py:

Import('env')
from base64 import b64decode

env.Replace(UPLOADHEXCMD='"$UPLOADER" ' + b64decode(ARGUMENTS.get("CUSTOM_OPTION")) + ' --uploader --flags')

# uncomment line below to see environment variables
# print env.Dump()
# print ARGUMENTS

Before/Pre and After/Post actions

PlatformIO Build System has rich API that allows to attach different pre-/post actions (hooks) using env.AddPreAction(target, callback) or env.AddPreAction(target, [callback1, callback2, ...]) function. A first argument target can be a name of target that is passed using platformio run --target command, a name of built-in targets (buildprog, size, upload, program, buildfs, uploadfs, uploadfsota) or path to file which PlatformIO processes (ELF, HEX, BIN, OBJ, etc.).

The example below demonstrates how to call different functions when platformio run --target is called with upload value. extra_script.py file is located on the same level as platformio.ini.

platformio.ini:

[env:pre_and_post_hooks]
extra_scripts = extra_script.py

extra_script.py:

Import("env")

#
# Upload actions
#

def before_upload(source, target, env):
    print "before_upload"
    # do some actions


def after_upload(source, target, env):
    print "after_upload"
    # do some actions

print "Current build targets", map(str, BUILD_TARGETS)

env.AddPreAction("upload", before_upload)
env.AddPostAction("upload", after_upload)

#
# Custom actions when building program/firmware
#

env.AddPreAction("buildprog", callback...)
env.AddPostAction("buildprog", callback...)

#
# Custom actions for specific files/objects
#

env.AddPreAction("$BUILD_DIR/firmware.elf", [callback1, callback2,...])
env.AddPostAction("$BUILD_DIR/firmware.hex", callback...)

# custom action before building SPIFFS image. For example, compress HTML, etc.
env.AddPreAction("$BUILD_DIR/spiffs.bin", callback...)

# custom action for project's main.cpp
env.AddPostAction("$BUILD_DIR/src/main.cpp.o", callback...)