|
|
<?xml version="1.0" encoding="utf-8"?>
<chapter label="2" id="bootstrapping">
<title>Bootstrapping Phase</title>
<highlights>
<para>During this phase, you will create a number of necessary tools:</para>
<itemizedlist>
<listitem><para>You will create a toolchain to use on your host to compile software for your target. This is called a "cross-compilation" toolchain.</para></listitem>
<listitem><para>You will build an essential set of software to bootstrap your target, including a toolchain to use on your target to directly compile software (or <firstterm>self host</firstterm>).</para></listitem>
<listitem><para>You will configure a kernel to boot on your target.</para></listitem>
<listitem><para>You will then create a bootable image that you will use to boot your target into Adélie Linux.</para></listitem>
</itemizedlist>
</highlights>
<section>
<title>Ensuring the musl C library is ported</title>
<para>Before you begin porting Adélie Linux to your target, you must ensure that the musl C library has been ported to it. You can view a list of supported architectures for musl on <ulink url="http://git.musl-libc.org/cgit/musl/tree/arch">the online musl Git repository</ulink>,or in the <filename class="directory">arch/</filename> directory of the musl source code found on the Adélie Linux Platform Group Resource Disc.</para>
<para>If your target is not yet supported by musl, you will need to port it first. Porting the musl C library is beyond the scope of this guide. If you have an Internet connection, you may consult <ulink url="https://wiki.musl-libc.org/porting.html">the official musl porting documentation</ulink>.</para>
</section>
<section>
<title>Creating the cross-compilation toolchain</title>
<para>In this section, you will:</para>
<itemizedlist>
<listitem><para>Add the necessary information to <package>abuild</package>;</para></listitem>
<listitem><para>Install the amended <package>abuild</package> to your host computer;</para></listitem>
<listitem><para>Add your target to <filename>APKBUILD</filename>s for essential software; and</para></listitem>
<listitem><para>Create the initial cross-compilation toolchain, allowing you to build packages for your target.</para></listitem>
</itemizedlist>
<para>Please make sure that you are at your host computer's terminal before continuing.</para>
<section>
<title>Making <package>abuild</package> aware of your target</title>
<para>Before you can build packages for your target, you will need to ensure <package>abuild</package> is aware of the architecture. This is accomplished by modifying a few files in the abuild source code. You will need to check out a clone of the <ulink url="https://code.foxkit.us/adelie/abuild">abuild Git repository</ulink>, or use the copy of the abuild Git tree found on the Adélie Linux Platform Group Resource Disc.</para>
<para>In the abuild Git tree, open the <filename>functions.sh.in</filename> file. Locate the <function>arch_to_hostspec</function> function, and add the short name of your target's architecture as a case to the case statement; it should echo the full build triplet for your target (see <xref linkend="example_arch"/>).</para>
<example id="example_arch"><title>Example addition of PA-RISC to <function>arch_to_hostspec</function></title>
<programlisting>
armhf) echo "armv6-foxkit-linux-muslgnueabihf" ;;
armv7) echo "armv7-foxkit-linux-musleabihf" ;;
<emphasis role="bold">hppa) echo "hppa-foxkit-linux-musl" ;;</emphasis>
i528) echo "pentium4-foxkit-linux-musl" ;;
mips) echo "mips-foxkit-linux-musl" ;;
</programlisting>
</example>
<para>Next, locate the <function>hostspec_to_arch</function> function, and add a string that would match any build triplet for your target's architecture as a case to the case statement; it should echo the short name you specified in <function>arch_to_hostspec</function> (see <xref linkend="example_hostspec"/>).</para>
<example id="example_hostspec"><title>Example addition of PA-RISC to <function>hostspec_to_arch</function></title>
<programlisting>
armv6*-*-*-*eabihf) echo "armhf" ;;
armv7*-*-*-*eabihf) echo "armv7" ;;
<emphasis role="bold">hppa-*-*-*) echo "hppa" ;;</emphasis>
i486-*-*-*) echo "x86" ;;
i586-*-*-*) echo "pmmx" ;;
</programlisting>
</example>
<para>Now that you have added your target to <package>abuild</package>, you will need to create a patch to apply to the <filename>APKBUILD</filename>. Commit your work with a descriptive message (such as <emphasis>"Add the PA-RISC architecture to functions"</emphasis>), then run <userinput>git format-patch HEAD^</userinput> to have Git provide you a patch file. This patch file will typically be named similar to <filename>0001-Add-<replaceable>foo</replaceable>-architecture-to-functions.patch</filename>.</para>
<para>Move (or copy) the patch file you have generated to the directory with <package>abuild</package>'s <filename>APKBUILD</filename>, then add it to the <varname>source</varname> list in the <filename>APKBUILD</filename> and rerun <userinput>abuild checksum</userinput> as with any package update. Build this new copy of <package>abuild</package> locally, and install it to your host computer.</para>
</section>
<section>
<title>Adding your target to essential software build recipes</title>
<para>A few of the essential system software packages for Adélie Linux are customised per target. In this section, you will add support for your target to these packages.</para>
<section>
<title>GCC</title>
<para>Add the appropriate line to <filename>system/gcc/APKBUILD</filename> (the case in build() with default arch/tune etc).</para>
</section>
<section>
<title>musl</title>
<para>Add the appropriate line to <filename>system/musl/APKBUILD</filename> (the ARCH case in package()).</para>
</section>
</section>
</section>
</chapter>
|
