diff options
| -rw-r--r-- | content/archs.xmli | 33 | ||||
| -rw-r--r-- | content/archs/amd64.xmli | 637 | ||||
| -rw-r--r-- | main.docbook | 1 |
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->emul* + </entry> + <entry> + d64 + </entry> + <entry> + *l->lib* + </entry> + </row><row> + <entry> + 2004.3/lib64 + </entry> + <entry> + *l->emul* + </entry> + <entry> + *l->64* + </entry> + <entry> + d64 + </entry> + </row><row> + <entry> + >=2005.0 + </entry> + <entry> + d32 + </entry> + <entry> + *l->64* + </entry> + <entry> + d64 + </entry> + </row><row> + <entry> + >=2005.0/no-multilib + </entry> + <entry> + d32 + </entry> + <entry> + *l->64* + </entry> + <entry> + d64 + </entry> + </row><row> + <entry> + >=2005.0/no-symlink + </entry> + <entry> + d32 + </entry> + <entry> + d + </entry> + <entry> + d64 + </entry> + </row><row> + <entry> + >=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->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 <asm-i386/types.h> +#endif /* __i386__ */ + +#ifdef __x86_64__ +#include <asm-x86_64/types.h> +#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> |