Revamp Config Strategy

[ImpulseAdventure]

One of my main priorities in making GUIslice easier to use is in simplifying the configuration process.

This work is already well under-way, and I believe these changes will enable new users to get up & running faster, and also provide more flexibility for advanced users.

The first major improvement is in creating step-by-step configuration guides specific to a device platform.

Another important change is the introduction of canned example configurations that suit a particular device platform + display + touch controller. For users with shields, it should only be a matter of selecting the appropriate config file, with no additional config edits required for basic operation. From my experience, it is difficult for new users to edit config files when many options and ifdefs exist for unrelated hardware.

I intend to provide a comprehensive table of common shields and displays, with a link to the corresponding example configuration.

Initially, the selected config file would need to be copied over top of the default GUIslice_config_ard/linux.h file. However, the next step will be to change the main GUIslice_config.h to enumerate many of these example configurations -- the user can simply uncomment one of the example configuration lines to use it. No file overwrite is required. Switching between devices is easy. The TFT_eSPI User_Setup_Select.h is an example of this type of approach. Another benefit here is that the custom configurations won't be overwritten when the user updates the GUIslice library.

For advanced users who have a desire to use a single config file (ie. GUIslice_config_ard.h), they can continue to do so by not uncommenting any of the example config lines. In the future, I might explore the removal of the monolithic multi-target GUIslice_config_ard.h, but I'll leave this for later discussion / feedback.

Summary of updates:

• Rewrite Configuration Guides in wiki
  • STATUS: Mostly done though cleanup & more testing is required
• Create Example Configuration files
  • STATUS: Many examples have already been posted to /configs, but many more are pending.
• Create user-select configuration file, avoid need for overwriting files
  • STATUS: Done. Uncomment one line in GUIslice_config.h to select an example config or user config.
• Provide table of common shields and displays, show mapping to Example Config
  • STATUS: Mostly done: table of common displays
• Create local master config that uses meta-language to generate example configs
  • This will enable easy maintenance across all example configurations
  • STATUS: Mostly done. Using jinja2 templating language.
• Revise the automated regression suite Backend: GUIslice platform+display regression suite #65 to use the Example Configs
  • STATUS: Mostly done

[rrroonn]

Hi Calvin,

Just my 2 cents worth.

I am not a fan of modifying files which reside in the libraries folders. It means that the library becomes tied to a specific project (and in this case specific hardware). This means that having more than one ongoing projects using the same library is a real problem.

Some alternative strategies,
(1) the user pulls in some canned code into the top of his project (before calling library headers).
(2) the user copies and renames an appropriate file into his project and then pulls in via

#include "some_config.h"

this can then pull in the headers from the library etc after appropriate #defines etc
(3) I am sure there are others, EG, some use of TEMPLATES might be useful - hmmm

At this point in time, I prefer option (2). Its simple and robust and easy to maintain from a user perspective.

thanks for your hard work.

[ImpulseAdventure]

I completely agree, Ron! Without a doubt I would really like to somehow enable user sketches to dictate the configuration parameterization. I feel this would be very useful for users of libraries like GUIslice that depend on #define settings for conditional compilation.

Unfortunately, I am not yet aware of a suitable way in which the Arduino IDE supports such methodology (like we see in other IDEs). There has been considerable discussion on this topic in arduino-builder Issue 15 and related PRs. Conceptually, it would be convenient if the library could include a config header located within the sketch folder, but I don't see an obvious path to accomplish this.

For (2), the library itself still needs visibility into the config header (now in the sketch folder), but it wasn't clear that there was a portable way for the library to include anything in the sketch folder.

I'm hopeful that there is indeed an easy way to do this but the lengthy discussions I've seen elsewhere (including workarounds involving custom boards.txt, dynamic library instantiation or templating) give me doubts.

That said, I am very open to ideas on this front, and willing to explore any alternate approaches that come to mind, as it is certainly possible that I have missed something obvious :)

---

BTW, as of today, I have now revised the configuration to enable selection of example/user config by uncommenting a single line in src/GUIslice_config.h (which can point to the example configs or a user config located elsewhere). While this still requires modifying a file in the library folder, the edits are greatly minimized compared to the previous methodology.

[ImpulseAdventure]

Completed the majority of the config strategy revision, with some cleanup remaining. I am still open to suggestions if alternate solutions seem more suitable / easier to use.

For reference, I am now building the example configurations from a common config file using the jinja2 templating language. This should help avoid errors and make maintenance much simpler.