It would greatly benefit library developers if libraries could specify additions to the include path used in their compilation. Developers could then create work that is much easier to maintain.

Problem

In my personal use case I would like to write both a portable C driver for a device (that can be used on other platforms and with minimal overhead) and an Arduino wrapper for that interface that makes it simple to use for beginners. For the purpose of illustration it would be best to think of the portable driver as immutable source code obtained from a third-party. For maintainability the third-party code would be included 'symbolically' (e.g. git submodule). A representative library structure might be:

libraries/Servo/library.properties libraries/Servo/keywords.txt libraries/Servo/src libraries/Servo/src/Servo.h # this is the Arduino wrapper interface libraries/Servo/src/Servo.c libraries/Servo/src/open-source-servo-driver-lib/include/ossdl.h # this is the portable open-source interface libraries/Servo/src/open-source-servo-driver-lib/src/ossdl.c

The file ossdl.c will most likely include the open-source portable interface with a line such as: #include "ossdl.h" -- unfortunately this will not work in Arduino 1.8.10

The workaround(s) is(are) not great:

• Maintain a Copy of OSSDL: Increases mainenance workload, detracts from open-source spirit (collaborating on original source rather than forking and never coming back)
• Use Relative Paths in OSSDL.c:#include "open-source-servo-driver-lib/include/ossdl.h" inexplicably associates the OSSDL project with Arduino build requirements
• Roll OSSDL into Arduino Library (If you are the maintainer of OSSDL) Same issues as maintaining a new copy, and if you abandon the standalone copy then other potential users have to work around additional code (the Arduino implementation)

Proposed Solution

I suggest that library.properties gains a new comma-separated field of extensions to the library's include path (relative to Servo/src). If not present (as in the case of existing libraries) only Servo/src will appear in the search path - keeping compatibility with the existing codebase. For the sake of interface protection this is as good as the current technique because users would have to modify library.properties to get access beyond the developer's original intent. Of course if they are modifying the library they don't need this feature to accomplish what they seek.

To fix the example situation from above the developer would add the following entry to his library.properties file:

include=open-source-servo-driver-lib/include 

Of course it would also be valid to use

include=lib1/include,lib2/include,lib2/src 

since commas are not (typically) used in filepaths. If needed another format (or use of escape characters) could be employed.

Other Possible Solutions (thoughts?)

• Linking Precompiled Libraries: Although this may work in some cases it is counter-productive to educational (and open-source) efforts not to mention that users will lose control of compilation options
• Recursive Search for Library Headers: This is the more extreme version of what is proposed - all .h files underneath the src/ directory would be accessible. Concerns of interface preservation/enforcement would be raised.

Related Issues / Feature Requests

arduino/arduino-builder/issues/15 - A long-debated feature in which it is requested to put the Sketch folder on the include path for libraries. This is not the same request because

• It keeps the library developer in control of the API
• Does not add complexity for the typical user