Porting Guide: Start work on this

7 files changed, 161 insertions, 0 deletions

diff --git a/src/porting/1_intro.xml b/src/porting/1_intro.xml
new file mode 100644
index 0000000..d1b4e80
--- /dev/null
+++ b/src/porting/1_intro.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="1" id="intro">
+    <title>Introduction to Porting</title>
+    <para>Welcome to the Adélie Linux New Port Guide.
+        This guide will provide everything you need to know to bootstrap a new platform to run Adélie Linux.
+        It is organised into three main parts: this Introduction, the Bootstrapping phase, and the Native Hardware phase.</para>
+    <section>
+        <title>Before You Begin</title>
+        <para>There are a few things you need to be aware of before you begin.
+            First of all, bootstrapping a new platform can be difficult at times.  Don't get discouraged if it doesn't work the first time.
+            Build issues and instability are common at the beginning.
+            If you need help, you can ask the maintainers of the software you are building, or you can contact the Adélie Linux Platform Group.
+            They are the group assigned to maintaining cross-platform compatibility and accepting new ports to the main Adélie Linux distribution.</para>
+    </section>
+    <section>
+        <title>Requirements</title>
+        <para>You will need two computers.
+            The first one, which we will term the "host", must be a computer that is already running a Linux;
+            it is recommended that the host is already running Adélie Linux.
+            It will also need a decent CPU and disk,
+            because it will need to compile two full toolchains (compiler and other build tools).</para>
+        <warning>
+            <para>While it is theoretically possible to bootstrap from any POSIX system that supports GCC or Clang,
+                it is unsupported to use a non-Linux environment to bootstrap Adélie.</para>
+        </warning>
+        <para>You may need Internet access on the host to download packages.
+            If you do not have Internet access on the host, you will need to obtain the Adélie Linux Platform Group Resource Disc,
+            which contains the packages and source code you will need to bootstrap your new platform.</para>
+        <para>On the computer you will run Adélie Linux on, which we will term the "target",
+            you will need a computer platform supported by the Linux kernel and one of its compilers (at the time of this writing, GCC or Clang).
+            The Linux kernel, as of version 4.3, supports over 30 CPU architectures, so odds are good that your computer will be supported.
+            Nonetheless, you should still ensure that the Linux kernel and a recent toolchain have been ported and tested on your hardware before proceeding.</para>
+        <para>You will also need a way to boot Linux on the target.  The specifics of this are beyond the scope of this guide.
+            Usually most embedded systems support booting off flash media which is easily obtained and writable by most host computers;
+            they may alternatively support booting from a network.</para>
+        <section>
+            <title>Host Requirements</title>
+            <itemizedlist>
+                <listitem><para>Linux (preferrably Adélie)</para></listitem>
+                <listitem><para>Multiple CPUs or cores (highly recommended).</para></listitem>
+                <listitem><para>At least 1.5 GB memory on any platform; 2 GB recommended on x86.</para></listitem>
+                <listitem><para>At least 10 GB disk space; 30 GB is highly recommended.</para></listitem>
+                <listitem><para>Internet connection (highly recommended).</para></listitem>
+            </itemizedlist>
+        </section>
+        <section>
+            <title>Target Requirements</title>
+            <itemizedlist>
+                <listitem><para>A computer that supports Linux and a toolchain.</para></listitem>
+                <listitem><para>Boot media of some kind (flash, disk, ROM, network, etc).</para></listitem>
+            </itemizedlist>
+        </section>
+    </section>
+    <section>
+        <title>Process Overview</title>
+        <para>Porting the Adélie Linux system to a new platform involves a few high-level goals:</para>
+        <itemizedlist>
+            <listitem><para>Port the musl libc to the target (if required);</para></listitem>
+            <listitem><para>Build a "cross-compilation" toolchain for the target on the host, which allows you to build software for the target;</para></listitem>
+            <listitem><para>Build essential libraries and system software for the target using the cross-compiler on the host;</para></listitem>
+            <listitem><para>Re-build these essential libraries on the target.</para></listitem>
+        </itemizedlist>
+        <para>Once these goals have been completed, you will have a functional Adélie Linux system on the target.
+            After you have tested it and are satisfied with the stability and functionality of the port,
+            you may also wish to contact the Adélie Linux Platform Group for consideration on including the new port in the distribution.</para>
+    </section>
+</chapter>
diff --git a/src/porting/2_bootstrapping.xml b/src/porting/2_bootstrapping.xml
new file mode 100644
index 0000000..70e64e0
--- /dev/null
+++ b/src/porting/2_bootstrapping.xml
@@ -0,0 +1,33 @@
+<?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:
+        <itemizedlist>
+            <listitem><para>You will create a toolchain to use on your host to compile software for the 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>
+        </itemizedlist>
+    </para>
+    <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 <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>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>
+</chapter>
diff --git a/src/porting/3_native.xml b/src/porting/3_native.xml
new file mode 100644
index 0000000..6ca6fb9
--- /dev/null
+++ b/src/porting/3_native.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="3" id="native">
+    <title>Native Hardware Phase</title>
+</chapter>
diff --git a/src/porting/4_submit.xml b/src/porting/4_submit.xml
new file mode 100644
index 0000000..8ce3815
--- /dev/null
+++ b/src/porting/4_submit.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="4" id="submit">
+    <title>Submitting Your Port to Adélie Linux</title>
+</chapter>
diff --git a/src/porting/5_help b/src/porting/5_help
new file mode 100644
index 0000000..8ce3815
--- /dev/null
+++ b/src/porting/5_help
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="4" id="submit">
+    <title>Submitting Your Port to Adélie Linux</title>
+</chapter>
diff --git a/src/porting/5_help.xml b/src/porting/5_help.xml
new file mode 100644
index 0000000..899bb73
--- /dev/null
+++ b/src/porting/5_help.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<chapter label="5" id="help">
+    <title>If You Need Help</title>
+</chapter>
diff --git a/src/porting/portguide.xml b/src/porting/portguide.xml
new file mode 100644
index 0000000..8bbbb1d
--- /dev/null
+++ b/src/porting/portguide.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+               <!ENTITY chap1 SYSTEM "1_intro.xml">
+               <!ENTITY chap2 SYSTEM "2_bootstrapping.xml">
+               <!ENTITY chap3 SYSTEM "3_native.xml">
+               <!ENTITY chap4 SYSTEM "4_submit.xml">
+               <!ENTITY chap5 SYSTEM "5_help.xml">
+]>
+<book>
+    <bookinfo>
+        <title>Adélie Linux 1.0 Porting Guide</title>
+        <author>
+            <personname><firstname>A.</firstname><surname>Wilcox</surname></personname>
+        </author>
+        <copyright><year>2015</year><year>2018</year><holder>Adélie Linux</holder></copyright>
+        <legalnotice><para>This guide is provided under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 license.</para>
+            <para>A copy of this license is included with the source of the documentation.
+                It is also available on the Web on the <ulink url="https://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Web site</ulink>.</para>
+        </legalnotice>
+        <abstract>This guide details how to port the Adélie Linux distribution to a new computer system.</abstract>
+    </bookinfo>
+    <preface>
+        <title>Preface</title>
+        <para>This Porting Guide is the official guide to porting the Adélie Linux 1.0 system to new architectures.
+            It has been re-written from the ground up to take advantage of the new Alpine-based build system in use as of 1.0-alpha3.</para>
+        <para>Many contributed to the final version of this guide,
+            including <personname><firstname>Horst</firstname><surname>Burkhardt</surname></personname>,
+            <personname><firstname>Samuel</firstname><surname>Holland</surname></personname>,
+            and many others.</para>
+        <para>It is assumed that you, the reader, are familiar with compiling software and the Adélie build system.
+            If you are not yet familiar with these concepts, start with our Developer's Guide, which will assist you in learning them.</para>
+        <para>Please also ensure that you are comfortable and properly rested before reading this guide.
+            This will allow you to learn quicker, and be able to recall the information you have learned easier.</para>
+        <para>It is hoped by the author that you find this guide easy to understand and read.
+            Please feel free to contact me or the Adélie Linux community if you have any suggestions on how to make this guide better.
+            We'd love to hear from you, and we hope you enjoy using our distribution.</para>
+        <para>– <personname><firstname>A.</firstname><surname>Wilcox</surname></personname>, 2018</para>
+    </preface>
+    &chap1;
+    &chap2;
+    &chap3;
+    &chap4;
+    &chap5;
+</book>