readme update: less scary warnings, more up-to-date info

Signed-off-by: Gregory M. Tuner <gmt@be-evil.net>

1 files changed, 94 insertions, 69 deletions

diff --git a/README b/README
index e50cf86..2837d14 100644
--- a/README
+++ b/README
@@ -1,26 +1,53 @@
-WARNING: Don't use this overlay if you value your sanity or your
-gentoo installation!
-
-WARNING: Don't ignore the above warning!
-This is seriously not ready for sane people yet.
-
-"But," you say, "I am batshit /in/sane, and my ~amd64 multilib Gentoo
-currently works far too well.  Pretty please, isn't there some way you
-could seriously fuck it up for me?  Ideally, I'd like to be forced to
-boot from a rescue CD and deploy the disaster-recovery tarballs."
-
-In that case, my friend, you've come to the right place!
-
-Although it may not stay that way, for now this overlay contains mostly
-my work-in-progress attempt to port lots and lots of ebuilds to support
-ABI-expand multilib.  This includes a pretty scary number of overriden
-core eclasses.
-
-Some of this is ready to go upstream.  Most isn't.  Like I said,
-it's a work in progress.
-
-To activate this, you'll need to install the overlay and then
-hack up your /etc/portage/repos.conf like so:
+WARNING: Don't use this overlay if you are not prepared to fix a
+broken gentoo installation!
+
+For now this overlay contains mostly my work-in-progress attempt to
+port lots and lots of ebuilds to support multilib-build.
+
+It's a work in progress and many things are expected to be broken.
+
+It also contains very, very experimental multilib python eclasses.
+These mostly work; however, I have decided to completely reimplement
+them as I've learned the hard way that I should have reversed the
+order of the USE_EXPAND arguments, and some non-PMS-compliant
+devices are utilized in the current multilib python codebase.
+
+The only thing I've had to do for no-multilib python ebuilds and
+eclasses (as of 12.14.31, I believe the only ebuild in the overlay
+with a multilib python dependency is =dev-lang/python-2.7.6-r1)
+is to add the occasional flag hack to support the nonstandard
+python header layout utilized by the multilib python installation.
+
+This was done because the only straightforward alternative was to
+wrap the pyconfig.h header in multilib python, using the built-in
+multilib-build header wrappers.  I've opted not to do that because
+I was finding too many configure scripts that expected to parse out
+constants from pyconfig.h and project them into config.h constants.
+
+This would have been fine if they'd used cpp to do the parsing but
+a several scripts were instead employing far cruder "grep" type
+hacks.  This would result in, at best, an error stating that
+pyconfig.h was invalid, or, at worst, erroneous values getting
+cached by configure which would compile fine but lead to runtime
+crashes later.  The prospect that more of these could be lurking out
+there in unknown places was enough to scare me off from wrapping
+the python headers.  Instead, I have ^-wrapped them.
+
+^-wrapping is an overlay-only extension to the regular multilib-build
+wrapping which simply moves the conflicting headers to a per-ABI
+location but does not generate the wrapper.  This gives us a nice clean
+all-or-nothing situation; if an ebuild depends on pyconfig.h, and
+no automated means of finding it is working (distutils-r1 and
+python-single-r1 eclasses have reasonably effective automated
+means of finding the appropriate headers), then it will crash
+stating that pyconfig.h cannot be found, and appropriate measures
+can be taken at the ebuild level.  Meanwhile, any python ebuild
+that compiles will probably work fine.
+
+To use this overlay, you'll need to install it via layman.  Since I
+implement extensive eclass overrides in here, you absolutely must
+hack up your /etc/portage/repos.conf approximately like so if the
+overlay is active:
 
 --
 [DEFAULT]
@@ -41,69 +68,67 @@ lower than that of "gmt".  Use emerge --info --verbose to ensure that
 portage is ordering your overlays that way you want it to.
 
 Before you even start using this, you should remove it from your
-layman, and get yourself on a multilib amd64 profile, with
-ACCEPT_KEYWORDS="~amd64", sync your portage,
-and get your packages completely consisitent, such that
+active layman overlays or disable it via repos.conf, and ensure the
+following prerequisites are met:
+
+  you are on a multilib profile
+
+  ACCEPT_KEYWORDS="~amd64"
+  
+  you have recently sync'ed portage
 
-  # emerge -DupvN '@world'
+  your packages database is entirely consistent, in the sense that:
 
-and 
+    # emerge -DupvN '@world'
 
-  # emerge --depclean
+  and 
 
-and
+    # emerge --depclean
 
-  # emerge '@preserved-rebuild'
+  and
 
-and
+    # emerge '@preserved-rebuild'
 
-  # revdep-rebuild
+  and
 
-all say there's nothing to do.
+    # revdep-rebuild
 
-Now that you're ready to break everything, you'll want to add my overlay
-back in, make the aformentioned changes to /etc/portage/repos.conf, and
-have the following in /etc/portage/make.conf (not precisely -- you'll want
-these in addition to whatever other stuff belongs there):
+  all say there's nothing to do.
+
+Now that everything is running smoothly you're ready to break everything!
+
+:)
+
+add the gmt overlay back in, make the aformentioned changes to
+/etc/portage/repos.conf, and have the following in /etc/portage/make.conf
+(not precisely -- you'll want these in addition to whatever other stuff belongs there):
 
 --
 USE_PYTHON="2.7"
 PYTHON_TARGETS="python2_7"
-PYTHON_MULTILIB_TARGETS_PYTHON2_7_X86="32 64"
-PYTHON_SINGLE_TARGET="python2_7"
-PYTHON_MULTILIB_SINGLE_TARGETS_PYTHON2_7_X86="32 64"
-ABI_X86="64 32" # I put have x32 in here and elsewhere too but had to re-bootstrap glibc to make it work... gl!
+ABI_X86="64 32"
 --
 
-then run 'eselect profile set "gmt:default/linux/amd64/13.0/developer/multilibpython"'
+If you happen to have a triple-multilib toolchain you can use it, it should work fine
+(as fine as x32 gets at least, which on current ~amd64 means you'll need to mask
+any recent mesa libraries).
 
-Now you will find that you are fucked.  Congratulations!
-
-Portage will almost always complain that something is wrong no matter what
-you try to do.  That's because, as I mentioned a couple times, this is a
-work in progress.
-
-But, if you start at the bottom of your dependency tree, and slowly work
-your way up, you might be able to get some stuff working again.  Over time,
-with any luck, things will become less fucked as I continue my work.
+then run 'eselect profile set "gmt:default/linux/amd64/13.0/developer/multilibpython"'
 
-Notes:
+One that's done, try emerging some stuff.  If you jump straight into emerge -e '@world',
+you might get lucky but probably not.  Portage will find circular dependencies or
+won't be willing to backtrack far enough to find a solution to the conflicts you've
+created and will give you an eyeful of garbage.
 
-If you are migrating from a normal multilib system to an ABI_X86-based system with
-this overlay, you're going to get caught in an circular-dependencies mess regarding
-gobject-introspection, dbus, glib, pango, and cairo.  My only advice, for now,
-is to keep fiddling around and forcing things to build with "USE=-blah ebuild" until that
-little gordian-dependency-knot unravels.  Once that occurs, you'll still have
-an inconsistent package database but you'll be able to go much further with things.
+It's probably better to start off getting @system re-emerged (without "--deep"),
+and then gradually resolving whatever madness ensues.
 
-If you are bootstrapping in to a triple-multilib environment with x32 as well,
-you'll need to hack on glibc to bootstrap the multilib process.  The trick
-is to bootstrap with crossdev and wedge your crossdev compiler into the
-glibc Makefiles after the ebuild crashes, and then restart... well it took a few
-more tricks than that actually... but that will get you started.
+If you start at the bottom of your dependency tree, and slowly work
+your way up, will be able to get most stuff working again.  As of this
+writing, I have a perfectly consistent package database as defined above using
+this overlay.  That may not be possible for you, without adjusting some
+use flags.  I've done my best to try various combinations of flags, but it
+would be a practical impossibility for me to try the bazillions of permutations
+possible, and certain flags (i.e.: ldap), I'm just haven't had the chance to
+dink around with yet.
 
-You will probably have lots of collisions until you emerge the version of
-app-emulation/emul-linux-x86-baselibs from my overlay.  Either force them or
-emerge app-emulation/emul-linux-x86-baselibs first.  The way I did it was
-simply to remove app-emulation/emul-linux-x86-* entirely, and rely on '@preserved-rebuild'
-to pick up the slack.