Global Defines - mhightower83/Arduino-ESP8266-misc GitHub Wiki

Status

A PR adding this feature to Arduino ESP8266 has been merged. See arduino-esp8266.readthedocs for details.

The features this page will add, is support for

  • Option for an Arduino IDE-wide globals.h file. This was omitted from the PR due to concerns of set and forget confusion it could cause. If you share this concern, you can omit the setting.
  • Option to split build.opt options into two block "C" comments, one for production and one for debugging. This one is currently in PR Add debug support for build.opt #8637.

GitHub Gist mhightower83/prebuild-v2.py has these two features added.

The remainder of this page is stale and will be updated later

What is this for?

This tweak enables a Sketch to have a unique set of build properties, that apply to all library and core modules built. This is implemented by adding some lines to platform.local.txt and saving GitHub Gist mhightower83/prebuild-v2.py to the tools folder.

Supported Options:

  • SketchName.ino.globals.h - Sketch global defines and optional embedded compiler command-line options.
  • build_opt.h - Raw (not encapsulated) compiler command-line options, an alternative to embedded.
  • Sketchbook Global defines

Implementation Objectives

  • Allows you to keep a .h file in your Sketch directory, that will be used to store global defines. This file will be implicitly included with every module built for your Sketch. Do not directly include it in any of your sketch files or in any other source files. This file should be named SketchName.ino.globals.h, where SketchName is the real name of the Sketch.
  • Allows you to keep, project-specific compiler command-line options, in a file in your Sketch directory. This can be done by embedding the options in a special "C" block comment. An alternative to this method is to create the file build_opt.h in the sketch directory.
  • Allows for global-global defines that are applied to all Arduino IDE Sketches. The default path/file for this is Arduino/include/ide_globals.h in the Sketchbook directory. This file will be implicitly included with every module built. Also, it should not be directly specified in any of the source files.
  • All these features are optional. No need to create empty/dummy files, when not used.

Setup/Install

  1. Prerequisites:
  • A current version of the Arduino IDE.
  • ESP8266 3rd Party Board support installed.

To get started you need to find the platform folder to save platform.local.txt in. You can locate that folder by doing the following steps.

  • Select a board from the ESP8266 list.
  • Set Preferences for a verbose compile,
    • From the Arduino IDE select Edit->File->Preferences.
    • Find the selection: "Show verbose output during: [] compilation [] upload"
    • Check the box for "compilation"
  • Open a new sketch.
  • Run Verify, (Sketch->Verify/Compile).
  • Scroll up to the top of the Arduino IDE message area.
  • Look for the text "Using core 'esp8266' from platform in folder" and make note of the path. This line will be near the top, before "Detecting libraries used...". This is the location you need to remember for saving platform.local.txt.

A sample of Arduino IDE message area text:

  C:\Program Files (x86)\Arduino\arduino-builder -dump-prefs ...
  C:\Program Files (x86)\Arduino\arduino-builder -compile -logger=machine ...
  Using board 'generic' from platform in folder: /home/mhightower83/Arduino/hardware/esp8266com/esp8266
> Using core 'esp8266' from platform in folder: /home/mhightower83/Arduino/hardware/esp8266com/esp8266
  Detecting libraries used...
  ...

  1. Using the platform folder you found above, save GitHub Gist mhightower83/prebuild-v2.py to the platform path/tools/ directory.

  2. Add/Create these entries to platform.local.txt in the platform folder. This is the same folder that holds the file platform.txt it supplements.

runtime.tools.prebuild={runtime.platform.path}/tools/prebuild-v2.py

build.opt.source.path={build.source.path}/build_opt.h
build.opt.path={build.path}/core/build.opt
build_opt.proxy.path={build.path}/core/PROXY.build_opt.h
globals.h.name={build.project_name}.globals.h

sketchbook.globals.h.path=
# If a sketchbook global include is desired, use `sketchbook.globals.h.path` to
# specify a relative path from the home directory. An example assuming the 
# Arduino Sketchbook path is `~/Arduino`:
#   sketchbook.globals.h.path=Arduino/include/ide_globals.h

recipe.hooks.prebuild.2.pattern="{runtime.tools.python3.path}/python3" "{runtime.tools.prebuild}" "{build.opt.source.path}" "{build.opt.path}" "{build_opt.proxy.path}" "{globals.h.name}" "{sketchbook.globals.h.path}"

compiler.cpreprocessor.flags=-D__ets__ -DICACHE_FLASH -U__STRICT_ANSI__ -D_GNU_SOURCE @{build.opt.path} "-I{compiler.sdk.path}/include" "-I{compiler.sdk.path}/{build.lwip_include}" "-I{compiler.libc.path}/include" "-I{build.path}/core"
  1. When used with compiler command-line option in build.opt, the Aggressively cache compiled core feature will eventually lead to bad 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 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 compiler.cache_core=false and save. For a longer description of the issue see Overzealous Caching core.a

Using features:

Global Defines for a Sketch Build

To create global defines for your Sketch, you simply create a file by the name SketchName.ino.globals.h in your Sketch's directory and place your defines in it. Note SketchName must be replaced with the real name of the Sketch.

This .h also supports embedding compiler command-line options in a block comment.

An example of SketchName.ino.globals.h:

/*@create-file:build.opt@
// This comment block is an alternative to using `build_opt.h`
// If `build_opt.h` is in your sketch folder, it takes priority over this block.
-DMYDEFINE="\"Chimichangas do not exist\""
-O3
-fanalyzer
-DUMM_STATS_FULL=1
*/

#ifndef SKETCH_INO_GLOBALS_H
#define SKETCH_INO_GLOBALS_H

#if defined(__cplusplus)
// Defines kept private to .cpp modules
#pragma message("__cplusplus has been seen")
#endif

#if !defined(__cplusplus) && !defined(__ASSEMBLER__)
// Defines kept private to .c modules
#endif

#if defined(__ASSEMBLER__)
// Defines kept private to assembler modules
#endif

#endif

Sketch Specific - Compiler command-line options

An alternate way to add compiler command-line options to a Sketch, create the file build_opt.h, in the sketch directory. Place the compiler command-line options in the file as you would have created a file for the GCC @file command option. Only put compiler command-line options in the file. And, never reference this build_opt.h from other source code files. If both build_opt.h and an embedded comment block in SketchName.ino.globals.h exist, build_opt.h is used.

While having non "C" code in a .h is a bit odd, the file having a .h extension allows you to edit it with the Arduino-IDE. Personally, I prefer encapsulating the compiler options in a "C" block comment as shown above.

An example of build_opt.h:

-DMYDEFINE="\"Chimichangas do not exist\""
-O3
-fanalyzer
-DUMM_STATS=2

Global Defines for all Sketches in Sketchbook

Global global defines for all sketches: If a sketchbook global include is desired, use sketchbook.globals.h.path= in platform.local.txt to specify a relative path from the home directory.

An example assuming the Arduino Sketchbook path is ~/Arduino:

sketchbook.globals.h.path=Arduino/include/ide_globals.h

To complete this create a folder, include, inside your Arduino Sketchbook folder. Then inside the include folder create the file ide_globals.h and place Sketchbook global defines in it.

The Sketchbook directory is commonly named Arduino and is located in the user's home directory, at least on Linux. On Windows maybe in the Document folder. To locate your Sketchbook folder:

  • Start the Arduino IDE
  • Select File->Preferences
  • Look for "Sketchbook location:"; it will appear as the first item in the Settings tab on the Preferences window.

An example of ide_globals.h:

#ifndef IDE_GLOBALS_H
#define IDE_GLOBALS_H

#define STASSID "Bobiverse"
#define STAPSK  "DeltaPavonis"

#endif

Another alternative

Support for adding compiler command-line options to a Sketch has been added to some platforms. A sketch file build_opt.h is used to hold the command-line options. It must not contain any "C" code and must not be referenced by any #include statements. There are no dependencies to cause a rebuild. If you change build_opt.h, you may need to restart the Arduino IDE to get your sketch built correctly. Also, you may want to address the issue of Overzealous Caching of core.a

While having non "C" code in a .h is a bit odd, the file having a .h extension allows you to edit it with the Arduino-IDE.

Closing Observation/Frustration

It looks like the topic of providing more advanced build options in the Arduino IDE was ongoing long before I started using it 4 years ago and after an initial search, made my own solution to handle global defines. So 3.5 years later I search again. Maybe it is the Dyslexia/ADHD, I could not get a clear picture of what is what and where things are going or if they really are going anywhere. So this update seems to be time well spent. I don't expect to see anything that will supersede it any time soon.

For the old way

If you are looking for the details of the previous method follow this link: Old Global Defines