Added context help for build option support

Author: mhightower83

doc/faq/a06-global-build-options.rst

@@ -2,8 +2,8 @@ How to specify global build defines and options
 ===============================================
 
 To create global defines for a Sketch, create a file with a name based
- on your sketch’s file name followed by ``.globals.h`` in the Sketch folder.
- For example, if the main Sketch file is named
+on your sketch’s file name followed by ``.globals.h`` in the Sketch
+folder. For example, if the main Sketch file is named
 ``LowWatermark.ino``, its global defines file would be
 ``LowWatermark.ino.globals.h``. This file will be implicitly included
 with every module built for your Sketch. Do not directly include it in
@@ -21,9 +21,10 @@ command option.
 Actions taken in processing comment block to create ``build.opt`` \* for
 each line, white space is trimmed \* blank lines are skipped \* lines
 starting with ``*``, ``//``, or ``#`` are skipped \* the remaining
-results are written to build tree\ ``/core/build.opt`` \* ``build.opt``
-is finished with a ``-include ...`` command, which references the global
-.h its contents were extracted from.
+results are written to build tree\ ``/core/build.opt`` \* multiple
+``/*@create-file:build.opt@`` ``*/`` comment blocks are not allowed \*
+``build.opt`` is finished with a ``-include ...`` command, which
+references the global .h its contents were extracted from.
 
 Example Sketch: ``LowWatermark.ino``
 
@@ -72,7 +73,7 @@ Global ``.h`` file: ``LowWatermark.ino.globals.h``
    #endif
 
    #if defined(__cplusplus)
-   // Defines kept private to .cpp modules
+   // Defines kept private to .cpp and .ino modules
    //#pragma message("__cplusplus has been seen")
    #define MYTITLE2 "Empty"
    #endif
@@ -93,14 +94,14 @@ Aggressive Caching of ``core.a``
 
 Using global defines or compiler command-line options will lead to bad
 builds when the **Aggressively cache compiled core** feature is enabled.
-When ``#define`` changes require ``core.a`` to be recompiled, and
-multiple Sketches are open, they can no longer reliably share one cached
+When ``#define`` changes require rebuilding ``core.a`` and multiple
+Sketches are open, they can no longer reliably share one cached
 ``core.a``. In a simple case: The 1st Sketch to be built has its version
 of ``core.a`` cached. Other sketches will use this cached version for
 their builds.
 
 To turn this off, you need to find the location of ``preferences.txt``.
-Using the Arduino IDE, go to *File->Preferences*. Make note of the path
+From the Arduino IDE, go to *File->Preferences*. Make note of the path
 to ``prefereces.txt``. You cannot edit the file while the Arduino IDE is
 running. Close all Arduino IDE windows and edit the file
 ``preferences.txt``. Change ``compiler.cache_core=true`` to
@@ -113,11 +114,12 @@ Sketch that uses global defines.
 Other build confusion
 =====================
 
-1. Renaming files does not change the last modified timestamp, possibly
-   causing issues when replacing files by renaming and rebuilding. A good
+1. Renaming a file does not change the last modified timestamp, possibly
+   causing issues when adding a file by renaming and rebuilding. A good
    example of this problem would be to have then fixed a typo in file
    name ``LowWatermark.ino.globals.h``. You need to touch (update
    timestamp) the file so a “rebuild all” is performed.
+
 2. When a ``.h`` file is renamed in the sketch folder, a copy of the old
    file remains in the build sketch folder. This can create confusion if
    you missed an edit in updating an ``#include`` in one or more of your

tools/mkbuildoptglobals.py

@@ -187,6 +187,7 @@
 # existing embedded documentation methods.
 build_opt_signature = "/*@create-file:build.opt@"
 
+docs_url = "https://arduino-esp8266.readthedocs.io/en/latest/faq/a06-global-build-options.html"
 
 def print_msg(*args, **kwargs):
     print(*args, flush=True, **kwargs)
@@ -307,6 +308,7 @@ def extract_create_build_opt_file(globals_h_fqfn, file_name, build_opt_fqfn):
     build_opt.close()
     return complete_comment
 
+
 def get_sketchbook_globals(build_path, sketchbook_globals_path, build_opt_fqfn):
     """
     Construct path to sketchbook globals using relative path from users home directory.
@@ -321,6 +323,7 @@ def get_sketchbook_globals(build_path, sketchbook_globals_path, build_opt_fqfn):
 
 def main():
     global build_opt_signature
+    global docs_url
 
     if len(sys.argv) >= 4:
         source_globals_h_fqfn = os.path.normpath(sys.argv[1])
@@ -353,7 +356,9 @@ def main():
             # positives. Only report when globals.h is being used.
             if os.path.getsize(globals_h_fqfn) and len(os.listdir(build_path)) < 20:
                 print_err("Aggressive caching of core.a might be enabled. This may create build errors.")
-                print_err("Suggest turning off in preferences.txt: \"compiler.cache_core=false\"")
+                print_err("  Suggest turning off in preferences.txt: \"compiler.cache_core=false\"")
+                print_err("  Read more at " + docs_url)
+
         else:
             # Info: When platform.txt, platform.local.txt, or IDE Tools are
             # changed, our build path directory was cleaned. Note,
@@ -371,16 +376,26 @@ def main():
         # controls the rebuild on change. We can always extact a new build.opt
         # w/o triggering a needless rebuild.
         embedded_options = extract_create_build_opt_file(globals_h_fqfn, globals_name, build_opt_fqfn)
-        if not embedded_options and os.path.exists(source_globals_h_fqfn):
-            print_msg("To add embedded compiler options, include them in a block comment starting with '" + build_opt_signature + "'." )
+
+        # Provide context help for build option support.
+        source_build_opt_h_fqfn = os.path.join(os.path.dirname(source_globals_h_fqfn), "build_opt.h")
+        if os.path.exists(source_build_opt_h_fqfn) and not embedded_options:
+            print_err("Build options file '" + source_build_opt_h_fqfn + "' not supported.")
+            print_err("  Add build option content to '" + source_globals_h_fqfn + "'.")
+            print_err("  Embedd compiler command-line options in a block comment starting with '" + build_opt_signature + "'.")
+            print_err("  Read more at " + docs_url)
+        elif os.path.exists(source_globals_h_fqfn):
+            if not embedded_options:
+                print_msg("Tip: Embedd compiler command-line options in a block comment starting with '" + build_opt_signature + "'.")
+                print_msg("  Read more at " + docs_url)
 
         add_include_line(build_opt_fqfn, globals_h_fqfn)
 
         if len(sketchbook_globals_path):
             get_sketchbook_globals(build_path, sketchbook_globals_path, build_opt_fqfn)
 
     else:
-        print_err("Too few arguments. Required arguments:")
+        print_err("Too few arguments. Add arguments:")
         print_err("  Source FQFN SketchName.ino.globals.h, Build FQFN SketchName.ino.globals.h, Build FQFN build.opt")
 
 if __name__ == '__main__':