Initial commit of amd64 pagedocbook

3 files changed, 671 insertions, 0 deletions

diff --git a/content/archs.xmli b/content/archs.xmli
new file mode 100644
index 0000000..4b0d175
--- /dev/null
+++ b/content/archs.xmli
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<chapter xmlns="http://docbook.org/ns/docbook" 
+	xmlns:xl="http://www.w3.org/1999/xlink" 
+	xmlns:xi="http://www.w3.org/2001/XInclude" 
+	xml:id="archs">
+<title>Arch Specific Notes</title>
+
+
+<para>
+This section provides a brief overview of various arch-specific issues. It is not
+complete, and it is not a substitute for discussing any problems with the
+relevant arch team.
+</para>
+
+<note><para>
+People who have worked with some other distributions may find Gentoo's
+views on architecture support slightly unfamiliar. We do not follow Debian's
+attempts to provide a standard set of packages at specific versions and install
+it onto every platform — rather, we simply attempt to provide whatever
+happens to work best in any situation.
+</para></note>
+
+<xi:include parse="xml" href="archs/amd64.xmli" />
+</chapter>
+
+
+
+
+
+
+
+
diff --git a/content/archs/amd64.xmli b/content/archs/amd64.xmli
new file mode 100644
index 0000000..3d7ed28
--- /dev/null
+++ b/content/archs/amd64.xmli
@@ -0,0 +1,637 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<section xmlns="http://docbook.org/ns/docbook" 
+	xmlns:xl="http://www.w3.org/1999/xlink" 
+	xmlns:xi="http://www.w3.org/2001/XInclude" 
+	xml:id="archs.amd64">
+<title>AMD64/EM64T</title>
+
+<section>
+<title>Position Independent Code Issues</title>
+
+
+<para>
+Gentoo Policy demands all shared objects to be compiled with <command>-fPIC</command>
+in <command>CFLAGS</command>. Since this is only a rule, you <emphasis>can</emphasis> break it on some arches.
+You might never notice it. On AMD64, this is a necessity, if shared objects aren't
+built with support for position independent code, the build process bails out
+with an error message like this:
+</para>
+
+<programlisting>
+foo.o: relocation R_X86_64_32 can not be used when making a shared
+object; recompile with -fPIC
+</programlisting>
+</section>
+
+<section>
+<title>How to fix -fPIC issues</title>
+
+
+<para>
+There are several ways to enforce <command>-fPIC</command> on shared objects, each with its
+pros and cons.
+</para>
+
+<section>
+<title xmlns="http://docbook.org/ns/docbook"><command>sed</command>'ing the Makefile</title>
+
+
+<para xmlns="http://docbook.org/ns/docbook">
+Sometimes, a simple <command>sed</command> command is enough to fix it, however, the statements
+normally aren't very readable and may fail when upstream changes the file.
+Please verify that you only change the <command>CFLAGS</command> for <emphasis>shared</emphasis> objects, not for
+the whole package.
+</para>
+
+</section>
+
+<section>
+<title>Patching <command>Makefile.in</command>/<command>configure</command></title>
+
+<para xmlns="http://docbook.org/ns/docbook">
+This is more readable, and easier to send upstream.
+</para>
+
+</section>
+</section>
+<section>
+<title>How <emphasis>not</emphasis> to fix -fPIC issues</title>
+
+
+<para>
+Do <emphasis>not</emphasis> patch the <command>Makefile</command> itself, since it is usually generated by the
+<command>configure</command> script and may vary heavily, so the patch could fail. Also, this
+doesn't help upstream at all.
+</para>
+
+<para>
+Another bad idea is to (ab)use <command>append-flags</command> function from
+<command>flag-o-matic.eclass</command>. Applying <command>-fPIC</command> on all objects should not be
+done.  It should only be applied to shared objects.
+</para>
+
+
+</section>
+
+
+<section>
+<title>Assembler Optimisation</title>
+
+
+<para>
+Modern x86 processors support special instruction sets like <command>mmx</command>, <command>sse</command>,
+<command>SSE2</command> and <command>3DNow!</command>. AMD64 also provides support for them, but in most
+cases, x86 assembler code is incompatible with AMD64 assembler. There are lots
+of packages that provide support through USE flags for these instruction sets.
+Originally, the USE flags were introduced to keep support for older processors
+such as the Pentium I that can't handle such code. Currently, all AMD64s support the
+same combination of extended instruction sets, so there is no reason to make 
+use of the mentioned USE flags. That's why these USE flags are hard-masked in 
+all AMD64-profiles. This doesn't mean we don't support the extensions 
+themselves, instead, we hard-enable them. 
+</para>
+
+<para>
+The following USE flags are masked on AMD64:
+</para>
+
+<itemizedlist>
+  <listitem><para>
+    mmx
+  </para></listitem>
+  <listitem><para>
+    mmx2
+  </para></listitem>
+  <listitem><para>
+    sse
+  </para></listitem>
+  <listitem><para>
+    sse2
+  </para></listitem>
+  <listitem><para>
+    3dnow
+  </para></listitem>
+  <listitem><para>
+    3dnowext
+  </para></listitem>
+</itemizedlist>
+
+
+</section>
+
+<section>
+<title>Multilib on AMD64</title>
+
+
+<para>
+The current AMD64 processors are able to natively run 32bit code on a 64bit
+kernel. Therefore, you can run programs compiled for x86 in an amd64 environment.
+However, 32bit applications need to be linked against 32bit libraries. Mixing
+them won't work. For this reason the libraries are sorted, 32bit libraries normally
+go to <command>/lib32</command> respectively <command>/usr/lib32</command>, the 64bit ones normally to <command>/lib64</command> or
+<command>/usr/lib64</command>. In a perfect world, you wouldn't have to read on. Unfortunately,
+that's not the case, and so it's a bit more complicated.
+</para>
+
+<section>
+<title>Multilib-Toolchain</title>
+
+
+<section>
+<title xmlns="http://docbook.org/ns/docbook">GCC</title>
+
+
+<para xmlns="http://docbook.org/ns/docbook">
+To generate 32bit code, we need a multilib-capable GCC. On other architectures,
+this functionality is enabled with the USE flag <command>multilib</command>. This is also true
+for amd64 with the <emphasis>pre</emphasis>-2005.0 profiles. From 2005.0 on, you have to choose
+whether you want multilib support or not by selecting the profile. Choose
+<command>2005.0/no-multilib</command> if you don't want it, all other profiles have the
+<command>multilib</command> USE flag masked, you're forced to it. With these profiles, GCC will
+produce x86-code whenever you add <command>-m32</command> to its command line. Adding <command>-m64</command>
+or omitting any bit-width option will default to producing 64bit code.
+</para>
+
+
+</section>
+
+<section>
+<title>glibc</title>
+
+
+<para xmlns="http://docbook.org/ns/docbook">
+If you've chosen a multilib profile, glibc will be built twice, once 64bit and
+once 32bit. This is because nearly every application links against glibc. 
+To understand how this is done in the ebuild, read
+<xref linkend="archs.amd64.#The ABI Variable"/>.
+</para>
+
+
+</section>
+
+</section>
+
+<section>
+<title>The <command>emul-linux-x86-*</command> packages</title>
+
+
+<para>
+As you read above, 32bit applications must be linked against 32bit libraries.
+For that, we've put together the most used libraries and stuck them into the
+so-called <command>emul-linux-x86</command> packages, which are located in the
+<command>app-emulation</command> category.
+</para>
+
+<table>
+  <title>Emul-* Libraries</title><tgroup cols="2"><tbody>
+   <row><entry> emul-linux-x86-baselibs</entry>
+	<entry>Contains very basic libraries like zlib, pam, ncurses.</entry>
+  </row>
+  <row><entry>emul-linux-x86-compat</entry>
+	<entry>Contains very old libraries for compatibility with binary-only programs.</entry>
+  </row>
+  <row><entry>emul-linux-x86-glibc</entry>
+  	<entry>Only used for compatibility reasons. This package is blocked by all 2005.0 profiles.</entry>
+  </row>
+  <row><entry>emul-linux-x86-gtklibs</entry>
+       <entry>The name says it — GTK and its engines belong herein.</entry>
+  </row>
+  <row><entry>emul-linux-x86-nvidia</entry>
+       <entry>Obsolete, <command>media-video/nvidia-glx</command> includes the 32bit library.</entry>
+  </row>
+  <row><entry>emul-linux-x86-qtlibs</entry>
+      	<entry>QT goes here.</entry>
+  </row>
+  <row><entry>emul-linux-x86-sdl</entry>
+       <entry>libsdl and friends are here.</entry>
+  </row>
+  <row><entry>emul-linux-soundlibs</entry>
+       <entry>alsa, libogg, just everything that is needed to get sound is located here.</entry>
+  </row>
+  <row><entry>emul-linux-x86-xlibs</entry>
+       <entry>Contains the basic X libraries.</entry>
+  </row>
+  </tbody></tgroup></table>
+<para>
+These packages only provide pre-compiled libraries. Currently, the
+archives are assembled manually, which is the main reason to keep the packages
+as tidy as possible. Do not include libraries that aren't commonly used.
+</para>
+
+<note><para>
+  The emul-packages might conflict with their native images, but only in
+  uncritical locations like <command>/usr/share</command> which are arch-independent anyway.
+</para></note>
+
+
+</section>
+
+<section>
+<title><command>Libdir</command> Links</title>
+
+
+<para>
+Currently, we provide several profiles, each with its own combination of <command>libdir</command>
+configurations.
+</para>
+
+<table><title> ... </title><tgroup cols="4"><thead><row>
+    <entry>
+      Profile
+    </entry>
+    <entry>
+      lib32
+    </entry>
+    <entry>
+      lib
+    </entry>
+    <entry>
+      lib64
+    </entry>
+  </row></thead><tbody><row>
+    <entry>
+      2004.3
+    </entry>
+    <entry>
+      *l-&gt;emul*
+    </entry>
+    <entry>
+      d64
+    </entry>
+    <entry>
+      *l-&gt;lib*
+    </entry>
+  </row><row>
+    <entry>
+      2004.3/lib64
+    </entry>
+    <entry>
+      *l-&gt;emul*
+    </entry>
+    <entry>
+      *l-&gt;64*
+    </entry>
+    <entry>
+      d64
+    </entry>
+  </row><row>
+    <entry>
+      &gt;=2005.0
+    </entry>
+    <entry>
+      d32
+    </entry>
+    <entry>
+      *l-&gt;64*
+    </entry>
+    <entry>
+      d64
+    </entry>
+  </row><row>
+    <entry>
+      &gt;=2005.0/no-multilib
+    </entry>
+    <entry>
+      d32
+    </entry>
+    <entry>
+      *l-&gt;64*
+    </entry>
+    <entry>
+      d64
+    </entry>
+  </row><row>
+    <entry>
+      &gt;=2005.0/no-symlink
+    </entry>
+    <entry>
+      d32
+    </entry>
+    <entry>
+      d
+    </entry>
+    <entry>
+      d64
+    </entry>
+  </row><row>
+    <entry>
+      &gt;=2005.0/no-symlink/no-lib32
+    </entry>
+    <entry>
+      inexistant
+    </entry>
+    <entry>
+      d32
+    </entry>
+    <entry>
+      d64
+    </entry>
+  </row></tbody></tgroup></table>
+
+<para>
+<emphasis>d</emphasis>: Directory containing mixed-bit objects
+<emphasis>dXX</emphasis>: Directory containing XXbit objects
+<emphasis>l-&gt;foo</emphasis>: Link to foo
+</para>
+
+<para>
+To always get the right path, you should use the function <command>$(get_libdir)</command> from
+<command>multilib.eclass</command>. It will always return the correct directory, on all arches.
+And of course it also takes care of the <command>ABI</command> variable.
+</para>
+
+
+</section>
+
+<section>
+<title>The <command>multilib-strict</command> Feature</title>
+
+
+<para>
+Many Makefiles assume that their libraries should go to <command>/usr/lib</command>, or
+<command>$(prefix)/lib</command>. This assumption can cause a serious mess if <command>/usr/lib</command>
+isn't a symlink to <command>/usr/lib64</command>. To find the bad packages, we have a portage feature
+called <emphasis>multilib-strict</emphasis>. It will prevent emerge from putting 64bit libraries
+into anything other than <command>(/usr)/lib64</command>.
+</para>
+
+<para>
+<command>multilib-strict</command> currently doesn't check perl5, gcc, gcc-lib and eclipse-3,
+this behaviour is controlled by the <command>MULTILIB_STRICT_EXEMPT</command> variable in
+<command>make.profile</command>.
+</para>
+
+<section>
+<title>How to fix ebuilds properly</title>
+
+
+<para xmlns="http://docbook.org/ns/docbook">
+In most cases, it's sufficient to use the <command>$(get_libdir)</command> function from
+<command>multilib.eclass</command>:
+</para>
+
+<programlisting xmlns="http://docbook.org/ns/docbook" language="ebuild">
+inherit multilib
+
+src_compile() {
+    econf \
+        --libdir=/usr/$(get_libdir)
+
+    emake || die
+}
+
+src_install() {
+    emake DESTDIR="${D}" install || die
+}
+</programlisting>
+
+<para xmlns="http://docbook.org/ns/docbook">
+Some packages provide really bad Makefiles which hard-code <command>/usr/lib</command>. Those
+should be <command>sed</command> -ed or patched. Don't forget to let upstream know about your
+modifications!
+</para>
+
+
+</section>
+
+
+</section>
+
+<section>
+<title>Headers and Multilib</title>
+
+
+<para>
+Most C/C++ programs need standard header files like <command>types.h</command>. Some of them
+depend on architecture specific facts, e.g. <command>types.h</command> on the length
+of machine words. To ensure that we can compile both 32bit and 64bit
+applications and libraries, we treat <command>/usr/include/asm</command> a bit special.
+</para>
+
+<para>
+This is what <command>/usr/include/asm/types.h</command> looks like on a AMD64 box:
+</para>
+
+<programlisting language="c">
+/* Common header file autogenerated by create_ml_includes in multilib.eclass */
+#ifdef __i386__
+#include &lt;asm-i386/types.h&gt;
+#endif /* __i386__ */
+
+#ifdef __x86_64__
+#include &lt;asm-x86_64/types.h&gt;
+#endif /* __x86_64__ */
+</programlisting>
+
+<para>
+As you can see, this is just a wrapper that decides which file you need
+depending on the the parameter <command>-D</command> given to gcc. You'll probably run into
+some troubles if you try to compile something by hand and forget to append
+<command>-D__x86_64__</command> to your <command>CFLAGS</command>. Of course, this is <emphasis>not necessary</emphasis> when
+using portage. For an explanation, see the <xref linkend="archs.amd64.#The ABI Variable"/>
+section.
+</para>
+
+
+</section>
+
+<section>
+<title>The ABI Variable</title>
+
+
+<para>
+Whenever portage builds something on amd64, it has to decide whether it should
+be 32bit or 64bit. As stated in <xref linkend="archs.amd64.#Headers and Multilib"/>
+the <command>__i386__</command> or <command>__x86_64__</command> respectively, is needed in <command>CDEFINE</command>.
+Also, gcc has to know what code it should produce, therefore <command>-m32</command> or <command>-m64</command>
+must be appended to CFLAGS. This is done via <command>profile.bashrc</command>. All you need to do
+if you want to build a package 32bit is to set <command>ABI=x86</command>.
+</para>
+
+<para>
+The details are shown in <command>make.defaults</command>:
+</para>
+
+<programlisting language="ebuild">
+MULTILIB_ABIS="x86 amd64"
+DEFAULT_ABI="amd64"
+
+CFLAGS_amd64="-m64"
+LDFLAGS_amd64="-m elf_x86_64"
+CHOST_amd64="x86_64-pc-linux-gnu"
+CDEFINE_amd64="__x86_64__"
+LIBDIR_amd64="lib64"
+
+CFLAGS_x86="-m32 -L/emul/linux/x86/lib -L/emul/linux/x86/usr/lib"
+LDFLAGS_x86="-m elf_i386 -L/emul/linux/x86/lib -L/emul/linux/x86/usr/lib"
+CHOST_x86="i686-pc-linux-gnu"
+CDEFINE_x86="__i386__"
+LIBDIR_x86="lib32"
+</programlisting>
+
+
+</section>
+
+
+</section>
+
+<section>
+<title>Porting Notes</title>
+
+
+<section>
+<title>Machine Word sizes</title>
+
+
+<para>
+On AMD64, some types differ in size from x86:
+</para>
+
+<table><title> ... </title><tgroup cols="3"><thead><row>
+    <entry>
+      Type
+    </entry>
+    <entry>
+      x86 (ILP32)
+    </entry>
+    <entry>
+      amd64 (LP64)
+    </entry>
+  </row></thead><tbody><row>
+    <entry>
+      <command>char</command>
+    </entry>
+    <entry>
+      1 byte
+    </entry>
+    <entry>
+      1 byte
+    </entry>
+  </row><row>
+    <entry>
+      <command>short</command>
+    </entry>
+    <entry>
+      2 bytes
+    </entry>
+    <entry>
+      2 bytes
+    </entry>
+  </row><row>
+    <entry>
+      <command>int</command>
+    </entry>
+    <entry>
+      4 bytes
+    </entry>
+    <entry>
+      4 bytes
+    </entry>
+  </row><row>
+    <entry>
+      <command>long</command>
+    </entry>
+    <entry>
+      <emphasis>4 bytes</emphasis>
+    </entry>
+    <entry>
+      <emphasis>8 bytes</emphasis>
+    </entry>
+  </row><row>
+    <entry>
+      <command>long long</command>
+    </entry>
+    <entry>
+      8 bytes
+    </entry>
+    <entry>
+      8 bytes
+    </entry>
+  </row><row>
+    <entry>
+      <command>pointer</command>
+    </entry>
+    <entry>
+      <emphasis>4 bytes</emphasis>
+    </entry>
+    <entry>
+      <emphasis>8 bytes</emphasis>
+    </entry>
+  </row><row>
+    <entry>
+      <command>float</command>
+    </entry>
+    <entry>
+      4 bytes
+    </entry>
+    <entry>
+      4 bytes
+    </entry>
+  </row><row>
+    <entry>
+      <command>double</command>
+    </entry>
+    <entry>
+      8 bytes
+    </entry>
+    <entry>
+      8 bytes
+    </entry>
+  </row><row>
+    <entry>
+      <command>long double</command>
+    </entry>
+    <entry>
+      16 bytes
+    </entry>
+    <entry>
+      16 bytes
+    </entry>
+  </row></tbody></tgroup></table>
+
+<para>
+If you need an exact amount of space, don't use these types but the <command>uXX</command> and
+<command>sXX</command> ones provided by <command>types.h</command>, where XX is the number of bits you need.
+Switching to a type that is the same on both arches is not suggested since it's
+not a clean solution and might cause problems with other arches.
+</para>
+
+
+</section>
+
+<section>
+<title>Casts</title>
+
+
+<para>
+Many upstream developers assume that the length of a pointer is 4 bytes, which
+can cause problems when programs do casts from <command>void *</command> to <command>int</command> and vice
+versa. With GCC 3.4, this causes warnings, the compilation won't abort. If
+you're lucky, your package works, but it's likely that you encounter
+segmentation faults or strange behaviour. GCC 4.0 refuses to compile such code.
+</para>
+
+
+</section>
+
+
+</section>
+
+<section>
+<title>Other Resources</title>
+
+
+<itemizedlist>
+  <listitem><para>
+    <link xl:href="http://amd64.gentoo.org/">Gentoo/AMD64 Project</link>
+  </para></listitem>
+  <listitem><para>
+    <link xl:href="http://www.gentoo.org/doc/en/gentoo-amd64-faq.xml">Gentoo/Linux AMD64 FAQ</link>
+  </para></listitem>
+  <listitem><para>
+    <link xl:href="http://forums.gentoo.org/viewforum-f-46.html">Gentoo on AMD64 Forum</link>
+  </para></listitem>
+</itemizedlist>
+</section>
+</section>
diff --git a/main.docbook b/main.docbook
index bfeb81b..d6fa2aa 100644
--- a/main.docbook
+++ b/main.docbook
@@ -139,4 +139,5 @@
   <xi:include parse="xml" href="content/eclass-writing.xmli" />
   <xi:include parse="xml" href="content/profiles.xmli" />
   <xi:include parse="xml" href="content/keywording.xmli" />
+  <xi:include parse="xml" href="content/archs.xmli" />
 </book>