What is an ediff and how it helps overlays

Ebuilds shouldn't have logic or use flags enabled by default.  The goal is to be able to provide the highest level of quality and easily reproduce any problems.  In the past there wasn't an easy way to make a small maintainable variance upon a base ebuild.  As a result overlays and use flags were created.  The complaints most commonly mentioned about overlays is that they are loosely coupled from the main tree and also extraneous to maintain.  With taking a fresh look at the problem we invented something called an "ediff".  The ediff is just a simple -ru patch between two versions of an ebuild.  This extension was simply given so that pkgcore can understand what to do with it when it's side-by-side to an ebuild.  Here's a basic real world example.


OSUNIX main tree is a x86_64 solaris base.

foo package - foo-0.0.1.ebuild

...
src_compile() {
     econf \
        --enable-64 \
        | die "you get the idea"
...


Now we assume that we want to support a new arch i686 and make an overlay for it.  In the overlay we have to disable all the explicit 64bit options that are currently enabled.  It could be the other way around, but this is just one example.

# Gentoo way with lots of if blocks and logic statements

src_compile() {
...
if [ arch == i686 && != arm || other_logic_which_makes_this_harder_to_maintain ]
...

     econf \
        (enable-use 64) \
        | die "you get the idea"

----
# Our main tree example

     econf \
        --enable-64 \
        | die "you get the idea"


# Start to show the benefit of ediff

foo-0.0.1-r1.ebuild
...
src_compile() {
# We could also maybe assume that our --target has changed
# and just leave the --enable-64 out, but verbosity on for
# example purposes
     econf \
        --disable-64 \
        | die "you get the idea"


So now instead of pushing the entirely new ebuild into the overlay we just make an ediff

diff -ru  foo-0.0.1.ebuild foo-0.0.1-r1.ebuild > foo.ediff


--- foo-0.0.1.ebuild  Sat Apr 11 10:04:25 2009
+++ foo-0.0.1-r1.ebuild Sat Apr 11 10:04:20 2009
@@ -1,5 +1,8 @@
  src_compile() {
+# We could also maybe assume that our --target has changed
+# and just leave the --enable-64 out, but verbosity is on for
+# example purposes
      econf \
-       --enable-64 \
+       --disable-64 \
         | die "you get the idea"


Now we have an ediff which is tightly coupled to the main tree.  Now all you have to do is maintain a diff against the main tree.  We've removed the need for both logic and if blocks.  The result is a cleaner main tree and isolated variances.

Author note:  I realize most people are scared of change, but when you see it in real world example it becomes clear.

At the highest level in the past overlays could only "overlay" or override ebuilds in the main tree.  Now we give overlays the power to merge and overlay.  When you start to see and treat the main tree as a codebase instead of a bunch metadata it only seems logical to apply a diff for anything you need to change or maintain.