Add prebuild script to use additional build options

doc/faq/readme.rst

@@ -152,6 +152,41 @@ Artificially clearing them is a workaround to help saving precious heap.
 
 Ref.  `#1923 <https://github.com/esp8266/Arduino/issues/1923>`__
 
+Use custom defines from build options file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A file named ``build_opt.h`` next to the ``sketch.ino`` file enables the user
+to specify custom definitons in a central and organized location.
+
+The following code is a slightly modified Blink example sketch. It opens the
+possibility to define the ``WAIT_TIME`` between the LED state changes. If no
+``build_opt.h`` file is placed next to the sketch file, the default value will
+be set as 1000ms in this example.
+
+.. code:: cpp
+
+    #ifndef WAIT_TIME
+    #define WAIT_TIME   1000             // use 1000ms if not defined different
+    #endif
+
+    void setup() {
+      // initialize digital pin LED_BUILTIN as an output.
+      pinMode(LED_BUILTIN, OUTPUT);
+    }
+
+    void loop() {
+      digitalWrite(LED_BUILTIN, HIGH);
+      delay(WAIT_TIME);
+      digitalWrite(LED_BUILTIN, LOW);
+      delay(WAIT_TIME);
+    }
+
+Place the following content in a file named ``build_opt.h`` at the same
+location as the ``sketch.ino`` file to define the ``WAIT_TIME`` to 500ms.
+
+.. code:: cpp
+
+    -DWAIT_TIME=500
 
 Why is there a board generator and what about it ?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

platform.txt

@@ -12,6 +12,7 @@ version=3.0.1-dev
 runtime.tools.xtensa-lx106-elf-gcc.path={runtime.platform.path}/tools/xtensa-lx106-elf
 runtime.tools.python3.path={runtime.platform.path}/tools/python3
 
+runtime.tools.prebuild={runtime.platform.path}/tools/prebuild.py
 runtime.tools.esptool.path={runtime.platform.path}/tools/esptool
 runtime.tools.signing={runtime.platform.path}/tools/signing.py
 runtime.tools.elf2bin={runtime.platform.path}/tools/elf2bin.py
@@ -85,6 +86,13 @@ compiler.size.cmd=xtensa-lx106-elf-size
 # This can be overridden in boards.txt
 build.extra_flags=-DESP8266
 
+# Pre and post build hooks
+build.opt.name=build_opt.h
+build.opt.path={build.path}/sketch/{build.opt.name}
+
+# Create empty {build.opt} if it does not exist in the output sketch dir
+recipe.hooks.prebuild.1.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.prebuild}" "{build.path}" "{build.source.path}"
+
 # These can be overridden in platform.local.txt
 compiler.c.extra_flags=
 compiler.c.elf.extra_flags=
@@ -107,13 +115,13 @@ recipe.hooks.linking.prelink.3.pattern="{compiler.path}{compiler.c.cmd}" -CC -E
 recipe.hooks.linking.prelink.4.pattern="{compiler.path}{compiler.c.cmd}" -CC -E -P {build.vtable_flags} {build.mmuflags} "{runtime.platform.path}/tools/sdk/ld/eagle.app.v6.common.ld.h" -o "{build.path}/local.eagle.app.v6.common.ld"
 
 ## Compile c files
-recipe.c.o.pattern="{compiler.path}{compiler.c.cmd}" {compiler.cpreprocessor.flags} {compiler.c.flags} -D{build.sdk}=1 -DF_CPU={build.f_cpu} {build.lwip_flags} {build.debug_port} {build.debug_level} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} -DARDUINO_BOARD="{build.board}" {build.led} {build.flash_flags} {compiler.c.extra_flags} {build.extra_flags} {includes} "{source_file}" -o "{object_file}"
+recipe.c.o.pattern="{compiler.path}{compiler.c.cmd}" {compiler.cpreprocessor.flags} {compiler.c.flags} -D{build.sdk}=1 -DF_CPU={build.f_cpu} {build.lwip_flags} {build.debug_port} {build.debug_level} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} -DARDUINO_BOARD="{build.board}" {build.led} {build.flash_flags} {compiler.c.extra_flags} {build.extra_flags} "@{build.opt.path}" {includes} "{source_file}" -o "{object_file}"
 
 ## Compile c++ files
-recipe.cpp.o.pattern="{compiler.path}{compiler.cpp.cmd}" {compiler.cpreprocessor.flags} {compiler.cpp.flags} -D{build.sdk}=1 -DF_CPU={build.f_cpu} {build.lwip_flags} {build.debug_port} {build.debug_level} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} -DARDUINO_BOARD="{build.board}" {build.led} {build.flash_flags} {compiler.cpp.extra_flags} {build.extra_flags} {includes} "{source_file}" -o "{object_file}"
+recipe.cpp.o.pattern="{compiler.path}{compiler.cpp.cmd}" {compiler.cpreprocessor.flags} {compiler.cpp.flags} -D{build.sdk}=1 -DF_CPU={build.f_cpu} {build.lwip_flags} {build.debug_port} {build.debug_level} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} -DARDUINO_BOARD="{build.board}" {build.led} {build.flash_flags} {compiler.cpp.extra_flags} {build.extra_flags} "@{build.opt.path}" {includes} "{source_file}" -o "{object_file}"
 
 ## Compile S files
-recipe.S.o.pattern="{compiler.path}{compiler.c.cmd}" {compiler.cpreprocessor.flags} {compiler.S.flags} -D{build.sdk}=1 -DF_CPU={build.f_cpu} {build.lwip_flags} {build.debug_port} {build.debug_level} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} -DARDUINO_BOARD="{build.board}" {build.led} {build.flash_flags} {compiler.S.extra_flags} {build.extra_flags} {includes} "{source_file}" -o "{object_file}"
+recipe.S.o.pattern="{compiler.path}{compiler.c.cmd}" {compiler.cpreprocessor.flags} {compiler.S.flags} -D{build.sdk}=1 -DF_CPU={build.f_cpu} {build.lwip_flags} {build.debug_port} {build.debug_level} -DARDUINO={runtime.ide.version} -DARDUINO_{build.board} -DARDUINO_ARCH_{build.arch} -DARDUINO_BOARD="{build.board}" {build.led} {build.flash_flags} {compiler.S.extra_flags} {build.extra_flags} "@{build.opt.path}" {includes} "{source_file}" -o "{object_file}"
 
 ## Create archives
 recipe.ar.pattern="{compiler.path}{compiler.ar.cmd}" {compiler.ar.flags} {compiler.ar.extra_flags} "{archive_file_path}" "{object_file}"

tools/prebuild.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# prebuild.py — create build_opt.h file in build directory if it does not exist
+#
+# This script will create a folder called "sketch" in the build path if it does
+# not yet exist and create an empty build options file inside if this does also
+# not exist yet
+#
+# Written by brainelectronics, 2021.
+#
+
+import os
+import sys
+
+
+def create_sketch_dir(build_path):
+    sketch_build_path = os.path.join(build_path, "sketch")
+
+    if not os.path.exists(sketch_build_path):
+        os.makedirs(sketch_build_path)
+
+
+def create_build_options_file(source_path, build_path):
+    file_source_path = os.path.join(source_path, "build_opt.h")
+    file_build_path = os.path.join(build_path, "sketch", "build_opt.h")
+
+    if not os.path.exists(file_source_path):
+        open(file_build_path, 'a').close()
+
+
+def main():
+    if len(sys.argv) == 3:
+        build_path = sys.argv[1]
+        source_path = sys.argv[2]
+
+        create_sketch_dir(build_path)
+        create_build_options_file(source_path, build_path)
+
+
+if __name__ == '__main__':
+    sys.exit(main())