Conflict of include files from an Arduino library

Question

I'm writing Arduino libraries and have the folder structure as follows:

libraries   
  +Foo
    -Foo.h
    -Helper.h   
  +Bar
    -Bar.h
    -Helper.h   
  +Helper
    -Helper.h

Foo and Bar are the libraries I created. The reasoning behind putting Helper.h in their folders is that, end user will have an easier time getting the libraries to work. Also, some libraries can only be configured by having their source code edited.

However, if I write #include <Helper.h> in my sketch, it'll be impossible to control which "Helper.h" I'm including.

Is there a way to hide Helper.h from Foo and Bar from sketches?

Yes, do not add Foo, Bar or Helper to the include path, and include Foo/Helper.h and Bar/Helper.h. Or come up with names better than Helper.h. — juanchopanza
@juanchopanza Helper.h is just a placeholder name, you can think about it as Fat16.h or something like that. Can you elaborate it a bit more and make it into an answer? Bit hard to understand here. — Xun Yang

James Kanze James Kanze · Accepted Answer · 2013-05-02T16:44:50

The obvious answer is: don't write #include <Helper.h>. Your files aren't part of the implementation, and should be included using #include "Helper.h". If you do this, the first place the compiler will look for the include file is in the directory containing the file which is including it: if you include it from Foo/Foo.h, the compiler will pick up Foo/Helper.h; if you include it from Bar/Bar.h, the compiler will pick up Bar/Helper' and so on.

Client code should only set the include path to the root, and do things like #include "Foo/Foo.h"; if necessary, they can also do #include "Foo/Helper.h".

The one thing you do have to do with this strategy is to ensure the uniqueness of all of the header guards. If this is an application, it will usually be sufficient to mangle the path into the include guard, e.g. use Foo_Helper_h, instead of just Foo_h. Alternatively (and I would use this for any library which third parties should use), generate some random string for the include guard. (If I open a file named abc.h which doesn't exist, my editor automatically generates the following boilerplate:

/********************************************************/
/*      File:       abc.h                               */
/*      Author:     J. Kanze                            */
/*      Date:       02/05/2013                          */
/* ---------------------------------------------------- */

#ifndef abc_h_20130502O481MBxFZeAzz4dgIb7iC4Q9
#define abc_h_20130502O481MBxFZeAzz4dgIb7iC4Q9

#endif

It's a safe bet that the include guard here will never conflict with any other. (And you have to do something along these lines anyway, in order to get your copyright message in the file.)

Conflict of include files from an Arduino library

2 Answers