summaryrefslogblamecommitdiff
path: root/src/porting/2_bootstrapping.xml
blob: d46080bcbed92ebfb42d9a1d177c37ffb7b5382f (plain) (tree)
1
2
3
4
5
6
7
8
9
10


                                      

                                                                                    
                      

                                                                                                                                                                                                                                   

                                                                                                                                             
                       
                 

                                                            

                                                                                                                                                                                                                                                                                                                                                                                                                                                         




                                                               


                                                                                                                           


                                                                                                                                             

                                                                                

                                                                                                                                                                                                                                                                                                                                                                                                                                                             
                                                                                                                          
                




                                                                                         
                 
                      
                                                                                                                                                                                                                                                                                                                                            
                                                                                                                              
                

                                               
                                                                               

                                              
                 
                      

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                  
                                                                                 








                                                                                                                                                                                               
                  

              
<?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>