extending the library discovery system to search-through the MAIN-folder of a library

[StefanL38]

Please read the Issues section of the Contributing Rules at the "Contributing" link to the right before submitting an issue report.
In this issue - that was closed - arduino/Arduino#11686

I asked for a solution how to give the user more information about what paths the compiler searched for a library.

I was told quote:

The problem is that there are many paths the library discovery system and compiler search for these files. The very nature of the error is such that there is no way to identify a single one of those locations to use in the error message. If they were all added to the error message it would become an unapproachable wall of cryptic text.

well if the library discovery system is already searching at so many places. I see no argument against including the "main"-folder of a library (the folder one-level-above-src)
The library-discovery-system was guided through the librarys filename to find the subfolder "src" so I estimate it is a breeze to add exact this folder to search through too.

I can really not think of any serious reason why looking in the "one-above-src"-folder should arise any problem.

If anybody wants to do any kind of super-special library-variations that something like this rule

if file library.property and subfolder "src" exists then do not search in the "one-above-src"-folder
makes sense for

She/he knows all the compiler-options very well so that She/he could modify what file ever to make this super-special situation work.

This rule is just creating a trap to fall in. But nothing else.
best regards Stefan

[matthijskooijman]

One reason to not also search the main directory, is to limit the number of include paths. Adding more search paths increases the chances that thing will behave surprisingly, i.e. you will be trying to include one file in some library, but end up including another file that happens to have the same name somehow.

Another way to look a this is that it is desirable to keep the number of files and directories exposed through the include path as small as possible, to minimize the chance of collisions (including the wrong file). For libraries, the layout that should be used has a src folder that collects all source and header files, leaving the rest of the library directory free for other things (examples, documentation, etc.), ensuring those other things do not pollute the include path.

You probably have seen that libraries can also omit the src subdirectory and library.properties file, in which case the main library directory is put on the include path. However, this is really only for compatibility with older libraries that were made for Arduino 1.0.x. All new libraries should use the new layout with a src folder.

From reading both your reports, I get the impression that a large part of the problem is that you were surprised by how the include path is applied? Maybe you expected the main folder to end up on the include path but it didn't? Or maybe you started without a src folder and then things broke down when you did? I wonder if better documentation could have helped here? If you look back at the documentation you might have read along the way, can you identify any places where this could have been better documented?

I also wonder if we should add a warning during the build when using a library with a legacy layout (i.e. no src folder)? The only reason to still do this is for compatibility with Arduino 1.0.x, but given that 1.5 was released in 2012, I do not think this is really something that library authors need to worry about. Maybe it would be good to start deprecating this old library layout, with a warning as a first step? @per1234, what would you think about that?

[per1234]

Maybe it would be good to start deprecating this old library layout, with a warning as a first step?

I am against the warning. The reason is that when Arduino took this approach in the past it caused a huge amount of confusion for the users. You are punishing the users for something that is completely out of their control. The very libraries that have the flat layout are also the ones most likely to be unmaintained, meaning that even if the users submit issues or PRs to update the layout the author might just ignore it. Beginners don't understand the difference between a warning and an error. They don't know anything about this subject. Their code is not behaving as expected for a completely different reason and the warning acts as a "red herring".

A better approach to deprecation is via the specification and via Arduino Lint.

[umbynos]

Unfortunately, this in our opinion would be a big breaking change and we don't see any advantage in implementing this approach.