Library handling

Proposals for advanced Library Handling:

Use statement '#library Foo' instead of '#include <Foo.h>' to import libraries
Why:
Much easier to comprehend than the include statement.
Users know exactly where they pull in Arduino library code and where avr-libc code is referenced.
The IDE-Preprocessor knows exactly which libaries to include. It can give an early warning
"Library 'FooHoo' not found"
before the compiler chokes on the unsatisfied #include statement and spits out some incomprehensible tech-message

Support a library.properties file
Why:
Two questions come up regulary

  • A) Library X does not work with board Y
  • B) Why can't I import an existing library into my own library

Solution:
A Library Foo can have (optionally) a config-file named Foo.properties. This file is parsed be the IDE every time the Verify/Upload process is started and a Sketch inludes the library.
The File supports (for a start) two entries

#properties for library Foo
depends=Wire
boards=arduino.Mega arduino.Nano xmega.XPlain

The depends entry lists all Libraries that the current Library is build upon and which have to be compiled and linked into to project to make the sketch work.
I our example Library Foo uses the Wire-lib.
There is no need for hacks anymore, like mentioning the Wire-Lib in the Sketch-code even though it is never exlicitly called.

The boards entry lists all the boards that are supported for by the code.
boards.txt should provide a unique key for each board like the examples used above. The arduino. is a kind of namespace-id which will make is possible to write a Library for third party boards.
myXMega.XPlain in the example would be a board from the external myXMega project. The parser supports wildcards arduino.*.

For backward compatibility the existance of such a file is not enforced. If no Foo.properties files exists, the library will be comiled for all boards (no matter if it supports the hardware or not).

A good idea per se, but it will break the (for me) precious c/c++ compatability.

A good idea per se, but it will break the (for me) precious c/c++ compatability.

I what way?
You are not able to replace '#inlude Foo' with '#include <Foo.h>' by hand to restore c/c++ compatability?
Ever tried to run a Sketch Pde file directly through the compiler? It's not valid C++ code anyway.

You are not the intended audicence for this sort of improvement, and I know you will not have any problems translating the Arduino Sketch-code back to plain C/C++.

Like the homepage says:

Arduino is an open-source electronics prototyping platform based on flexible, easy-to-use hardware and software. It's intended for artists, designers, hobbyists, and anyone interested in creating interactive objects or environments.

The C/C++ heritage is not even mentioned on this page.

Eberhard

Agreed on all points. Notice that (for me) clause? It's there to signal that I see how this is valuable for the intended audience. :slight_smile:

I selected Arduino as a hardware prototyping platform because it is C/C++, and I'm sure I'm not alone.

Some more thoughts:

I also thing this will be a problem when the users start to #library in the libraries themselves. Either the IDE need to parse all files for #library, or we need to state that the #library is only allowed in Sketches [that are not libraries].

What would you want? Users that complain about #library not working in their newly created library, or a long recursive preprocess/parse time?

Is it easiest to learn that you always #include other files, or that you #library libraries, but you #include if you write a library.

I also thing this will be a problem when the users start to #library in the libraries themselves.

This will not happen. Did you notice there have never been any forum topics starting with:
Why do I have to write prototypes in library code? I never had to do this with Sketch-code?
I think users are to smart for this. They know they have to learn some C/C++ when they want to start their first Library project.

Either the IDE need to parse all files for #library, or we need to state that the #library is only allowed in Sketches [that are not libraries].
What would you want?

I want the #library statement only in Sketch code because

  • It takes too long to preprocess the included library files in addition to the Sketch code. Thats why I proposed a way out with the library properties-file
  • You get shot by the Kernighan&Ritchie police for even thinking about this.

Is it easiest to learn that you always #include other files, or that you #library libraries, but you #include if you write a library.

Kindergarten is over by the time you decide to write a Library. (In the best sense : You have been playing around for quite a while; now you create code and show to all the world by putting it somewhere on the net. Its you first school-project.)

It is a very strange conception to think that Noobs stay Noobs forever.
That is what I like about the Arduino-documentation
"It starts from Zero and ends up with very advanced topics."
There is no need to protect people from the fact that writing software requires some work.

Eberhard

I could just repeat all you said, and replace the 'why we need a #library' - with 'why we do not need a #library' arguments.

You are right, kindergarden is over.

[edit]It was not my intention to ruin this thread.

I still think the idea is good, but in my opinion the negatives outweigh the positives.[/edit]

Hi All,

(noting that this may not be what the OP meant).

I would like to make a plea for clearer/more transparent handling of "Libraries" ("Classes").

The Arduino build process is a bit of a black box, documented here and there somewhat briefly in the FAQ and scattered through incomplete forum posts. For users coming from, say Processing, or a higher level scripting language that supports OOP, the way Arduino handles custom classes is very confusing and error prone. This makes handling more complex coding projects needlessly difficult and can be an impediment to users working with the Arduino and getting tripped up by the training wheels.

More than a few times I have found myself wrestling with the Arduino build process (rather than the specifics of the project code) because of this lack of transparency and/or info. I've had the feeling that while the Arduino concept is great(!), after you reach a certain experience point or project complexity it often blocks you/gets in the way, without any direction on how to proceed/work around/learn through it. Perhaps it is not part of the Arduino concept to be able to scale easily in this way? If so, that's fair. It might simply be that more info on the distinctions between Wiring and C/C++, on the internals and limitations of the IDE, etc. would address this issue.

You make a good point, and this is also one of the things coming across in the survey responses. It's definitely something to think about and work on.

In the meantime, I wanted to point out this page, which may be useful if you haven't seen it (although it's not really written from a user perspective): Google Code Archive - Long-term storage for Google Code Project Hosting.

Kindergarden is not over if you are simply trying to use a library, not develop one. That is very common, of course.

The process for using libraries that come with the distribution is pretty clear: you select "Import Library" from the Sketch menu and the appropriate #include is inserted into the sketch code for you. When you compile, it finds the library wherever it has been tucked away in the distribution and you're off.

The process is horribly confusing and poorly documented right now if you want to use a contributed library. Where to install the library is explained somewhat murkily, and even what constitutes a library file (is it the .h, .cpp, or something else?) is not clear.

I am thinking of the non-expert programmer user, naturally. At the very least, the current documentation should be expanded:

from: Libraries - Arduino Reference

Contributed Libraries

To install a contributed library, unzip it to the libraries sub-folder of your sketchbook. For details, see the page on the Arduino environment.

and

from: http://arduino.cc/en/Guide/Environment#libraries

Libraries

Libraries provide extra functionality for use in sketches, e.g. working with hardware or manipulating data. To use a library in a sketch, select it from the Sketch > Import Library menu. This will insert one or more #include statements at the top of the sketch and compile the library with your sketch. Because libraries are uploaded to the board with your sketch, they increase the amount of space it takes up. If a sketch no longer needs a library, simply delete its #include statements from the top of your code.

There is a list of libraries in the reference. Some libraries are included with the Arduino software. Others can be downloaded from a variety of sources. To install these third-party libraries, create a directory called libraries within your sketchbook directory. Then unzip the library there. For example, to install the DateTime library, its files should be in the /libraries/DateTime sub-folder of your sketchbook folder.

The addition of a short, clear, step-by-step tutorial for how to use a contributed library in a sketch would be most, most helpful!

.andy

You could possibly do some more with the IDE to make the process easier.

  1. Add an 'install library' menu item or something. A dialog pops up asking you to locate the .zip file containing the library you just downloaded. The IDE then unzips the file, and puts the files in the right place for the system you're on. This may require a standardized library packaging format, but probably nothing terribly difficult.

  2. Maybe promote the 'import library' item from the Sketch menu to its own 'Libraries' menu. Contributed libraries already show up in that menu if they're properly installed. The Libraries menu could hold the install option, and then have options for 'use core library' or 'use contributed library' or something.

I love the idea of a #library in arduino...

Here's my thoughts at random to the above thread...

I like the idea of early checking for libraries... and especially having dependencies in a .properties file... there have been breaking changes to arduino in the past that required me to rewrite libraries, and this might've addressed some of the issues I had...

I think its definitely important to leave the libraries themselves pure c/c++ - this should be a sketch-only precompile. It's made to fix specific confusing issues with using libraries in Arduino, not with including files into the C language.

I think it's a great time to add more library management to the UI as well... install / import library is a good start. Edit library would be another one - using Arduino to edit library files has required a lot of copy and paste with notepad for me in the past...

I love the idea of a #library in arduino...

Thank you, one positive vote at last!

I like the idea of early checking for libraries... and especially having dependencies in a .properties file... there have been breaking changes to arduino in the past that required me to rewrite libraries, and this might've addressed some of the issues I had...

Yes, I wonder why there are so few who people who care about this. This hits me every time I write some library code.
You cannot write the simplest driver library for I²C devices because you cannot make use of the Wire-lib without including it into the users Sketch-code.

Eberhard

Good idea,i love arduino!