[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Mandatory -dbg packages for libraries? (and API docs too)

On Sun, 22 Apr 2007 20:39:26 +0100
Neil Williams <codehelp@debian.org> wrote:

After reading the responses so far, the -doc element of my original
idea needs modification.

> I'd like to see all library source packages having a minimum of 4
> binary packages required by Policy: the SONAME, the -dev,  the -dbg
> and a -doc package. (Libraries for perl or other non-compiled
> languages would be exempt from -dbg packages but not -doc.)

The -doc is overkill for all packages but I still feel it is important
for upstream development that all libraries have at least basic API
documentation within Debian, not just somewhere in the Google cache.

I think a -dbg package should be mandatory for all libraries that
can support it, albeit with an introductory period where it is
advisable, recommended then required.

I think that all libraries - without exception - must come with some
API documentation and the docs should be as complete and as accurate
as possible - ideally generated from the source itself. Where such
documentation makes a -doc package worthwhile, that should be done but
a man (3) page in the -dev would be sufficient in some cases. I would
like to see -doc packages - or at least substantive and reliable API
documentation - being the norm for all libraries in Debian. As with the
-dbg, the 'must' could be introduced as a recommendation prior to being

The tools exist for all these changes - only the incentive to use the
tools is needed.

> Things like that make Debian a nicer environment to be upstream, not
> just a nice environment to be a DD or user. I'm upstream for many of
> my Debian packages and I'd like to think that Debian unstable would
> be the distribution of choice for upstream development.

I was using Debian for upstream development long before I even
considered being a DD.

I chose Debian as a development platform for my own reasons and my
decision was "not deemed to be wise" in the eyes of some of my upstream
colleagues. As the newbie to that particular team, I was under
significant pressure to "upgrade to Fedora or SuSE". Debian needs to
reclaim the respect of upstream development teams and part of that is
making it *a lot* easier to do upstream development on Debian without
needing to become a DD as well. Debian is respected as a
distribution for users because of the multiple architecture support and
the patches and bug reports that are forwarded upstream - what is
missing (IMHO) is respect for Debian as the distribution of choice for
upstream development itself.

> Possible policy amendment:
> "Any library source package capable of building with debug information
> (i.e. with -g) must do so. Any such library source package must strip
> the debug symbols into separate objects, provide a binary package
> librarynamesoversion-dbg containing these separate objects
> as /usr/lib/debug/path/to/ELF/object for each /path/to/ELF/object in
> the main library package, and reference these separate objects in
> a .gnu_debuglink section in the corresponding unstripped object."
> (Thanks to Josh Triplett)
> I'd like to add something on -doc to that proposition but haven't
> decided how just yet.

"All library packages must include at least basic API documentation
either in the -dev package or in a dedicated -doc package where
sufficient documentation exists. Wherever possible, documentation
should cover the entire library API, be generated from the source code
of the library and be registered with helper programs like dwww and/or
devhelp etc."

(subject to being introduced as a recommendation prior to being made

What happens now?

Would these changes need a GR?

Would it be sufficient to generate a bug report against Policy?

Or submit these ideas to -policy and take from there?


Neil Williams

Attachment: pgpCdTy35foQ6.pgp
Description: PGP signature

Reply to: