|
| 1 | +How to specify global build defines and options |
| 2 | +=============================================== |
| 3 | + |
| 4 | +To create global defines for a Sketch, create a file with a name based |
| 5 | + on your sketch’s file name followed by ``.globals.h`` in the Sketch folder. |
| 6 | + For example, if the main Sketch file is named |
| 7 | +``LowWatermark.ino``, its global defines file would be |
| 8 | +``LowWatermark.ino.globals.h``. This file will be implicitly included |
| 9 | +with every module built for your Sketch. Do not directly include it in |
| 10 | +any of your sketch files or in any other source files. There is no need |
| 11 | +to create empty/dummy files, when not used. |
| 12 | + |
| 13 | +This global define ``.h`` also supports embedding compiler command-line |
| 14 | +options in a unique “C” block comment. Compiler options are placed in a |
| 15 | +“C” block comment starting with ``/*@create-file:build.opt@``. This |
| 16 | +signature line must be alone on a single line. The block comment ending |
| 17 | +``*/`` should also be alone on a single line. In between, place your |
| 18 | +compiler command-line options just as you would have for the GCC @file |
| 19 | +command option. |
| 20 | + |
| 21 | +Actions taken in processing comment block to create ``build.opt`` \* for |
| 22 | +each line, white space is trimmed \* blank lines are skipped \* lines |
| 23 | +starting with ``*``, ``//``, or ``#`` are skipped \* the remaining |
| 24 | +results are written to build tree\ ``/core/build.opt`` \* ``build.opt`` |
| 25 | +is finished with a ``-include ...`` command, which references the global |
| 26 | +.h its contents were extracted from. |
| 27 | + |
| 28 | +Example Sketch: ``LowWatermark.ino`` |
| 29 | + |
| 30 | +.. code:: cpp |
| 31 | +
|
| 32 | + #include <umm_malloc/umm_malloc.h> // has prototype for umm_free_heap_size_min() |
| 33 | +
|
| 34 | + void setup() { |
| 35 | + Serial.begin(115200); |
| 36 | + delay(200); |
| 37 | + #ifdef MYTITLE1 |
| 38 | + Serial.printf("\r\n" MYTITLE1 MYTITLE2 "\r\n"); |
| 39 | + #else |
| 40 | + Serial.println("ERROR: MYTITLE1 not present"); |
| 41 | + #endif |
| 42 | + Serial.printf("Heap Low Watermark %u\r\n", umm_free_heap_size_min()); |
| 43 | + } |
| 44 | +
|
| 45 | + void loop() {} |
| 46 | +
|
| 47 | +Global ``.h`` file: ``LowWatermark.ino.globals.h`` |
| 48 | + |
| 49 | +.. code:: cpp |
| 50 | +
|
| 51 | + /*@create-file:build.opt@ |
| 52 | + // An embedded build.opt file using a "C" block comment. The starting signature |
| 53 | + // must be on a line by itself. The closing block comment pattern should be on a |
| 54 | + // line by itself. Each line within the block comment will be space trimmed and |
| 55 | + // written to build.opt, skipping blank lines and lines starting with '//', '*' |
| 56 | + // or '#'. |
| 57 | +
|
| 58 | + * this line is ignored |
| 59 | + # this line is ignored |
| 60 | + -DMYTITLE1="\"Running on \"" |
| 61 | + -O3 |
| 62 | + //-fanalyzer |
| 63 | + -DUMM_STATS_FULL=1 |
| 64 | + */ |
| 65 | +
|
| 66 | + #ifndef LOWWATERMARK_INO_GLOBALS_H |
| 67 | + #define LOWWATERMARK_INO_GLOBALS_H |
| 68 | +
|
| 69 | + #if !defined(__ASSEMBLER__) |
| 70 | + // Defines kept away from assembler modules |
| 71 | + // i.e. Defines for .cpp, .ino, .c ... modules |
| 72 | + #endif |
| 73 | +
|
| 74 | + #if defined(__cplusplus) |
| 75 | + // Defines kept private to .cpp modules |
| 76 | + //#pragma message("__cplusplus has been seen") |
| 77 | + #define MYTITLE2 "Empty" |
| 78 | + #endif |
| 79 | +
|
| 80 | + #if !defined(__cplusplus) && !defined(__ASSEMBLER__) |
| 81 | + // Defines kept private to .c modules |
| 82 | + #define MYTITLE2 "Full" |
| 83 | + #endif |
| 84 | +
|
| 85 | + #if defined(__ASSEMBLER__) |
| 86 | + // Defines kept private to assembler modules |
| 87 | + #endif |
| 88 | +
|
| 89 | + #endif |
| 90 | +
|
| 91 | +Aggressive Caching of ``core.a`` |
| 92 | +================================ |
| 93 | + |
| 94 | +Using global defines or compiler command-line options will lead to bad |
| 95 | +builds when the **Aggressively cache compiled core** feature is enabled. |
| 96 | +When ``#define`` changes require ``core.a`` to be recompiled, and |
| 97 | +multiple Sketches are open, they can no longer reliably share one cached |
| 98 | +``core.a``. In a simple case: The 1st Sketch to be built has its version |
| 99 | +of ``core.a`` cached. Other sketches will use this cached version for |
| 100 | +their builds. |
| 101 | + |
| 102 | +To turn this off, you need to find the location of ``preferences.txt``. |
| 103 | +Using the Arduino IDE, go to *File->Preferences*. Make note of the path |
| 104 | +to ``prefereces.txt``. You cannot edit the file while the Arduino IDE is |
| 105 | +running. Close all Arduino IDE windows and edit the file |
| 106 | +``preferences.txt``. Change ``compiler.cache_core=true`` to |
| 107 | +``compiler.cache_core=false`` and save. Then each sketch will maintain |
| 108 | +its *own* copy of ``core.a``. The alternative when using |
| 109 | +``compiler.cache_core=true``, is to close all Arduino IDE sketch |
| 110 | +windows. Start and run *only* one instance of the IDE, while building a |
| 111 | +Sketch that uses global defines. |
| 112 | + |
| 113 | +Other build confusion |
| 114 | +===================== |
| 115 | + |
| 116 | +1. Renaming files does not change the last modified timestamp, possibly |
| 117 | + causing issues when replacing files by renaming and rebuilding. A good |
| 118 | + example of this problem would be to have then fixed a typo in file |
| 119 | + name ``LowWatermark.ino.globals.h``. You need to touch (update |
| 120 | + timestamp) the file so a “rebuild all” is performed. |
| 121 | +2. When a ``.h`` file is renamed in the sketch folder, a copy of the old |
| 122 | + file remains in the build sketch folder. This can create confusion if |
| 123 | + you missed an edit in updating an ``#include`` in one or more of your |
| 124 | + modules. That module will continue to use the stale version of the |
| 125 | + ``.h`` until you restart the IDE or other major changes that would |
| 126 | + cause the IDE to delete and recopy the contents from the source |
| 127 | + Sketch directory. Changes on the IDE Tools selection may cause a |
| 128 | + complete rebuild, clearing the problem. This may be the culprit for |
| 129 | + “What! It built fine last night!” |
0 commit comments