Can Someone Explain the Logic Used in Finding Libraries in SketchFolder/src/

Since, I think, somewhere around v1.6, the Arduino build process has supported finding libraries down in the "src" subdirectory of the sketch folder. But the logic used to find things down there eludes me. Every time I try to take advantage of this feature, I end up spending time moving things around, changing paths, etc. struggling to get it to work as required.

So, can anyone explain the logic actually used to FIND things down that path, and how the #include paths should be set, both in the sketch, and in the libraries in that folder? It seems not at all straight-forward or obvious...

Regards,
Ray L.

Let's say your sketch folder structure looks like this:

FooSketch
|_FooSketch.ino
|_src
   |_FooLib
      |_FooLib.h
      |_FooLib.cpp

You would include FooLib.h in your sketch like this:

#include "src/FooLib/FooLib.h"

Unfortunately there is a problem in quite a few Arduino libraries. Let's say in FooLib.cpp they put the following line:

#include <FooLib.h>

That's actually incorrect include syntax for that usage but because it normally works it slips through testing. That tells the compiler to search the standard include paths for FooLib.h. If the library was installed in one of the standard library folders, that would work but since you don't have the library in one of those folders you get a file not found error. The solution is to edit FooLib.cpp to use the correct include syntax:

#include "FooLib.h"

which tells the compiler to look in the current folder before searching the standard include paths.

Would I be correct then in assuming that if one library in src includes another library in src, that the first must specify a relative path to the second? i.e. -

#include "../Lib2/Lib2.h"

Regards,
Ray L.

Yes, that's correct, because SketchFolder/src/ folder is not added to the include path. Definitely not an ideal situation when that's necessary but luckily it's a minor modification.