From 0e0321f376491533dbe1114f2d77d359e20356a6 Mon Sep 17 00:00:00 2001
From: "A. Wilcox" <AWilcox@Wilcox-Tech.com>
Date: Fri, 27 Apr 2018 23:24:44 -0500
Subject: Porting Guide: Add more content to chapter 2

---
 src/porting/2_bootstrapping.xml | 62 ++++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 7 deletions(-)

diff --git a/src/porting/2_bootstrapping.xml b/src/porting/2_bootstrapping.xml
index 70e64e0..a842c0b 100644
--- a/src/porting/2_bootstrapping.xml
+++ b/src/porting/2_bootstrapping.xml
@@ -3,12 +3,12 @@
     <title>Bootstrapping Phase</title>
     <para>During this phase, you will create a number of necessary tools:
         <itemizedlist>
-            <listitem><para>You will create a toolchain to use on your host to compile software for the target.
+            <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 the target,
-                    including a toolchain to use on the target to compile software directly on the target.</para></listitem>
-            <listitem><para>You will configure a kernel to boot on the target.</para></listitem>
-            <listitem><para>You will then create a bootable image that you will use to boot the target into Adélie Linux.</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>
     </para>
     <section>
@@ -24,10 +24,58 @@
         <title>Creating the cross-compilation toolchain</title>
         <para>In this section, you will:</para>
         <itemizedlist>
-            <listitem><para>Add the necessary information to <filename>abuild</filename> and <filename>APKBUILD</filename>s for essential software;</para></listitem>
-            <listitem><para>Install the amended <package>abuild</package> to your host computer; and</para></listitem>
+            <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>Add 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>
     </section>
 </chapter>
-- 
cgit v1.2.3-70-g09d2