Allow library to include a configuration file located in the project folder

[GDV0]

Writing a generic library that can be fine tuned for several projects seems difficult (impossible) without adding extra code and having a bad impact on th project memory footprint.
The idea is to have a library configuration file located in the project folder to allow this fine tuning.

[matthijskooijman]

I'm not so sure if the proposed fix is a good idea: adding more paths to the include path increases the chances of conflicts (and random unpredictable failures) when a filename is reused.

I could imagine two alternatives:

• Have a config.h file (or similar) that is automatically included when compiling everything (e.g., by passing -include /path/to/sketch/config.h to the compiler)
• Have a config subdirectory inside the sketch folder, which is included in the build path for all libraries. Libraries can then explicitely include some config file from that directory (e.g., SPI_config.h or something like that).

I think I like the first option better, since it's less messy. However, the second option has less magic, which can also be a good idea...

[GDV0]

Your right, it could be an issue, but it can be easily managed!
Today, a higher risk already exists when including several libraries in the same project ( if same #define with different value or meaning is present in several library include files)

These issues could only be fixed by using strong naming rules for filenames, constants and defines. It is the responsibility of the library writer to follow such rules and therefore avoid as much as possible such issue.

Some remarks regarding the 2 alternatives you mentioned

• Have a config.h file …
  I assume you want to have this file in the project folder
  It was my first idea, but the main constraint for the user is to gather all defines from libraries used in his project without going deeper in the library code. Therefore a complete description of these defines must be provided with the library
  It could be done:
  + With a textual file, (pdf, txt, chm, …). User will have to copy all he wants in the Config.h file taking care about typo errors,
  + By copying the content (or part) of a pre-made include file, from the library folder, to config.h file
• Have a config.h subdirectory …
  Main constraint is that sketch subdirectory content is not displayed in Arduino editor and therefore config files are not directly visible for user to modify it

My proposal
For library implementation (e.g. XYZ) with user configurable parts ia as follow

• Add a “Configuration” subdirectory to the library directory (XYZ directory)
• Add a “LibXYZConf.h” file in XYZ\Configuration folder
• Include in this file all constants and defines that can be modified by the user.
  Don’t forget
  + to use naming rules for all items ( e.g. begin all items with LIB_XYZ_)
  + to add comments to all data (supported value ranges, option meanings, …)
• Create library files: XYZ.cpp and XYZ.h
• Add the following line in the XYZ.h file: #include “LibXYZConf.h”

For Library use

• Copy the Library configuration file LibXYZConf.h from XYZ\Configuration folder directly to the sketch folder (1)
• Include, as usual, XYZ.h file in the sketch ino file
  Then opening the project will display and modify both sketch.ino and LibXYZConf.h files

That’s all folks !

(1) Next possible improvement:
Modify “Import library” function to automatically copy Library configuration file if exists to the sketch folder

As I previously said, it is only a proposal that can surely be improved. So feel free to leave comments and suggestions about it.

[matthijskooijman]

Have a config.h file …
I assume you want to have this file in the project folder
Yes, that config.h file would live in the sketch folder.

It was my first idea, but the main constraint for the user is to gather all defines from libraries used in his project without going deeper in the library code. Therefore a complete description of these defines must be provided with the library

I'm not following what the problem here is. If a library offers user-configurable values, it seems that it should properly document them in all cases anyway? Or are you saying that, with your initial suggestion, the library foo author could just provide a foo-config.h file for the user to copy into his sketch directory to modify? If so, as you suggested, you could also just copy-paste the relevant config bits into the main config.h file (if that approach is chosen).

Main constraint is that sketch subdirectory content is not displayed in Arduino editor and therefore config files are not directly visible for user to modify it
That's not really a valid downside - the IDE needs modfications to add the right files to the include path anyway, so it can also be modified to show these files.

Regarding your proposal, it looks good to me. However, I'd still suggest to put the config files into a "Configuration" subdirectory within the sketch directory, to keep things more clear.

Furthermore, were you considering to put the "Configuration" subdirectory of a library in the include path as well? If we'd do that, if the user does not copy the configuration file, the default file from inside the library will be included instead. The alternative is to put the defaults in the main XYZ.h (with #ifndefs for example), but then there's a chance of the real defaults and the ones documented in the libXYZConf.h file becoming different, so I like the first option better.

[GDV0]

OK, I followed your suggestions and some of mine:

• Library configuration files are stored in a Configuration subdirectory in the sketch folder
• This Configuration subdirectory (and not the one from Library filder) is used as include path only when compiling libraries
• Library configuration files are visible and can be modified in Arduino IDE
• importing libraries with configuration files makes the Configuration subdirectory to be created in the sketch folder and all Library configuration file to be copied in it.
  I have done some tests with Save, Save as, Archive and Import functions and have not seen any issue ( for the moment)
  I will continue testing it before pulling the changes