Porting: commit the overhaul I started a while back but never finished

1 files changed, 26 insertions, 40 deletions

diff --git a/src/porting/2_bootstrapping.xml b/src/porting/2_bootstrapping.xml
index cf6f278..d46080b 100644
--- a/src/porting/2_bootstrapping.xml
+++ b/src/porting/2_bootstrapping.xml
@@ -1,24 +1,19 @@
 <?xml version="1.0" encoding="utf-8"?>
 <chapter label="2" id="bootstrapping">
     <title>Bootstrapping Phase</title>
-    <para>During this phase, you will create a number of necessary tools:
+    <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 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>
-    </para>
+    </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>
+        <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>
@@ -32,50 +27,41 @@
         <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>
+            <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>
+<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>
+</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>
+            <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>
+<programlisting>
         armv6*-*-*-*eabihf)     echo "armhf" ;;
         armv7*-*-*-*eabihf)     echo "armv7" ;;
-        <emphasis role="bold">        hppa-*-*-*)             echo "hppa" ;;</emphasis>
+        <emphasis role="bold">hppa-*-*-*)             echo "hppa" ;;</emphasis>
         i486-*-*-*)             echo "x86" ;;
         i586-*-*-*)             echo "pmmx" ;;
-                </programlisting>
+</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>
+            <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>
+            <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>