Gentoo Archives: gentoo-commits

From: "Friedrich Oslage (bluebird)" <bluebird@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] gentoo commit in xml/htdocs/proj/en/base/sparc: index.xml multilib.xml
Date: Wed, 31 Dec 2008 15:17:36
Message-Id: E1LI2pB-0001Ko-Mn@stork.gentoo.org
bluebird    08/12/31 15:17:33

  Modified:             index.xml
  Added:                multilib.xml
  Log:
  Move multilib migration guide from dev space to normal docs space

Revision  Changes    Path
1.45                 xml/htdocs/proj/en/base/sparc/index.xml

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/base/sparc/index.xml?rev=1.45&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/base/sparc/index.xml?rev=1.45&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/base/sparc/index.xml?r1=1.44&r2=1.45

Index: index.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/base/sparc/index.xml,v
retrieving revision 1.44
retrieving revision 1.45
diff -u -r1.44 -r1.45
--- index.xml	14 Nov 2008 20:58:15 -0000	1.44
+++ index.xml	31 Dec 2008 15:17:33 -0000	1.45
@@ -112,6 +112,9 @@
     <uri link="qla2xxx.xml">How to get QLA2xxx adapters working with kernel
     >=2.6.18</uri>
   </li>
+  <li>
+    <uri link="multilib.xml">Gentoo Linux SPARC Multilib Migration Guide</uri>
+  </li>
 </ul>
 
 <p>



1.1                  xml/htdocs/proj/en/base/sparc/multilib.xml

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/base/sparc/multilib.xml?rev=1.1&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/base/sparc/multilib.xml?rev=1.1&content-type=text/plain

Index: multilib.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/base/sparc/multilib.xml,v 1.1 2008/12/31 15:17:33 bluebird Exp $ -->

<guide link="/doc/en/guide.xml" lang="en">
<title>Gentoo Linux SPARC Multilib Migration Guide</title>

<author title="Author">
  <mail link="bluebird"/>
</author>

<abstract>
This guide will help you to migrate your existing Gentoo Linux SPARC
installation from a non-multilib profile to a multilib profile.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.2</version>
<date>2008-12-30</date>

<chapter>
<title>Overview</title>
<section>
<body>

<p>
This guide will help you to migrate your existing Gentoo Linux SPARC
installation from a non-multilib profile to a multilib profile.
</p>

<impo>
Multilib is still experimental, do not use it if you have to rely on a fully
working machine.
</impo>

<p>
Multlib has advantages but it also has some disadvantages, these are the facts:
</p>

<dl>
  <dt>Advantages</dt>
  <dd>
    <ul>
      <li>You can compile and run 64 bit binaries</li>
      <li>Gcc can handle -m32 and -m64 (biarch)</li>
      <li>One compiler for both kernel and userland</li>
    </ul>
  </dd>
  <dt>Drawbacks</dt>
  <dd>
    <ul>
      <li>Compiling gcc takes twice as long as it did before</li>
      <li>Compiling glibc takes twice as long as it did before</li>
    </ul>
  </dd>
</dl>


</body>
</section>
</chapter>

<chapter>
<title>Preparation</title>
<section>
<title>Unmask required packages</title>
<body>

<p>
The multilib profile requires recent versions of gcc and glibc, to be
exact:
</p>

<ul>
  <li><c>&gt;=sys-devel/gcc-4.3.2-r1</c></li>
  <li><c>&gt;=sys-libs/glibc-2.7</c></li>
</ul>

<p>
Depending on your configuration you may need to add them to
<path>/etc/portage/packages.keywords</path> to avoid holdups.
</p>

</body>
</section>

<section>
<title>Kernel configuration</title>
<body>

<p>
The Linux kernel can be configured to disable 64 bit ELF support and only
enable 32 bit ELF support. Make sure your kernel <e>is not</e> configured like
that and can acually run 64 bit ELF binaries.
</p>

<pre caption="Configuration options">
Executable file formats  ---&gt;
  &lt;*&gt; Kernel support for ELF binaries
</pre>

<p>
Which translated to the <path>.config</path> file would be:
</p>

<pre caption=".config options">
CONFIG_BINFMT_ELF=y
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Migration</title>

<section>
<title>Update the make.profile symlink</title>
<body>

<p>
Because the profile is still in an experimental state you have to create/change
the <path>/etc/make.profile</path> symlink manually.
</p>
<p>
The multilib profile also provides these three sub-profiles for your
convenience, just like 2008.0 does:
</p>

<ul>
  <li>desktop</li>
  <li>developer</li>
  <li>server</li>
</ul>

<pre caption="Update the make.profile symlink">
$ <i>rm /etc/make.profile</i>

$ <i>ln -s /usr/portage/profiles/default/linux/sparc/experimental/multilib /etc/make.profile</i>
or
$ <i>ln -s /usr/portage/profiles/default/linux/sparc/experimental/multilib/desktop /etc/make.profile</i>
or
$ <i>ln -s /usr/portage/profiles/default/linux/sparc/experimental/multilib/developer /etc/make.profile</i>
or
$ <i>ln -s /usr/portage/profiles/default/linux/sparc/experimental/multilib/server /etc/make.profile</i>
</pre>

</body>
</section>

<section>
<title>Rename lib to lib32</title>
<body>

<p>
Though it is not fully compliant with FHS, common practice in Gentoo is to store
32 bit libraries in <e>lib32</e>, 64 bit libraries in <e>lib64</e> and to have
<e>lib</e> as a symlink to the default library directory.
</p>
<p>
The 2008.0 profile stores libraries in <e>lib</e>. These commands will rename
all <e>lib</e> directories to <e>lib32</e> and create a symlink <e>lib</e> to
<e>lib32</e>. Additionally they will create empty <e>lib64</e> directories.
</p>

<warn>
Do not exit your shell while doing this! You would not be able to login again
and would have to boot a livecd to recover.
</warn>

<pre caption="Rename lib to lib32">
$ <i>mv /lib /lib32</i>
# sln is a statically linked version of ln
$ <i>sln lib32 /lib</i>
$ <i>mkdir -p /lib64</i>
$ <i>touch /lib64/.keep</i>
$ <i>for dir in /usr/qt/*/lib /usr/kde/*/lib /usr/local/lib /usr/lib</i>
  <i>do</i>
    <i>if [ -d ${dir} ]</i>
    <i>then</i>
      <i>mv ${dir} ${dir}32</i>
      <i>ln -sf lib32 ${dir}</i>
      <i>mkdir -p ${dir}64</i>
      <i>touch ${dir}64/.keep</i>
    <i>fi</i>
  <i>done</i>
$ <i>ldconfig</i>
</pre>

</body>
</section>

<section>
<title>Remerge baselayout</title>
<body>

<p>
For multilib profiles, <c>sys-apps/baselayout</c> installs additional files,
like <path>/etc/env.d/04multilib</path>. To get these you need to remerge it.
</p>

<pre caption="Remerge baselayout">
$ <i>emerge --oneshot sys-apps/baselayout</i>
$ <i>env-update &amp;&amp; source /etc/profile</i>
</pre>

</body>
</section>

<section>
<title>Install a multilib glibc</title>
<body>

<p>
To compile a multilib glibc you need a biarch gcc but to compile a biarch gcc
you need a multilib glibc. You <e>could</e> compile glibc using a
cross-compiler such as <c>sys-devel/kgcc64</c> but that is not something you
would enjoy...
</p>
<p>
Therefore we will install a binary packages of glibc first and afterwards,
once the migration is complete, remerge it with your USE- and CFLAGS.
</p>

<pre caption="Install binary glibc package">
$ <i>PORTAGE_BINHOST="http://dev.gentoo.org/~bluebird/sparc-multilib/packages" emerge --getbinpkgonly --usepkgonly --oneshot sys-libs/glibc</i>
</pre>

<p>
If you get <e>All ebuilds that could satisfy "sys-libs/glibc" have been
masked.</e> try using a different version of glibc, these three are available
as binary packages:
</p>

<ul>
  <li><c>=sys-libs/glibc-2.7-r2</c></li>
  <li><c>=sys-libs/glibc-2.8_p20080602-r1</c></li>
  <li><c>=sys-libs/glibc-2.9_p20081201-r1</c></li>
</ul>

</body>
</section>

<section>
<title>Install a biarch gcc</title>
<body>

<p>
With a multilib glibc installed you can simply compile a biarch gcc using
portage.
</p>

<pre caption="Install biarch gcc">
$ <i>emerge --oneshot sys-devel/gcc</i>
</pre>

<p>
Now you need to configure your system to use the newly installed gcc using
gcc-config. Replace <e>4.3.2</e> with the version you just installed.
</p>

<pre caption="Set native-compiler">
$ <i>gcc-config sparc-unknown-linux-gnu-4.3.2</i>
$ <i>source /etc/profile</i>
</pre>

</body>
</section>

<section>
<title>Remerge glibc with your preferred settings</title>
<body>

<p>
Remerge glibc with your system specific settings(USE-flags, CFLAGS and such).
</p>

<pre caption="Remerge glibc">
$ <i>emerge --oneshot sys-libs/glibc</i>
</pre>

<p>
If the glibc compilation finishes without any strange error messages it means
that your multilib setup is working. You can use <c>file</c> to verify this by
checking the contents of <path>/lib64</path>.
</p>
<pre caption="Verify multilib glibc installation">
$ <i>file /lib64/libc-*.so</i>
/lib64/libc-2.7.so: ELF 64-bit MSB shared object, SPARC V9, version 1 (SYSV), for GNU/Linux 2.6.9, stripped
</pre>

</body>
</section>

<section>
<title>Unmerge kgcc64</title>
<body>

<p>
<c>sys-devel/gcc</c> can compile the kernel now, therefore you don't need
<c>sys-devel/kgcc64</c> anymore to do it. If you have some scripts that need
it, just replace <e>sparc64-unknown-linux-gnu-gcc</e> with
<e>sparc-unknown-linux-gnu-gcc -m64</e>.
</p>

<pre caption="Unmerge kgcc64">
$ <i>emerge --unmerge sys-devel/kgcc64</i>
</pre>

</body>
</section>

<section>
<title>Remerge world</title>
<body>

<note>
This step is optional.
</note>

<p>
Your system was build with <e>lib</e> as library directory, now it's
<e>lib32</e>. Though you will not notice anything because there is a symlink in
place but if you have a lot of spare cpu time and like your system clean...
</p>
<p>
Or in other words: If you are one of those guys who uses portage's
multilib-strict feature just for the fun of it...this is for you!
</p>

<pre caption="Remerge world">
$ <i>emerge --emptytree world</i>
</pre>

</body>
</section>
</chapter>
<chapter>
<title>Closing-off</title>
<section>
<title>Usage example</title>
<body>

<p>
Here's a simple example how to compile a hello world programm in both 32 and
64 bit.
</p>

<pre caption="Sample hello world program, hello_world.c">
<ident>#include</ident> &lt;<var>stdio.h</var>&gt;
<ident>#include</ident> &lt;<var>stdlib.h</var>&gt;

<stmt>int main(int argc, char** argv)</stmt> {
  <keyword>printf</keyword>("<const>hello, world\n</const>");
  <keyword>return</keyword> <const>EXIT_SUCCESS</const>;
}
</pre>

<pre caption="Compile it as 32 bit binary">
$ <i>sparc-unknown-linux-gnu-gcc -m32 -o hello_world hello_world.c</i>
or
$ <i>sparc-unknown-linux-gnu-gcc -o hello_world hello_world.c</i>
</pre>

<note>
If you specify neigther -m32 nor -m64 the compiler will default to -m32.
</note>

<pre caption="Compile it as 64 bit binary">
$ <i>sparc-unknown-linux-gnu-gcc -m64 -o hello_world hello_world.c</i>
</pre>

</body>
</section>

<section>
<title>Things you shouldn't do</title>
<body>

<p>
So now you have a multlib installation and you are thinking about adding -m64
to CFLAGS in /etc/make.conf and recompiling your entire userland in 64 bit?
PLEASE DO NOT!
</p>

<warn>
<e>Doing this will render your system unusable!</e> Any bugs you report
will just be closed without any further action.
</warn>

<p>
While compiling everything in 64 bit may be a good idea on other 64 bit
architectures, like AMD64, on SPARC it is not. There are good reasons why we
have been using a pure 32 bit userland until now, some of these are:
</p>

<ul>
  <li>32 bit is faster than 64 bit</li>
  <li>32 bit is well tested, 64 bit isn't tested at all</li>
  <li>2039 is still long way off</li>
</ul>

<p>
The only reasons why it <e>might</e> be appropriate to compile an application
in 64 bit are:
</p>

<ul>
  <li>It needs to access more than 4GB of memory. In the real world this only
  applies to huge databases.</li>
  <li>It needs to talk to the kernel directly. Some applications, like
  <c>net-firewall/iptables</c>, contain ugly hacks to support the 64 bit
  kernel/32 bit userland thing.</li>
  <li>It is a kernel.</li>
</ul>

<p>
If you would like to read more about the differences between 32 and 64 bit,
there are dozens of webpages about it on the internet, one of them is
<uri>http://www.superlogic.net/downloads/pub/docs/64bit.htm</uri>.
</p>

</body>
</section>
</chapter>

</guide>