1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
|
<?xml version="1.0" encoding="utf-8"?>
<chapter label="1" id="intro">
<title>Introduction to Porting</title>
<highlights><para>Welcome to the Adélie Linux Porting Handbook. This handbook 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></highlights>
<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 your build doesn't work perfectly the first time. Build issues and instability are common at the beginning of every port. 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 distribution; it is recommended that the host is already running Adélie Linux. It will also need a performant CPU and adequate disk space, because it will need to compile two full toolchains (compiler and other build tools).</para>
<warning><title>Warning</title><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 your 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 your target (if required);</para></listitem>
<listitem><para>Build a "cross-compilation" toolchain for your target on the host, which allows you to build software for your target;</para></listitem>
<listitem><para>Build essential libraries and system software for your target using the cross-compiler on the host;</para></listitem>
<listitem><para>Re-build these essential libraries on your target.</para></listitem>
</itemizedlist>
<para>Once these goals have been completed, you will have a functional Adélie Linux system on your 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 to consider including the new port in the official distribution.</para>
</section>
</chapter>
|
