path: root/README

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]
eclass-overrides = gmt
main-repo = gentoo

[gmt]
priority=0
--

if you use this overlay without the eclass overrides, I can confidently
assure you, some horrible shit is going to happen.  If you're gonna
use it, use the eclass override.

If you have a local overlay that you want to take precedent over gmt,
you should put that in your repos.conf, with a "priority" setting
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
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

  your packages database is entirely consistent, in the sense that:

    # emerge -DupvN '@world'

  and 

    # emerge --depclean

  and

    # emerge '@preserved-rebuild'

  and

    # revdep-rebuild

  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"
ABI_X86="64 32"
--

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).

then run 'eselect profile set "gmt:default/linux/amd64/13.0/developer/multilibpython"'

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.

It's probably better to start off getting @system re-emerged (without "--deep"),
and then gradually resolving whatever madness ensues.

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.

A final note: your MULTILIB_ABIS variable must be a superset of your ABI_X86 variable;
otherwise you are writing a check that your toolchain can't cash!  The mapping between
them is:

MULTILIB_ABIS		ABI_X86
=============		=======
amd64			64
x86			32
x32			x32

Another thing to be aware of is that a very significant number of bugs exist in
the upstream code pertaining to crossdev.  Many of these have been worked around
in this overlay, often requiring nontrivial efforts to do so.

But in general, if you have a crossdev toolchain whose ARCH matches the pseudo-ARCH
corresponding to your multilib targets, expect things to be less stable.

The most likely scenario of this nature would be that you are on an ~amd64 profile
and have an i686-pc-linux-gnu crossdev toolchain.  It helps somewhat to tell
binutils-config to generate "fake" targets for x86 by passing it the --x86 argument;
however, this is a half-measure.  Autotools will pick the crossdev toolchain elements
up automatically almost every time.  For things like "ar" this is not a problem and
you will get away with even really drastic things like accidentally using the
crossdev i686-pc-linux-gnu-gcc -- but know that this is wrong and will lead to problems
very frequently.

Specific countermeasures are taken in this overlay to prevent the crossdev pkg-config
wrappers from being chosen by autotools, however, most build systems seem to (almost
desperately) want to use those, and this will lead to utter disaster very frequently
when it happens.  Your best bet is simply to unmerge your i686-pc-linux-gnu crossdev
target once you are confident that your x86_64-pc-linux-gnu toolchain is consistently
doing the right thing with -m32.  After all, technically speaking, at that point,
you really don't need it anymore.

Long story short: keep your crossdev stuff in a prefix or a chroot or something,
unless you like fixing problems!