Subfolder utility of library Wire

Using Arduino Programming Questions
1

I'm studying the Wire Library and I've found a subfolder named "utility" which contains twi.h and twi.c files used by Wire.cpp (Arduino UNO and compatibles, not DUE).

Topic How to include .h files in utility folder? - Libraries - Arduino Forum explains how C++ functions call C function with an extern "C" {#include ...} declaration.

My question is : Where is documented the usage of the subfolder "utility" ?
Could somebody give a link where the c++ subfolder "utility" is described ?

2

Could somebody give a link where the c++ subfolder "utility" is described ?

The fact that the IDE looks in a sub-folder named utility has nothing to do with standard C++. The name doesn't even have to be utility. Some libraries use utils.

3

My question is : Where is documented the usage of the subfolder "utility" ?

It's just used by the Wire library. The Wire documentation is all you need.

4

PaulS:
The fact that the IDE looks in a sub-folder named utility has nothing to do with standard C++. The name doesn't even have to be utility. Some libraries use utils.

Hi PaulS,
If it's not a C++ standard, it's an AVR GCC compiler/linker directive. Do you know where the directive is written ?
I'm interrested to know other hidden directives.

5

Thanks Nick,
I'm debugging Wire because I've found some frozen cases communicating in noisy environment.

6

Hi PaulS,
If it's not a C++ standard, it's an AVR GCC compiler/linker directive. Do you know where the directive is written ?
I'm interrested to know other hidden directives.

They are not hidden. To use an include file in utility or utils or bobIsYourUncle, you need to include the folder name in the statement:

#include "bobIsYourUncle/someSillyName.h"
7

PaulS:
They are not hidden. To use an include file in utility or utils or bobIsYourUncle, you need to include the folder name in the statement:

#include "bobIsYourUncle/someSillyName.h"

I'm not sure of your answer.
Consider Wire.cpp example:

...
extern "C" {
  #include <stdlib.h>
  #include <string.h>
  #include <inttypes.h>
  #include "twi.h"
}
...

The "twi.h" file is Inside the sulfolder "utility" and is not mentionned in #include sentence.
So how is it possible? Which rule?

8

Good question. If you do a trial compile you will see something like this:

(install_folder)/hardware/tools/avr/bin/avr-g++ -c -g -Os -Wall -fno-exceptions -ffunction-sections -fdata-sections -mmcu=atmega328p -DF_CPU=16000000L -MMD -DUSB_VID=null -DUSB_PID=null -DARDUINO=106 -I(install_folder)/hardware/arduino/cores/arduino -I(install_folder)/hardware/arduino/variants/standard [color=green]-I(install_folder)/libraries/Wire[/color] (temp_folder)/[color=blue]sketch_aug19a.cpp[/color] -o (temp_folder)/sketch_aug19a.cpp.o

(install_folder)/hardware/tools/avr/bin/avr-g++ -c -g -Os -Wall -fno-exceptions -ffunction-sections -fdata-sections -mmcu=atmega328p -DF_CPU=16000000L -MMD -DUSB_VID=null -DUSB_PID=null -DARDUINO=106 -I(install_folder)/hardware/arduino/cores/arduino -I(install_folder)/hardware/arduino/variants/standard [color=green]-I(install_folder)/libraries/Wire -I(install_folder)/libraries/Wire/utility[/color] (install_folder)/libraries/Wire/[color=blue]Wire.cpp[/color] -o (temp_folder)/Wire/Wire.cpp.o

First line compiles your sketch. It pulls the library in directly from the libraries folder (it doesn't make a copy) and this is possible because of:

-I(install_folder)/libraries/Wire

Thus it finds Wire.h.

Now when it goes to compile Wire.cpp it add include directives for the sub-folders:

-I(install_folder)/libraries/Wire -I(install_folder)/libraries/Wire/utility

So it now finds the utility files - but only when compiling Wire.cpp, not when compiling your sketch. Your sketch doesn't need to know about the utility includes.