1.5 Library format (rev.2)

[Cristian Maglie]

Hi,

In these days I've revised and simplified the 1.5 library specification. The
specification is in attachment and there are four main changes introduced.

The first change is about IDE behaviour: the previous specification said that
the IDE GUI should hide incompatible libraries from being displayed and
compiled. We've seen that this implies having an "incompatible library
detection" that is not feasible (doing it at "board" or "features" level) or
not accurate enough (doing it at "architecture" level) so, to avoid losing
flexibility in the Arduino IDE, I removed this "IDE behaviour" part to allow
users to do anything without any forced limitation.

The second change is the removal of the "arch" folder: I tried to push it (and
I'm still convinced that is a useful thing to have), but I see too much
reluctance in particular from libraries developers that are also the main
audience this change refers to, so I prefere to give up on that in favor of
preprocessor defines that seems the most established method.

Third change is about library compatibility.
Backward compatibility (using an 1.0 lib on an 1.5 IDE) was already
implemented in the previous specification, but I've added a statement that
explicitly ensure it for the future.
About forward compatibility (using an 1.5 lib on an 1.0 IDE), I've already
removed the "arch" folder, that was one of the problems. The other problem is
the "src" folder and the solution I found is that a library developer may:
- continue to use the 1.0 layout (source code in library's root and "utility"
folders without recursive sub-folder compilation) or
- opt to "upgrade" the library by placing all the source code into the "src"
folder that allows recursive compilation
In the latter case the library will become incompatible with IDEs <=1.0.5. I
can plan a 1.0.6 release that implements compatibility with the src folder so,
overall, the upgraded library will be compatible with, at least, all the
latest releases of the actual stable and beta. This is still not optimal but I
hope to be a good compromise.

The fourth change is about metadata: I removed the "dependency" and "core-
dependency" fields. The are many reasons for that:
- I see no agreement on these metadata (or any alternative set proposed) from
the previous discussion in mailing list
- The presence of these fields are strictly related to the presence of a
"Library Manager" that is not coming in a short while
- I want to discuss them in a separate thread and use the current specification
as a "base" to build on top of that. This will hopefully help to not lose
focus by mixing many problems in a single discussion and to agree to some of
them while discussing the others.

Finally, the plan I have in mind is:

1) review the rev2 specification here
2) extend the Arduino API to reduce the needs for architecture-specific code in
libraries (starting from Paul's wish list for example)
3a) discuss and find an agreement on the metadata to be used in library manager
to define hardware and software dependencies
3b) discuss any eventual metadata not strictly related to the library manager
3c) release a final rev3 specification.

I'm looking forward for your comments, and thanks for reading so far.

C

[Paul Stoffregen]

This looks pretty good. Applying the recursive compile to "src" seems
like a great way to give people the recursive compile they've wanted,
without risking issues with the name existing libraries that have
complex structure.

I do believe it's essential to release 1.0.6 with support for recursive
compiling in the src folder, but relatively few changes from 1.0.5, so
it's a painless upgrade.

The metadata spec still has "architectures=". Is that intentional, or
just leftover material?


I'm somewhat reluctant to bring up any new conversation, but there is
one more meta data item I think will really be needed in the long term:
categories. The really tough part about categories is a centrally
defined list is really needed, where anything other than a recognized
category is considered "other". You might be wondering why we need
categories. For the base install of Arduino, you don't. In fact, I
believe the software should automatically switch from presenting the
libraries list from flat to hierarchical at some point, like perhaps 25
libraries. Of course, the future library manager will have at least
hundreds, perhaps thousands of libraries to present. A well defined
list of about 10 to 15 top-level categories is really needed to tame
these long lists and present them in a way that's easy to understand and
not so overwhelming. I have more thoughts about the category list, but
perhaps this is enough for the moment?

[Cristian Maglie]

Hi Paul,

thanks for the prompt feedback!

> The metadata spec still has "architectures=". Is that intentional, or
> just leftover material?

I'd like to keep the "architectures=" property to show a warning in the IDE
output window in case of compile errors, something like:

"WARNING: The SPI library is declared as being compatible with "avr"
architecture(s), but the currently selected board runs on "sam", this may be
the cause of the error."
(well the text may be adjusted to be more friendly, but you've got the idea)

This message gives a clue to the users that the IDE now supports different
architectures and that a compile error may be due to an incompatible library
rather than an error in the sketch (now I prefere this kind of "verbose"
approach instead of blocking the user without an apparent reason).

Moreover:
1) if the library doesn't specify the metadata we can assume architectures=*
as default.
2) I want to add a preference in platform.txt to override this check,
something like "compatible-architectures=*", or "compatible-architectures=avr"
to override the check on avr only.

> I'm somewhat reluctant to bring up any new conversation, but there is
> one more meta data item I think will really be needed in the long term:
> categories. The really tough part about categories is a centrally
> defined list is really needed, where anything other than a recognized
> category is considered "other". You might be wondering why we need
> categories. For the base install of Arduino, you don't. In fact, I
> believe the software should automatically switch from presenting the
> libraries list from flat to hierarchical at some point, like perhaps 25
> libraries. Of course, the future library manager will have at least
> hundreds, perhaps thousands of libraries to present. A well defined
> list of about 10 to 15 top-level categories is really needed to tame
> these long lists and present them in a way that's easy to understand and
> not so overwhelming. I have more thoughts about the category list, but
> perhaps this is enough for the moment?

The category field seems reasonable to me, probably the GUI will requires a bit
of iterations (for example I personally didn't like to have too many sub
menus) but I can see the value of the "category" field, and I can add it for
the next release. Remains to define the list of categories, do you have already
something in mind?

C

[Visual Micro]

Makes a lot of sense. Thanks

[Matthijs Kooijman]

Hey Christian,

> In these days I've revised and simplified the 1.5 library specification. The
> specification is in attachment and there are four main changes introduced.

Cool! The proposal looks good to me, I hope we covered most of the problems and
goals with this spec. Did you put the proposal up against the goals we
previously discussed to see if it matches all or most of them?

It looks like a good base to implement, while leaving plenty of room for
later incremental improvements and additions (like Paul's categories
proposal).

However, I think the library specification itself can be improved in
terms of structure and terms used. I'd be happy to spend some time on
that somewhere in the coming weeks. Here's a few things I would consider
rewording.

- Perhaps introduce a distinction in normal libraries (e.g., with a
library.properties file) and legacy libraries (without one)?

Using the 'legacy' term emphasizes that new libraries should always
have a library.properties file (since that by itself no longer
prevents < 1.0.6 compatibility).

- We should have proper names for the two source layouts (e.g., flat
layout with utility folder, or recursive layout in the src folder).
I'm not quite sure about this. "legacy" and "normal" might be
confusing with the above, and already calling the new layout "normal"
might be too soon (I also don't want to discourage the flat layout as
much already). Perhaps "flat" and "recursive", or "old" and "new"
(yuck...), or "simple" and "advanced"?

- If we are going to implement support for this format in 1.0.6, then
the "1.5 library format" might not be a good name anymore. Even more,
since the current proposal is essentially a superset of the
"1.0-style" libraries, perhaps the library format doesn't even need a
new name at all? Just call it "the library format" and clearly
describe what will happen (e.g., what defaults to use) when the
library.properties file is missing?

Furthermore, what allows the IDE to choose between the recursive src/
and non-recursive utility/ layout? The easiest is probably to just check
for the existence of a src/ directory and fall back to the old layout if
it's not there. Having an explicit "layout" attribute might be less
error-prone?

I like Paul's idea of adding a category field, we just need to define a
list of categories (but please let's keep discussion about that in that
part of the thread, or perhaps even a separate thread).


Furthermore, I'd propose adding a license field. This is something
that's commonly overlooked by library authors when they just throw out
their library (which technically prevents anyone from distributing
modified or compiled copies of the library). Having a license field
might cause authors to realize they need to put a license on their code,
especially if we add some docs about this. Also, if we ever want a
central distribution system, we need to get the copyright and licensing
clear. Also, this extra field is fairly separate from the rest of the
spec, so I wouldn't mind postponing this and/or separately discussing
it.

> 1) review the rev2 specification here
> 2) extend the Arduino API to reduce the needs for architecture-specific code in
> libraries (starting from Paul's wish list for example)
> 3a) discuss and find an agreement on the metadata to be used in library manager
> to define hardware and software dependencies
> 3b) discuss any eventual metadata not strictly related to the library manager
> 3c) release a final rev3 specification.

I assume that at step 1, you also intend to implement and possibly
already release the specification? Or do you want to wait with that
until step3 (I'd rather not)?


Gr.

Matthijs

[Paul Stoffregen]

On 12/18/2013 05:41 PM, Cristian Maglie wrote:
> Hi Paul,
>
> thanks for the prompt feedback!
>
>> The metadata spec still has "architectures=". Is that intentional, or
>> just leftover material?
> I'd like to keep the "architectures=" property to show a warning in the IDE
> output window in case of compile errors, something like:
>
> "WARNING: The SPI library is declared as being compatible with "avr"
> architecture(s), but the currently selected board runs on "sam", this may be
> the cause of the error."
> (well the text may be adjusted to be more friendly, but you've got the idea)
>
> This message gives a clue to the users that the IDE now supports different
> architectures and that a compile error may be due to an incompatible library
> rather than an error in the sketch (now I prefere this kind of "verbose"
> approach instead of blocking the user without an apparent reason).
>
> Moreover:
> 1) if the library doesn't specify the metadata we can assume architectures=*
> as default.
> 2) I want to add a preference in platform.txt to override this check,
> something like "compatible-architectures=*", or "compatible-architectures=avr"
> to override the check on avr only.

That sounds good. Perhaps this should be added to the specification text?

> The category field seems reasonable to me, probably the GUI will requires a bit
> of iterations (for example I personally didn't like to have too many sub
> menus) but I can see the value of the "category" field, and I can add it for
> the next release. Remains to define the list of categories, do you have already
> something in mind?

Here's an initial list, just to start discussion.

Display
Communication
Signal Input/Output
Sensors
Device Control
Timing
Data Storage
Data Processing
Other
Uncategorized

At some point when the library manager has a comprehensive list of ALL
Arduino libraries, novice users will certainly use it to "shop" or
"browse" for libraries that might be useful for their projects. I
believe the scenario will be pretty similar to shopping for a book,
where many different ones might be good alternatives, but how to do even
begin looking in a huge bookstore?

http://www.barnesandnoble.com/subjects/subjects.asp

Barnes & Noble divides fiction in to 9 broad categories and non-fiction
into, well, many more. I'm not sure their non-fiction categories are
necessarily a great example. I believe overlapping or ambiguous
categories could create a lot of confusion for novices. For example, on
Barnes & Noble's list, I don't understand the difference between
"Religion", "New Age & Spirituality", "Bible Studies" and
"Christianity", but my knowledge on those subjects is limited at best,
much like many novice Arduino users regarding electrical engineering.
Still, I think the overall model of how people shop for books, music,
magazines and other media is useful for designing a library manager, and
for developing broad categories for library metadata.

One important point about categories is a bookstore can't allow every
publisher to define its own uniquely named categories. Obviously that
would results in duplicate and overlapping categories, which could
create more confusion than it helps people to instantly narrow their
search to only 5% to 10% of all the available items.

[Cristian Maglie]

Hi Matthijs!

In data venerdì 20 dicembre 2013 00:15:06, Matthijs Kooijman ha scritto:
> Cool! The proposal looks good to me, I hope we covered most of the problems
> and goals with this spec. Did you put the proposal up against the goals we
> previously discussed to see if it matches all or most of them?

Yes, I've checked the specification with the original goals. As I said, only
the requirements about library dependencies didn't find enough agreement, so
the decision to postpone them for a little while. I can share the updated
requirements but IMHO they have well made their purpose for now, and I prefere
to focus on the specification.

> - Perhaps introduce a distinction in normal libraries (e.g., with a
> library.properties file) and legacy libraries (without one)?
> Using the 'legacy' term emphasizes that new libraries should always
> have a library.properties file (since that by itself no longer
> prevents < 1.0.6 compatibility).

Yeah, why not.

> - We should have proper names for the two source layouts (e.g., flat
> layout with utility folder, or recursive layout in the src folder).
> I'm not quite sure about this. "legacy" and "normal" might be
> confusing with the above, and already calling the new layout "normal"
> might be too soon (I also don't want to discourage the flat layout as
> much already). Perhaps "flat" and "recursive", or "old" and "new"
> (yuck...), or "simple" and "advanced"?

Uhm.. I don't know, maybe flat/recursive, but introducing this terminology is
really needed? probably we can just stick to say library that uses the src
folder and library that don't.

> - If we are going to implement support for this format in 1.0.6, then
> the "1.5 library format" might not be a good name anymore. Even more,
> since the current proposal is essentially a superset of the
> "1.0-style" libraries, perhaps the library format doesn't even need a
> new name at all? Just call it "the library format" and clearly
> describe what will happen (e.g., what defaults to use) when the
> library.properties file is missing?

Right. For now, in a generic library specification, the only thing to explain
clearly is that if you use the src folder then the library will be
incompatible with IDE <1.0.6. This generality will last when the specification
will be extended with the "dependecies" part?

> Furthermore, what allows the IDE to choose between the recursive src/
> and non-recursive utility/ layout? The easiest is probably to just check
> for the existence of a src/ directory and fall back to the old layout if
> it's not there. Having an explicit "layout" attribute might be less
> error-prone?

The idea was to just check for the existence of "src" folder. I meditated to
add a property "layout=" since from a declarative point of view is better to
have something that explicitly states "using layout X", but in the end I
rejected that because just looking to the "src" folder seems enough to safely
discern the two cases and adding a specific property will become an unneeded
redundancy.

> Furthermore, I'd propose adding a license field. This is something
> that's commonly overlooked by library authors when they just throw out
> their library (which technically prevents anyone from distributing
> modified or compiled copies of the library). Having a license field
> might cause authors to realize they need to put a license on their code,
> especially if we add some docs about this. Also, if we ever want a
> central distribution system, we need to get the copyright and licensing
> clear. Also, this extra field is fairly separate from the rest of the
> spec, so I wouldn't mind postponing this and/or separately discussing
> it.

Good point, this is a nice information to have. I guess we should write a list
of licenses in order to group them? I see that debian uses a list of short
names for the most common licenses maybe we can use the same:
http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#license-
short-name

C

[Kristian Sloth Lauszus]

On Sunday, December 22, 2013 8:54:49 PM UTC+1, c.maglie wrote:

> Furthermore, I'd propose adding a license field. This is something
> that's commonly overlooked by library authors when they just throw out
> their library (which technically prevents anyone from distributing
> modified or compiled copies of the library). Having a license field
> might cause authors to realize they need to put a license on their code,
> especially if we add some docs about this. Also, if we ever want a
> central distribution system, we need to get the copyright and licensing
> clear. Also, this extra field is fairly separate from the rest of the
> spec, so I wouldn't mind postponing this and/or separately discussing
> it.

Good point, this is a nice information to have. I guess we should write a list
of licenses in order to group them? I see that debian uses a list of short
names for the most common licenses maybe we can use the same:
http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#license-
short-name

C

You might want to take a look at this site: http://choosealicense.com/.

It might be a bit more user friendly for beginners.

Regards

Lauszus

[Matthijs Kooijman]

Hey Kristian & Christian,

> > > Furthermore, I'd propose adding a license field. This is something
> > > that's commonly overlooked by library authors when they just throw out
> > > their library (which technically prevents anyone from distributing
> > > modified or compiled copies of the library). Having a license field
> > > might cause authors to realize they need to put a license on their code,
> > > especially if we add some docs about this. Also, if we ever want a
> > > central distribution system, we need to get the copyright and licensing
> > > clear. Also, this extra field is fairly separate from the rest of the
> > > spec, so I wouldn't mind postponing this and/or separately discussing
> > > it.
> >
> > Good point, this is a nice information to have. I guess we should
> > write a list of licenses in order to group them? I see that debian
> > uses a list of short names for the most common licenses maybe we can

> > use the same: > > http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/#licenseshort-name
Yes, that sounds good to me. However, let's just refer to the SPDX
license list directly, which Debian also uses: http://spdx.org/licenses/

> You might want to take a look at this site: http://choosealicense.com/.
> It might be a bit more user friendly for beginners.

Oh, that sounds like a good source to refer to.

How about this text for the library spec:

**license** - The license that applies to this library. If the license is
listed in the SPDX list of [licenses][spdx], you should use the short
identifier (e.g., `MIT`, `GPL-3.0`, etc.). For other licenses, use the
full name and version number (if any) of the license, without
abbreviating it.

[spdx]: http://spdx.org/licenses/

If different licenses apply to different parts of the library, they
should all be specified, separated by a comma and a space.

Note that specifying a license here is intended to simplify the
display of library info, but it is not sufficient to actually
apply the license to your code. Be sure to also include the full
text of the license in your library (typically in a file called
LICENSE or LICENSE.txt). Preferably also state the license at
the top of every source file in your library and in the README.


And, in some more detail later on, or perhaps in some other
introductory documentation for library authors:

## Choosing a license
When you write a library and release it for others to use, it is
important to pick a license for it. In most countries, an
author automatically gets copyright over something (like books,
or code) he writes (even without an explicit copyright notice).

Without a license, someone who downloads your code can use and
modify it for themselves, but is not allowed to redistribute
(modified and unchanged versions of) your code, or any compiled
code including your code. Since this is probably not what you
wanted, be sure to always include a license with your code.

For some help in picking one of the common open-source licenses,
see [choosealicense.com][choose].

[choose]: http://choosealicense.com/

Once you picked a license, be sure to:

- Include the full license text in your library, typically in a
file called LICENSE, or LICENSE.txt.
- State the license used in every source file (some licenses
like the GPL or Apache license contain an example of a notice
to use for that, short licenses like the MIT and BSD licenses
are commonly included verbatim in every source file).

Doing this helps to keep track of the origin and license of a
file, when it is used outside of it's original context.
- If you have a README file, also state the applicable license
in there.

How does this sound?

Gr.

Matthijs

[Matthijs Kooijman]

Hey Christian,

> In data venerdì 20 dicembre 2013 00:15:06, Matthijs Kooijman ha scritto:
> > Cool! The proposal looks good to me, I hope we covered most of the problems
> > and goals with this spec. Did you put the proposal up against the goals we
> > previously discussed to see if it matches all or most of them?
>
> Yes, I've checked the specification with the original goals. As I said, only
> the requirements about library dependencies didn't find enough agreement, so
> the decision to postpone them for a little while. I can share the updated
> requirements but IMHO they have well made their purpose for now, and I prefere
> to focus on the specification.

Ok, great!

> > - Perhaps introduce a distinction in normal libraries (e.g., with a
> > library.properties file) and legacy libraries (without one)?
> > Using the 'legacy' term emphasizes that new libraries should always
> > have a library.properties file (since that by itself no longer
> > prevents < 1.0.6 compatibility).
>
> Yeah, why not.

Ok.

> > - We should have proper names for the two source layouts (e.g., flat
> > layout with utility folder, or recursive layout in the src folder).
> > I'm not quite sure about this. "legacy" and "normal" might be
> > confusing with the above, and already calling the new layout "normal"
> > might be too soon (I also don't want to discourage the flat layout as
> > much already). Perhaps "flat" and "recursive", or "old" and "new"
> > (yuck...), or "simple" and "advanced"?
>
> Uhm.. I don't know, maybe flat/recursive, but introducing this terminology is
> really needed? probably we can just stick to say library that uses the src
> folder and library that don't.

"Libraries with src directory" and "libraries without src directory" is
also terminology, albeit a bit verbose terminology :-) I expect that
it's useful to have a short name to refer to these two layouts in the
specification, but perhaps we can just work around that if no better
names pop up.

> > - If we are going to implement support for this format in 1.0.6, then
> > the "1.5 library format" might not be a good name anymore. Even more,
> > since the current proposal is essentially a superset of the
> > "1.0-style" libraries, perhaps the library format doesn't even need a
> > new name at all? Just call it "the library format" and clearly
> > describe what will happen (e.g., what defaults to use) when the
> > library.properties file is missing?
>
> Right. For now, in a generic library specification, the only thing to explain
> clearly is that if you use the src folder then the library will be
> incompatible with IDE <1.0.6. This generality will last when the specification
> will be extended with the "dependecies" part?

I guess so, since users of IDE < 1.0.6 will just have to explicitely
include all the library's dependencies in the main sketch, just like
before.

> > Furthermore, what allows the IDE to choose between the recursive src/
> > and non-recursive utility/ layout? The easiest is probably to just check
> > for the existence of a src/ directory and fall back to the old layout if
> > it's not there. Having an explicit "layout" attribute might be less
> > error-prone?
>
> The idea was to just check for the existence of "src" folder. I meditated to
> add a property "layout=" since from a declarative point of view is better to
> have something that explicitly states "using layout X", but in the end I
> rejected that because just looking to the "src" folder seems enough to safely
> discern the two cases and adding a specific property will become an unneeded
> redundancy.

Sounds good to me.

Gr.

Matthijs

[Cristian Maglie]

Hi,

I've just published an implementation to be reviewed:

https://github.com/arduino/Arduino/pull/1765

The pull request should include all the changes discussed here.

C

[Matthijs Kooijman]

Hey folks,

I still have one more suggestion for the library format, regarding
separation of public and private APIs (.h files). This has been
discussed before, but never actually made it into an actual proposal.
Thinking about this a bit more, it appears to me that this is something
important after all, and also fairly easy to implement.

So, here's what I propose:

- In libraries with a src/ directory, also add an include/ directory.
- Public header files go into include/, source files and private
include files go into (subdirectories of) src/.
- When compiling a library, the include/ directory is put into the
compiler's include path (files in src can still be included using
#include "foo.h" or #include "../foo.h" (for source files in a
subdirectory), since using "" instead of <> allows including relative
to the source file being compiled.
- When compiling a sketch, only the include/ directory of all the
libraries it needs are put on the include path (and automatic library
selection also only looks inside the include/ path).

Doing this allows a library author to clearly separate public API from
private API and minimizes the number files in the include path (which
again minimizes the chance of filename conflicts between two libraries
when one of them offers foo.h as a public API and the other only uses it
internally).

If we want to implement this, we can't wait until a rev3 of the
specifcation, since the change would be backward incompatible (unless we
introduce a third possible library layout, but that would make things
more confusing).


So, how does this sound?

Also, for the third-party tool developers, does this sound easy to
implement (I'd expect so), or will it caue problems?

Gr.

Matthijs

[Rick Anderson]

Standard .h files have a clearly defined private and public portion.

It would be harder for me to figure out what the code does by creating more places to look. I think this would be similar to the issue of code in the utility folder. Try figuring out how the SD library works without looking into that folder. The SD library is also a good example of why you should separate header files into smaller files and hiding files makes it harder to understand.

--Rick

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)

iEYEARECAAYFAlK+jycACgkQz0nQ5oovr7yMIACghuL4mHCgPi4pF3mGc473Uv7u
R7sAnjX20uhNpLvIXPYbJyXvhF9Zeb4P
=fF3o
-----END PGP SIGNATURE-----

--
Co-founder
Fair Use Building and Research (FUBAR) Labs
http://fubarlabs.org

[Cristian Maglie]

Hi Matthijs!

> Doing this allows a library author to clearly separate public API from
> private API and minimizes the number files in the include path (which
> again minimizes the chance of filename conflicts between two libraries
> when one of them offers foo.h as a public API and the other only uses it
> internally).

That's a good point, it sound something very similar to what Jantje was trying
to explain in some discussion going on here and on github.

In data sabato 28 dicembre 2013 09:43:19, Matthijs Kooijman ha scritto:
> So, here's what I propose:
>
> - In libraries with a src/ directory, also add an include/ directory.
> - Public header files go into include/, source files and private
> include files go into (subdirectories of) src/.
> - When compiling a library, the include/ directory is put into the
> compiler's include path (files in src can still be included using
> #include "foo.h" or #include "../foo.h" (for source files in a
> subdirectory), since using "" instead of <> allows including relative
> to the source file being compiled.
> - When compiling a sketch, only the include/ directory of all the
> libraries it needs are put on the include path (and automatic library
> selection also only looks inside the include/ path).

Currently we can achieve something very similar if we put:
- "public" includes in src
- "private" include in a subfolder of src/....
- for library selection the IDE looks only in src and not subfolders

So, despite I really like your proposal to add an "include" folder, I'm not
going to do so, unless there is a very strong response here that agree to do
so, escpecially from 3rd party developers.

Probably a "Guidelines for writing Arduino Libraries" with suggestions on how
to keep the library "clean" is a must-do and I think we can include the very
good text you wrote about how to choose licenses in another post.

C

[Matthijs Kooijman]

> In data sabato 28 dicembre 2013 09:43:19, Matthijs Kooijman ha scritto:
> > So, here's what I propose:
> >
> > - In libraries with a src/ directory, also add an include/ directory.
> > - Public header files go into include/, source files and private
> > include files go into (subdirectories of) src/.
> > - When compiling a library, the include/ directory is put into the
> > compiler's include path (files in src can still be included using
> > #include "foo.h" or #include "../foo.h" (for source files in a
> > subdirectory), since using "" instead of <> allows including relative
> > to the source file being compiled.
> > - When compiling a sketch, only the include/ directory of all the
> > libraries it needs are put on the include path (and automatic library
> > selection also only looks inside the include/ path).
>
>
> Currently we can achieve something very similar if we put:
> - "public" includes in src
> - "private" include in a subfolder of src/....
> - for library selection the IDE looks only in src and not subfolders

Right, that also makes sense. I did think of that already at some point,
but for some reason this didn't appear to me as a sufficient solution
when I wrote my proposal. Looking again now, it seems just fine like
that. Using the separate include folder is slightly cleaner, but also
makes things more complicated.

As an added advantage of "your" approach, you could now even still
access private APIs if you know what you're doing, by explicitely
specifying the subdirectory inthe include (e.g., #include
<subfolder/header.h>)

> So, despite I really like your proposal to add an "include" folder, I'm not
> going to do so, unless there is a very strong response here that agree to do
> so, escpecially from 3rd party developers.

Agreed.

> Probably a "Guidelines for writing Arduino Libraries" with suggestions on how
> to keep the library "clean" is a must-do and I think we can include the very
> good text you wrote about how to choose licenses in another post.

Also makes sense.

Gr.

Matthijs

[Cristian Maglie]

Hi,

In data mercoledì 18 dicembre 2013 16:56:07, Paul Stoffregen ha scritto:
> I do believe it's essential to release 1.0.6 with support for recursive
> compiling in the src folder, but relatively few changes from 1.0.5, so
> it's a painless upgrade.

I've just added the support for recursive compiling in src folder in 1.0.x.
Here the patch:

https://github.com/arduino/Arduino/commit/567240236a614817f32a8dff8c5271f5d07a53f9

I've tested and seems to work as expected. As usual, any test welcome.

C

[gdv]

Hello Matthijs 

Did you have opportunity to have a look to pull request #1808 ?

 

This is an implementation of Library public include files management which allows projects to define their own options

Regards

Gilles

[Ricardo JL Rufino]

Not know if this is the right place to ask.

But is there any configuration to declare the interdependencies of libraries.

Ex :. Ethernet depends of SPI

[c.ma...@bug.st]

Il 24/11/2014 06:26, Ricardo JL Rufino ha scritto:
> But is there any configuration to declare the interdependencies of
> libraries.
> Ex :. Ethernet depends of SPI

Hi Ricardo,

from the latest discussion, there are currently two possible solutions
available:


Solution 1) Using an automatic parser, based on the implementation
started by me on:
https://github.com/arduino/Arduino/pull/1726
and later refined by Matthijs K. on
https://github.com/arduino/Arduino/pull/2174

Shortly: this parser inspects the library source code and extract the
missing headers.
In your example the Ethernet source code is inspected and the header
"SPI.h", #included
in W5100.h AND not found in the build path, is used to automatically add
the missing SPI
library in the build.


Solution 2) Add metadatain library.properties to indicate the libraries
from which the current
library depends upon. The field will be optional, in your example the
Ethernet library will use a line
in library.properties like:

dependencies=SPI


As time passes I'm more and more convinced that the solution 2) is the
right thing to do
since it doesn't make use of complex processing inside the IDE: less
magic less things that may
broke in some weird and unpredictable ways.
Moreover the "metadata" approach is the one used on dependency systems
and it's very
easy to explain and document.

If there are no big concerns I'll go for solution 1) and update the
library specification accordingly.

C

[c.ma...@bug.st]

If there are no big concerns I'll go for solution 1) and update the library specification accordingly.

Err... sorry, I mean solution 2) with the metadata field "dependencies" of course ;-)

C

[Ricardo JL Rufino]

Option 2 (.properties) becomes lighter and can be used by a Library Manager.

However the first option would be interesting to legacy libraries! Maybe run during the "Import Library".

Is there any specification to deal with the versions of the libraries?
For example: SPI 1.0 and SPI 2.0?
Instead of waiting for just the folder name is sufficient...

Ricardo JL Rufino

----------------------------------------------------------------------
CriativaSoft - Desenvolvimento de Sistemas com Qualidade
Analista e Engenheiro de Software

Skype: ricardojlrufino

Linkedin: br.linkedin.com/pub/ricardo-rufino/5a/696/81a

--
You received this message because you are subscribed to the Google Groups "Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to developers+...@arduino.cc.