Re: [avr-libc-dev] dox status and next release

[Joerg Wunsch]

As Theodore A. Roth wrote:

> Here's what I see that still needs to be done (from doc/TODO):
> 
>  - Doxument the following:
>    * introduction

Hmm, your current state of affairs doesn't look all too bad to me.

>    * building and installing tools for win32

No idea, is there anyone around who's willing to share their
experience here (preferably in doxygen form ;-)?

>    * how to pre-program the EEPROM.

That depends from the programmer used.  Brian's avrprog documentation
already explains how it's done there.  Rich's demo project explains
how to create the EEPROM data file (although it's of course empty in
this little project).

>    * merge chapter 3 (startup code discussion) from Rich Neswold's doc.
>      Needs some rewriting to update for newer tools.
>    * interfaces in:
>      + include/math.h
>      + include/avr/crc16.h  ???
>      + include/avr/delay.h  ???
>      + include/avr/ina90.h  ???

I wouldn't really document this except of mentioning that this file is
for compatibility with the IAR compiler.

>      + include/avr/timer.h  ???

Can't we completely remove this file?  Or, move it under a compat/
subdirectory.  This would require people to change their #include
statements to prefix it with "compat/", but so far, that's the only
way i see to get rid of the deprecated interfaces.

>      + include/avr/twi.h (move to examples?)

I think so.  The names used are in no way `official names' (like those
in <avr/io.h>).

>      + include/avr/wdt.h (move to examples?)

This one is basically a complete interface for the watchdog (unlike
avr/timer.h, or avr/twi.h), so i'd rather like to keep it.

>      + include/avr/parity.h (move to examples?)

Useful, but i'm neutral about it.  Wouldn't be too hard to
document. ;-)

>    * gcrt1.S ???

Documentation for this file could be combined with the discussion of
the startup code.

>    * the mechanism behind include/avr/io*.h ???

Mmmaybe.

Since printf() is a frequently requested item, i'd like to see the
upcoming stdio implementation to be included as well.  I'm close to
getting something that can go into CVS within the next days.  Would
anybody want to test it before committing, or should i just go ahead
and add it to the CVS repo?

> I've also been thinking about the versioning of avr-libc.

Incidentally, i recently also thought we should finally have a 1.0
instead of all the yyyymmdd versions. ;-)

> Make the next release 1.0.0, and cut a 1.0.0 branch. Then all 1.0.x
> changes are strictly bug fixes and possibly new devices, but no changing
> of interfaces nor deleting/moving of files.
> 
> Once that branch is cut, the head becomes 1.1.<date>-cvs. Where date is
> bumped regularly as it is now. Developers can do whatever surgery is
> needed on the head. Once we're ready for another release, it would be
> branch 1.2.0. If changes are drastic enough, bump it to 2.0.0.

I'd suggest to just avoid the dot-dot releases if possible.
Internally (i. e. in the CVS tag names), use them, but just release
the version as 1.0, along with a branch for it.  If serious bugfix
updates are needed, we can issue 1.0.x releases based on it, but
normally, we'd aim to name the next version 1.1.  In case we really
need to change some API in a way incompatible with previous versions,
this would warrant a major number bump.

I don't think we really need date stamps in branch versions, although
i wouldn't object to them.

> If our branches some what coincide with gcc branches, then we can
> say use avr-libc-1.0.x with gcc-3.3.x, avr-libc-1.2.x with
> gcc-3.4.x, etc. This would also allow for more drastic changes in
> binutils/gcc since we can track them more easily without disturbing
> the users.

I think it's too much of work to try to coordinate this.  The only
reason would be to support new devices, but in that case, binutils
need to be the first, followed by a new gcc version, then avr-libc can
support it, too.  Other changes that only affect avr-libc (like adding
new interfaces) are unrelated to the underlying tools however, so i
don't see why we need to correlate them.

> A down side I see is for package maintainers. E.g. how does rpm know
> that 1.0.0 is newer than 20021015? If this is a huge problem, we
> could just rename the distributiion to navr-libc (n for new). But
> I'm not too keen on that. How does debian/freebsd handle stuff like
> this?

FreeBSD doesn't.  Versions using a date stamp is something i'd
consider to be a `development version' where people are eventually
required to force their tools update manually once the officially
released version is available.  I wouldn't even have started to
provide FreeBSD ports/packages for them if it weren't the increasing
gap between the last officially released version and the development
branch (like support for the ATmega128) had warranted it.

> The major win is for the users.

Indeed.

-- 
J"org Wunsch                                           Unix support engineer
address@hidden        http://www.interface-systems.de/~j/