source: chapter05/binutils-pass1.xml@ faf3398

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>
<sect1 id="ch-tools-binutils-pass1" role="wrap">
<title>Binutils-&binutils-version; - Pass 1</title>
<?dbhtml filename="binutils-pass1.html"?>

<indexterm zone="ch-tools-binutils-pass1">
<primary sortas="a-Binutils">Binutils</primary>
<secondary>tools, pass 1</secondary></indexterm>

<sect2 role="package"><title/>
<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/binutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/>

<segmentedlist>
<segtitle>&buildtime;</segtitle>
<segtitle>&diskspace;</segtitle>
<seglistitem><seg>1.0 SBU</seg><seg>194 MB</seg></seglistitem>
</segmentedlist>

<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/binutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/>

</sect2>

<sect2 role="installation">
<title>Installation of Binutils</title>

<para>It is important that Binutils be the first package to get compiled,
because both Glibc and GCC perform various tests on the available linker and
assembler to determine which of their own features to enable.</para>

<para>This package is known to behave badly when you change its default
optimization flags (including the <parameter>-march</parameter> and
<parameter>-mcpu</parameter> options). Therefore, if you have defined any
environment variables that override default optimizations, such as CFLAGS and
CXXFLAGS, we recommend un-setting them when building Binutils.</para>

<para>The current version of Binutils in use has a bug that causes strip to
remove necessary information from certain library files.  This patch fixes
the problem:</para>

<screen><userinput>patch -Np1 -i ../binutils-&binutils-version;-fix_strip-1.patch</userinput></screen>

<para>The Binutils documentation recommends building Binutils outside of the
source directory in a dedicated build directory:</para>

<screen><userinput>mkdir ../binutils-build
cd ../binutils-build</userinput></screen>

<note><para>If you want the SBU values listed in the rest of the book to be of
any use, you will have to measure the time it takes to build this package --
from the configuration up to and including the first install. To achieve this
easily, you could wrap the four commands in a <command>time</command> command
like this: <userinput>time { ./configure ... &amp;&amp; ... &amp;&amp; ...
&amp;&amp; make install; }</userinput>.</para></note>

<para>Now prepare Binutils for compilation:</para>

<screen><userinput>../binutils-&binutils-version;/configure --prefix=/tools --disable-nls</userinput></screen>

<para>The meaning of the configure options:</para>

<variablelist>
<varlistentry>
<term><parameter>--prefix=/tools</parameter></term>
<listitem><para>This tells the configure script to prepare to install the Binutils
programs in the <filename class="directory">/tools</filename> directory.</para></listitem>
</varlistentry>

<varlistentry>
<term><parameter>--disable-nls</parameter></term>
<listitem><para>This disables internationalization (a word often shortened to 
i18n). We don't need this for our static programs and <emphasis>nls</emphasis>
often causes problems when linking statically.</para></listitem>
</varlistentry>
</variablelist>

<para>Continue with compiling the package:</para>

<screen><userinput>make configure-host
make LDFLAGS="-all-static"</userinput></screen>

<para>The meaning of the make parameters:</para>

<variablelist>
<varlistentry>
<term><parameter>configure-host</parameter></term>
<listitem><para>This forces all the subdirectories to be configured immediately. 
A statically linked build will fail without it. We therefore use this option to work 
around the problem.</para></listitem>
</varlistentry>

<varlistentry>
<term><parameter>LDFLAGS="-all-static"</parameter></term>
<listitem><para>This tells the linker that all the Binutils programs should be 
linked statically. However, strictly speaking, <parameter>"-all-static"</parameter>
is passed to the <command>libtool</command> program, which then passes
<parameter>"-static"</parameter> to the linker.</para></listitem>
</varlistentry>
</variablelist>

<para>Compilation is complete. Normally we would now run the test suite, but
at this early stage the test suite framework (Tcl, Expect and DejaGNU) is not
yet in place. And there would be little point in running the tests anyhow,
since the programs from this first pass will soon be replaced by those from the
second.</para>

<para>Now install the package:</para>

<screen><userinput>make install</userinput></screen>

<para>Now prepare the linker for the <quote>Adjusting</quote> phase later on:</para>

<screen><userinput>make -C ld clean
make -C ld LDFLAGS="-all-static" LIB_PATH=/tools/lib</userinput></screen>

<para>The meaning of the make parameters:</para>

<variablelist>
<varlistentry>
<term><parameter>-C ld clean</parameter></term>
<listitem><para>This tells the make program to remove all the compiled files 
in the <filename class="directory">ld</filename> subdirectory.</para></listitem>
</varlistentry>

<varlistentry>
<term><parameter>-C ld LDFLAGS="-all-static"
LIB_PATH=/tools/lib</parameter></term>
<listitem><para>This option rebuilds everything in the
<filename class="directory">ld</filename> subdirectory. Specifying the LIB_PATH
makefile variable on the command line allows us to override the default value
and have it point to our temporary tools location. The value of this variable
specifies the linker's default library search path. You will see how this
preparation is used later on in the chapter.</para></listitem>
</varlistentry>
</variablelist>


<warning><para><emphasis>Do not yet remove</emphasis> the Binutils build and
source directories. You will need them again in their current state a bit
further on in this chapter.</para></warning>


</sect2>

<sect2 role="content"><title/>
<para>The details on this package are found in <xref linkend="contents-binutils"/>.</para>
</sect2>

</sect1>