From 6d03854a183f2d0426d89d182019b6e87636b8ca Mon Sep 17 00:00:00 2001 From: "A. Wilcox" Date: Thu, 26 Apr 2018 22:07:13 -0500 Subject: Porting Guide: Start work on this --- src/porting/1_intro.xml | 67 +++++++++++++++++++++++++++++++++++++++++ src/porting/2_bootstrapping.xml | 33 ++++++++++++++++++++ src/porting/3_native.xml | 4 +++ src/porting/4_submit.xml | 4 +++ src/porting/5_help | 4 +++ src/porting/5_help.xml | 4 +++ src/porting/portguide.xml | 45 +++++++++++++++++++++++++++ 7 files changed, 161 insertions(+) create mode 100644 src/porting/1_intro.xml create mode 100644 src/porting/2_bootstrapping.xml create mode 100644 src/porting/3_native.xml create mode 100644 src/porting/4_submit.xml create mode 100644 src/porting/5_help create mode 100644 src/porting/5_help.xml create mode 100644 src/porting/portguide.xml (limited to 'src') 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 @@ + + + Introduction to Porting + 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. +
+ Before You Begin + 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. +
+
+ Requirements + 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). + + 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. + + 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. + 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. + 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. +
+ Host Requirements + + Linux (preferrably Adélie) + Multiple CPUs or cores (highly recommended). + At least 1.5 GB memory on any platform; 2 GB recommended on x86. + At least 10 GB disk space; 30 GB is highly recommended. + Internet connection (highly recommended). + +
+
+ Target Requirements + + A computer that supports Linux and a toolchain. + Boot media of some kind (flash, disk, ROM, network, etc). + +
+
+
+ Process Overview + Porting the Adélie Linux system to a new platform involves a few high-level goals: + + Port the musl libc to the target (if required); + Build a "cross-compilation" toolchain for the target on the host, which allows you to build software for the target; + Build essential libraries and system software for the target using the cross-compiler on the host; + Re-build these essential libraries on the target. + + 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. +
+ 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 @@ + + + Bootstrapping Phase + During this phase, you will create a number of necessary tools: + + You will create a toolchain to use on your host to compile software for the target. + This is called a "cross-compilation" toolchain. + 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. + You will configure a kernel to boot on the target. + You will then create a bootable image that you will use to boot the target into Adélie Linux. + + +
+ Ensuring the musl C library is ported + 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 the online musl Git repository, + or in the arch/ directory of the musl source code found on the Adélie Linux Platform Group Resource Disc. + 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 the official musl porting documentation. +
+
+ Creating the cross-compilation toolchain + In this section, you will: + + Add the necessary information to abuild and APKBUILDs for essential software; + Install the amended abuild to your host computer; and + Create the initial cross-compilation toolchain, allowing you to build packages for your target. + + Please make sure that you are at your host computer's terminal before continuing. +
+ 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 @@ + + + Native Hardware Phase + 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 @@ + + + Submitting Your Port to Adélie Linux + 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 @@ + + + Submitting Your Port to Adélie Linux + 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 @@ + + + If You Need Help + 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 @@ + + + + + + +]> + + + Adélie Linux 1.0 Porting Guide + + A.Wilcox + + 20152018Adélie Linux + This guide is provided under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 license. + A copy of this license is included with the source of the documentation. + It is also available on the Web on the Creative Commons Web site. + + This guide details how to port the Adélie Linux distribution to a new computer system. + + + Preface + 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. + Many contributed to the final version of this guide, + including HorstBurkhardt, + SamuelHolland, + and many others. + 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. + 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. + 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. + – A.Wilcox, 2018 + + &chap1; + &chap2; + &chap3; + &chap4; + &chap5; + -- cgit v1.2.3-60-g2f50