Build System: Attach custom Before/Pre and After/Post actions for targets // Resolve #542

HISTORY.rst

@@ -65,6 +65,8 @@ PlatformIO 3.0
   + Support for the 3rd party manifests (Arduino IDE "library.properties"
     and ARM mbed "module.json")
 
+* Build System: Attach custom Before/Pre and After/Post actions for targets
+  (`issue #542 <https://github.com/platformio/platformio/issues/542>`_)
 * Print human-readable information when processing environments without
   ``-v, --verbose`` option
   (`issue #721 <https://github.com/platformio/platformio/issues/721>`_)
@@ -77,7 +79,7 @@ PlatformIO 3.0
 * Development platform `Atmel SAM <https://github.com/platformio/platform-atmelsam>`__
 
   + Fixed missing analog ports for Adafruit Feather M0 Bluefruit
-    (`issue #2 <https://github.com/platformio/platform-atmelsam/issues/2>`_)
+    (`issue #2 <https://github.com/platformio/platform-atmelsam/issues/2>`__)
 
 * Development platform `Nordic nRF51 <https://github.com/platformio/platform-nordicnrf51>`__
 
@@ -87,12 +89,12 @@ PlatformIO 3.0
 * Development platform `ST STM32 <https://github.com/platformio/platform-ststm32>`__
 
   + Added support for BluePill F103C8 board
-    (`pull #2 <https://github.com/platformio/platform-ststm32/pull/2>`_)
+    (`pull #2 <https://github.com/platformio/platform-ststm32/pull/2>`__)
 
 * Development platform `Teensy <https://github.com/platformio/platform-teensy>`__
 
   + Updated Arduino Framework to v1.29
-    (`issue #2 <https://github.com/platformio/platform-teensy/issues/2>`_)
+    (`issue #2 <https://github.com/platformio/platform-teensy/issues/2>`__)
 
 
 PlatformIO 2.0

docs/faq.rst

@@ -68,6 +68,13 @@ PlatformIO IDE
 
 Please refer to :ref:`PlatformIO IDE Frequently Asked Questions <ide_atom_faq>`.
 
+Before/Pre and After/Post build actions
+---------------------------------------
+
+PlatformIO Build System has rich API that allows to attach different pre-/post
+actions (hooks). See features of :ref:`projectconf_extra_script` option for
+:ref:`projectconf`.
+
 .. _faq_troubleshooting:
 
 Troubleshooting

docs/projectconf.rst

@@ -513,6 +513,9 @@ This option can be set by global environment variable
 ``extra_script``
 ^^^^^^^^^^^^^^^^
 
+.. contents::
+    :local:
+
 Allows to launch extra script using `SCons <http://www.scons.org>`_ software
 construction tool. For more details please follow to "Construction Environments"
 section of
@@ -521,13 +524,23 @@ section of
 This option can be set by global environment variable
 :envvar:`PLATFORMIO_EXTRA_SCRIPT`.
 
+Take a look at the multiple snippets/answers for the user questions:
+
+  - `#462 Split C/C++ build flags <https://github.com/platformio/platformio/issues/462#issuecomment-172667342>`_
+  - `#365 Extra configuration for ESP8266 uploader <https://github.com/platformio/platformio/issues/365#issuecomment-163695011>`_
+  - `#351 Specific reset method for ESP8266 <https://github.com/platformio/platformio/issues/351#issuecomment-161789165>`_
+  - `#247 Specific options for avrdude <https://github.com/platformio/platformio/issues/247#issuecomment-118169728>`_.
+
+Custom Uploader
+'''''''''''''''
+
 Example, specify own upload command for :ref:`platform_atmelavr`:
 
 ``platformio.ini``:
 
 .. code-block:: ini
 
-    [env:env_with_specific_extra_script]
+    [env:env_custom_uploader]
     platform = atmelavr
     extra_script = /path/to/extra_script.py
     custom_option = hello
@@ -544,14 +557,50 @@ Example, specify own upload command for :ref:`platform_atmelavr`:
     # print env.Dump()
     # print ARGUMENTS
 
+Before/Pre and After/Post actions
+'''''''''''''''''''''''''''''''''
 
-* see built-in examples of `PlatformIO build scripts <https://github.com/platformio/platformio/tree/develop/platformio/builder/scripts>`_.
-* take a look at the multiple snippets/answers for the user questions:
+PlatformIO Build System has rich API that allows to attach different pre-/post
+actions (hooks) using ``env.AddPreAction(target, callback)`` function. A first
+argument ``target`` can be a name of target that is passed using
+:option:`platformio run --target` command or path to file which PlatformIO
+processes (ELF, HEX, BIN, etc.). For example, to call function before HEX file
+will be created, need to use as a ``$BUILD_DIR/firmware.hex`` target value.
+
+The example below demonstrates how to call different functions
+when :option:`platformio run --target` is called with ``upload`` value.
+`extra_script.py` file is located on the same level as ``platformio.ini``.
+
+``platformio.ini``:
+
+.. code-block:: ini
+
+    [env:pre_and_post_hooks]
+    extra_script = extra_script.py
+
+``extra_script.py``:
+
+.. code-block:: python
+
+    Import("env")
+
+    def before_upload(source, target, env):
+        print "before_upload"
+        # do some actions
+
+
+    def after_uploads(source, target, env):
+        print "after_uploads"
+        # do some actions
+
+    print "Current build targets", map(str, BUILD_TARGETS)
+
+    # env.AddPreAction("$BUILD_DIR/firmware.elf", callback...)
+    # env.AddPostAction("$BUILD_DIR/firmware.hex", callback...)
+
+    env.AddPreAction("upload", before_upload)
+    env.AddPostAction("upload", after_uploads)
 
-  - `#462 Split C/C++ build flags <https://github.com/platformio/platformio/issues/462#issuecomment-172667342>`_
-  - `#365 Extra configuration for ESP8266 uploader <https://github.com/platformio/platformio/issues/365#issuecomment-163695011>`_
-  - `#351 Specific reset method for ESP8266 <https://github.com/platformio/platformio/issues/351#issuecomment-161789165>`_
-  - `#247 Specific options for avrdude <https://github.com/platformio/platformio/issues/247#issuecomment-118169728>`_.
 
 .. _projectconf_targets: