A specification for pkg-config

[Michał Górny]

On Tue, 18 Sep 2012 20:31:45 -0700
Dan Nicholson <dbn.lists at gmail.com> wrote:

> Sorry for the slow reply.
> 
> On Mon, Sep 3, 2012 at 2:11 PM, Michał Górny <mgorny at gentoo.org>
> wrote:
> > Hello,
> >
> > Due to a lack of good documentation in pkg-config, I have decided to
> > write a small specification based mostly on its source code,
> > available documentation and a fair bit of common sense.
> >
> > I think it's fairly complete now, and thus I'd like to get some
> > feedback on it. There were a few things that I was unsure about.
> > I tried to follow the actual behavior but whenever I thought it's
> > not something people should trust, I put an 'implementation-defined'
> > behavior (not sure if it's the most correct way of stating that).
> >
> > The specification also explicitly states what I have omitted now.
> > I'd appreciate an opinion whether the things mentioned there should
> > be added and any comments relevant to them. I'd also like to know
> > if I missed something.
> >
> > Thank you for your patience.
> >
> > The rendered version:
> > http://dev.gentoo.org/~mgorny/pkg-config-spec.html Plain-text
> > version:   http://dev.gentoo.org/~mgorny/pkg-config-spec.txt
> > Project repository:   https://bitbucket.org/mgorny/pkg-config-spec
> 
> I think that's really great that you did that work. I've always wanted
> a formal spec for pkg-config. The best we have is buried in
> pkg-config(1). I'd love to carry a spec in the pkg-config repo and
> publish it on the website. This seems like a great start. There are
> certain bugs that I don't think can be fixed without small extensions
> of the syntax, and without a spec it's difficult to roll those out.
> Now to the specifics.

Now, while we're at the point of extending the syntax, I believe that
authors of the alternative implementations which are in use now should
be allowed to have their part in the discussion about them. At least
pkgconf, which is becoming the official pkg-config implementation
in Gentoo.

> 1. Most of the introduction is complaints about how the reference
> implementation has been designed. I don't think that belongs in a
> specification.

That's mostly a rationale for writing it, and covering all the fields
mentioned in it. But I guess the website shouldn't put dirt on what it
is offering.

> 2. The specification seems to cover both the package file format and
> the implementation. The file format I'm definitely interested in
> specifying, but I'm not so interested in specing the implementation. I
> understand you're trying to create a drop-in replacement for
> pkg-config. I have no issue with that. However, I'm really not
> interested in constraining the reference implementation in a spec. I
> wouldn't want to have to bump a spec if I added a command line switch
> or autoconf macro that someone found useful. I can't speak for Tollef,
> but I'd only be interested in defining the package format and the
> parts of the implementation that are vital to interpreting that
> format. I hope you understand.

I understand you but the problem is that the specification has to cover
all the fields which packages start to rely on. If you remove a switch
or change its behavior, packages may start falling apart. Same goes for
changing autoconf macros (or even worse, with all the magic hidden
beyond m4). And people always rely on more hidden options than they are
supposed to.

But I think that shouldn't be a big problem as long as particular
topics are split clearly. If you see some options which shouldn't be
listed there, feel free to tell and we can discuss the specifics.
If you want, we can even tell you circa which packages rely on which
of the 'less common' options. Well, I probably got too far specifying
'--version' but it's very useful in POSIX shell scripts.

At last, we can decide to split the spec in the 'officially accepted'
and 'extended' part but we'd really like to avoid that. I believe that
such a widely deployed application as pkg-config should be changed with
great care and the spec should cover it all to make it clear what
people can rely on, and what they should not.

Writing a drop-in replacement is one thing, and it is indeed important
that it follows the relied behavior in pkg-config, so that people
choosing the alternative implementation don't hit failures. But it is
even more important that new version of pkg-config itself is
interface-compatible with the previous one, so that people wouldn't
actually hit failures when upgrading.

Sadly, pkg-config was widely deployed before a spec was written,
and I doubt that even with official support we can tell people 'you
shouldn't be using this option for the last 3 years, it's forbidden by
the spec now'.

-- 
Best regards,
Michał Górny
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 316 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/pkg-config/attachments/20120919/25fc7145/attachment.pgp>