mention some caveats in the README

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

1 files changed, 36 insertions, 0 deletions

diff --git a/README b/README
index 2837d14..d153d4b 100644
--- a/README
+++ b/README
@@ -132,3 +132,39 @@ 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!