I'm having difficulty finding which actual arduino.h (there are a dozen of them) is accessed by my Mac. I can browse the package contents for the files, but it's unclear where in the IDE it actually decides where to grab include files from.
Any help would be much appreciated.
If you enable verbose output during compilation (in the preferences of the Arduino IDE), it will show you the compiler commands run by the builder.
"/home/user/.arduino15/packages/arduino/tools/avr-gcc/4.9.2-atmel3.5.4-arduino2/bin/avr-g++" -c -g -Os -w -std=gnu++11 -fpermissive -fno-exceptions -ffunction-sections -fdata-sections -fno-threadsafe-statics -flto -w -x c++ -E -CC -mmcu=atmega328p -DF_CPU=16000000L -DARDUINO=10805 -DARDUINO_AVR_UNO -DARDUINO_ARCH_AVR "-I/home/user/.arduino15/packages/arduino/hardware/avr/1.6.20/cores/arduino" "-I/home/user/.arduino15/packages/arduino/hardware/avr/1.6.20/variants/standard" "/tmp/arduino_build_722314/sketch/Blink.ino.cpp" -o "/dev/null"
Note the section
It tells the compiler to add that directory to the include path (where it will search for <Arduino.h>).
Wow that was fast and helpful. Thank you! Followup question: is there a decoder ring to decipher what all that means? I do see some references to libraries, but it would be nice to have an overview.
The first quoted string is the (compiler) command. In this case, it uses the version of avr-gcc taht comes with the Arduino AVR core.
Then there are many compiler flags (e.g. -c compiles to an intermediate object file, -g includes debug information, -D defines a preprocessor macro, -I specifies an include directory, -o specifies the output file, ...).
The filename without a flag (before the -o flag) is the source file to be compiled.
First, your sketch (ino file) is prepared (function prototypes are added) and compiled into an object file.
It also detects what libraries your sketch uses. I haven't looked into how this works yet. Maybe someone else will be able to tell you more about it.
Then all implementation files of the libraries are compiled to object files.
Then there are some lines compiling the core files to object files, and they are added to an archive (by avr-gcc-ar), this is a static library.
Finally, all object files are linked together to form the final executable.
Note that the Arduino.h used can depend on which board you have selected from the Tools > Board menu. The Arduino AVR Boards will all use the same file. Boards from hardware packages (e.g. Arduino SAMD Boards) will use their own core folder. The method PieterP described will always tell you which one is being used.