1.1 --- a/docs/known-issues.txt	Thu Aug 07 22:34:32 2008 +0000
     1.2 +++ b/docs/known-issues.txt	Fri Aug 08 07:07:16 2008 +0000
     1.3 @@ -0,0 +1,59 @@
     1.4 +This files lists the known issues encountered while developping crosstool-NG,
     1.5 +but that could not be addressed before the release.
     1.6 +
     1.7 +The file has one section for each known issue, each section containing four
     1.8 +sub-sections: Symptoms, Explanations, Fix, and Workaround.
     1.9 +
    1.10 +Each section is separated from the others with a lines of at least 4 dashes.
    1.11 +
    1.12 +The following dummy section explains it all.
    1.13 +
    1.14 +    --------------------------------
    1.15 +    Symptoms:
    1.16 +      A one-liner of what you would observe.
    1.17 +
    1.18 +    Explanations:
    1.19 +      An as much as possible in-depth explanations of the context, why it
    1.20 +      happens, what has been investigated so far, and possible orientations
    1.21 +      as how to try to solve this (eg. URLs, code snippets...).
    1.22 +
    1.23 +    Fix:
    1.24 +      What you have to do to fix it, if at all possible.
    1.25 +      The fact that there is a fix, and yet this is a known issue means that
    1.26 +      time to incorporate the fix in crosstool-NG was missing, or planned for
    1.27 +      a future release.
    1.28 +
    1.29 +    Workaround:
    1.30 +      What you can do to fix it *temporarily*, if at all possible.
    1.31 +      A workaround is not a real fix, as it can break other parts of
    1.32 +      crosstool-NG, but at least makes you going in your particular case.
    1.33 +
    1.34 +So now, on for the real issues...
    1.35 +
    1.36 +--------------------------------
    1.37 +Symptoms:
    1.38 +  Seemingly native toolchains do not build.
    1.39 +
    1.40 +Explanations:
    1.41 +  Seemingly native toolchains are toolchains that target the same architecture
    1.42 +  as the one it is built on, and on which it will run, but the machine tuple
    1.43 +  may be different (eg i686 vs. i386, or x86_64-unknown-linux-gnu vs.
    1.44 +  x86_64-pc-linux-gnu).
    1.45 +
    1.46 +  This seems to happen when building glibc-2.7 based toolchains only, for
    1.47 +  x86 and for x86_64.
    1.48 +
    1.49 +  Only the system part of the tuple (here, linux-gnu) needs to be the same to
    1.50 +  trigger the bug.
    1.51 +
    1.52 +  If you really cross-compile (eg x86 -> x86_64, or the other way around),
    1.53 +  the toolchain builds successfully.
    1.54 +
    1.55 +Fix:
    1.56 +  None known.
    1.57 +
    1.58 +Workaround:
    1.59 +  If this happens for you, stick with glibc-2.6.1 for now.
    1.60 +  Or investigate! :-)
    1.61 +
    1.62 +--------------------------------