[gentoo-dev] Unified DEPENDENCIES concept

[Ciaran McCreesh]

Since DEPENDENCIES hasn't been written up in a Gentoo-friendly manner,
and since the Exherbo documentation doesn't seem to suffice to explain
the idea here, here's some more details on the DEPENDENCIES proposal.

We observe that a typical package will have something like this:

    DEPEND="
        cat/first
        cat/second
        cat/third
        cat/fourth
        foo? (
            foo/one
            >=foo/two-2.34[monkeys]
        )
        bar? (
             bar/one
        )
        baz? (
             baz/one
             baz/two
        )
        fnord? (
             fnord/one
        )"

    RDEPEND="
        cat/second
        cat/third
        cat/fourth
        cat/fifth
        foo? (
            >=foo/two-2.34[monkeys]
            foo/three
        )
        bar? (
             bar/one
             bar/two
             bar/three
             bar/four
        )"

Note how many dependencies that we think of as being "the same" are
listed in two places, and are not in any way "the same".

Note also how the foo-related things, the bar-related things etc cannot
be grouped together by their fooness or barness, but are rather grouped
by their DEPENDness and RDEPENDness.

Right now we've just got three variables. In a not too distant EAPI, it
will be considerably more than three. We also have duplication; with
HDEPEND, this will sometimes become triplication.

Here's the important bit, which I shall prefix with some stars:

*** The point of DEPENDENCIES is not to replace n variables with one
*** variable.

*** The point of DEPENDENCIES is not to provide syntactic sugar over a
*** group of n variables.

*** The point of DEPENDENCIES is to allow a package's dependencies,
*** which can be very complicated, to be expressed accurately and
*** simply, in a way friendly to how developers deal with dependencies
*** in practice.

So here's what DEPENDENCIES solves:

Firstly, it allows developers to group together foo-related dependencies
and bar-related dependencies by their fooness and barness, not by their
role.

Secondly, it reduces error-prone duplication.

Thirdly, it avoids some fairly obtuse names (BADEPEND? LDEPEND?) in
favour of something a tad more readable.

Here's the other important bit, with more stars:

*** It does it by replacing the concept of "a package has build
*** dependencies, run dependencies, etc" with "a package has
*** dependencies, and each dependency is applicable at one or more of
*** build time, run tme, etc".

We could just mark each dependency individually by when it's
applicable. But that turns out to be quite verbose, since packages have
fairly long lists of dependencies of the same kind. So here's a much
more concise syntax:

    DEPENDENCIES="
        build:
            cat/first
        build+run:
            cat/second
            cat/third
            cat/fourth
        run:
            cat/fifth

        foo? (
            build:
                foo/one
            build+run:
                >=foo/two-2.34[monkeys]
            run:
                foo/three
        )

        bar? (
             build+run:
                 bar/one
             run:
                 bar/two
                 bar/three
                 bar/four
        )

        build:
            baz? (
                 baz/one
                 baz/two
            )

            fnord? (
                 fnord/one
            )"

Here are the rules for working out which labels apply to a given spec:

We have a "labels stack" when parsing. Initially, the value "build+run"
is on the top. Whenever we encounter a block ("( )", "use? ( )" etc),
we duplicate the top value of the stack, and when we leave the block we
pop the value off. Whenever we encounter labels, we replace the top
value on the stack with those labels. Whenever we encounter a spec, its
associated labels are those on the top of the stack.

To avoid weirdness, so long as we're inside a || block, use of labels
is forbidden. Note that this is a reflection of the current ambiguity
as to what DEPEND="|| ( a b )" RDEPEND="|| ( a b )" means (can you
build against a, and run against b?), and if we're wanting to tidy that
up, that should be an independent proposal.

These rules are mostly for flexibility: if developers sometimes prefer
to group things by role rather than by fooness, then that's possible
too.

The rules for eclass merging need changing too, to add a ( ) around
values rather than merely appending. This is a technicality, and isn't
developer visible.

-- 
Ciaran McCreesh