Document the core-linux-eglibc port bootstrap.

3 files changed, 189 insertions, 2 deletions

diff --git a/dev/ports/core-linux-eglibc/bootstrap.mdwn b/dev/ports/core-linux-eglibc/bootstrap.mdwn
new file mode 100644
index 0000000..a9d0171
--- /dev/null
+++ b/dev/ports/core-linux-eglibc/bootstrap.mdwn
@@ -0,0 +1,187 @@
+[[!meta title="core-linux-eglibc Port Bootstrap"]]
+
+`core-linux-eglibc` is the first architecture port of ProteanOS 1.0.
+([[ProteanOS_0.x|/dev/releases/0]] had a `cortexa8-linux-eglibc` architecture,
+but `core-linux-eglibc` is being built from scratch.)
+
+This port is being bootstrapped from a Debian GNU/Linux system.
+
+Operating systems are often bootstrapped with GCC by building a cross compiling
+GCC with a sysroot then using that to build the system.  This port is instead
+being bootstrapped natively in two stages.  This is possible because care is
+taken to ensure that the resulting ELF binaries are compatible with the
+ProteanOS ABI (including the value of the ELF INTERP field and the file system
+hierarchy).
+
+The first stage involves building base system and toolchain packages and
+unpacking them into a bootstrap system directory.
+
+The second stage involves changing the file system root (with **chroot**(8)) to
+the bootstrap directory and building source packages.
+
+
+Stage 1
+=======
+
+These instructions are tested on a Debian wheezy amd64 GNU/Linux system.
+
+The following directory structure is assumed:
+
+    <work-root>/
+     +- bootstrap_core-linux-eglibc/
+         +- etc/
+         +- lib/
+         +- [...]
+     +- pkg/
+         +- binutils/
+         +- eglibc/
+         +- gcc-4.7/
+         +- [...]
+         +- zlib/
+
+Preparation
+-----------
+
+Build and install [opkbuild 3.0.0-alpha4][opkbuild-3.0.0-alpha4] and
+[opkhelper 3.0.0-beta2][opkhelper-3.0.0-beta2].
+
+The build system needs to be made to look a little more like ProteanOS.
+
+To install `/etc/proteanos_arch` and `/etc/proteanos_plat` files on the build
+system for **opkbuild**(1), run opkbuild's `mksysconf` makefile with `ARCH` and
+`PLAT` macros, e.g.:
+
+    # ./mksysconf ARCH=core-linux-eglibc PLAT=dev
+
+The `gcc-4.7` package will look for a symbolic link to the ELF interpreter
+(dynamic linker) at `/usr/lib/core-linux-eglibc/ld.so`.
+
+    # mkdir /lib/core-linux-eglibc /usr/lib/core-linux-eglibc
+    # ln -sf /lib64/ld-linux-x86-64.so.2 /lib/core-linux-eglibc/ld-linux-x86-64.so.2
+    # ln -sf /lib/core-linux-eglibc/ld-linux-x86-64.so.2 /usr/lib/core-linux-eglibc/ld.so
+
+Make a directory for the bootstrap ProteanOS system.
+
+    $ mkdir bootstrap_core-linux-eglibc
+
+ProteanOS's ELF interpreter is not installed in the location described in the
+ELF INTERP field of binaries built with the build system's GCC.  Make a symbolic
+link in the bootstrap system directory to direct Linux to the correct location
+when it executes the stage 1 binaries.
+
+    $ mkdir bootstrap_core-linux-eglibc/lib64
+    $ ln -sf /lib/core-linux-eglibc/ld-linux-x86-64.so.2 bootstrap_core-linux-eglibc/lib64/ld-linux-x86-64.so.2
+
+[opkbuild-3.0.0-alpha4]: http://files.proteanos.com/pub/opkbuild/3.0.0-alpha4/
+[opkhelper-3.0.0-beta2]: http://lists.proteanos.com/proteanos-dev/2013/05/msg00001.html
+
+Building EGLIBC
+---------------
+
+Run the following commands in a copy of the `eglibc` source package to build
+EGLIBC for the bootstrap system.
+
+    $ opkbuild -b -c
+
+Building zlib
+-------------
+
+Run the following commands in a copy of the `zlib` source package to build zlib
+for the bootstrap system.
+
+    $ opkbuild -b -c
+
+Building, Installing, and Testing GNU Binutils
+----------------------------------------------
+
+Run the following commands in a copy of the `binutils` source package to build
+GNU Binutils for the bootstrap system.
+
+    $ ./config clean
+    $ PKG_TARGETS='core-linux-eglibc' ./config
+    $ opkbuild -b -c
+
+Run the following commands in the bootstrap system directory to unpack the
+`binutils` packages and their dependencies:
+
+    $ tar -xzOf ../pkg/libc.6_2.17~r22751+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/libz.1_1.2.7+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/binutils-common_2.22-1_all_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/binutils-core-linux-eglibc_2.22-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+
+Now test some Binutils programs.
+
+    # chroot . as --version
+    GNU assembler (GNU Binutils for ProteanOS) 2.22
+    Copyright 2011 Free Software Foundation, Inc.
+    This program is free software; you may redistribute it under the terms of
+    the GNU General Public License version 3 or later.
+    This program has absolutely no warranty.
+    This assembler was configured for a target of `x86_64-unknown-linux-gnu'.
+    # chroot . readelf -hl /usr/bin/readelf
+    [...]
+    # chroot . objdump -p /usr/bin/objdump
+    [...]
+
+Building the Multiple Precision Libraries
+-----------------------------------------
+
+TODO.
+
+Building, Installing, and Testing GCC
+-------------------------------------
+
+Run the following commands in a copy of the `gcc-4.7` source package to build
+GCC for the bootstrap system.
+
+    $ ./config clean
+    $ PKG_TARGETS='core-linux-eglibc' ./config
+    $ opkbuild -b -c
+
+Run the following commands in the bootstrap system directory to unpack the
+`gcc-4.7` packages and their dependencies.
+
+    $ tar -xzOf ../pkg/libc.6-dev_2.17~r22751+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/libgcc.1_4.7.3+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/libgomp.1_4.7.3+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/libitm.1_4.7.3+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/libgmp.10_5.0.5-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/libmpc.3_1.0.1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/libmpfr.4_3.1.1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/cpp-4.7-core-linux-eglibc_4.7.3+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/gcc-4.7-common_4.7.3+sip1-1_all_all.opk data.tar.gz | tar -xz
+    $ tar -xzOf ../pkg/gcc-4.7-core-linux-eglibc_4.7.3+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+
+Now try compiling, linking, and running an example program (the `fitblk.c`
+example from zlib).
+
+    $ tar -xzOf ../pkg/libz.1-dev_1.2.7+sip1-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+    $ cp ../pkg/zlib/tmp/src/examples/fitblk.c .
+    # chroot . core-linux-eglibc-gcc-4.7 -lz -o /fitblk /fitblk.c
+    # chroot . /fitblk
+    fitblk abort: need one argument: size of output block
+
+Building and Installing GNU Make
+--------------------------------
+
+Run the following commands in a copy of the `gmake` source package to build GNU
+Make for the bootstrap system.
+
+    $ LDFLAGS='-Wl,--dynamic-linker=/lib/core-linux-eglibc/ld-linux-x86-64.so.2' opkbuild -b -c
+
+Run the following commands in the bootstrap system directory to unpack the
+`gmake` package:
+
+    $ tar -xzOf ../pkg/gmake_3.82-1_core-linux-eglibc_all.opk data.tar.gz | tar -xz
+
+TODO
+----
+
+To be built and installed are busybox, linux-libre (headers), gcc-defaults,
+opkbuild, opkhelper-3.0, and opkhelper-data.
+
+
+Stage 2
+=======
+
+TODO.
diff --git a/dev/ports/list.mdwn b/dev/ports/list.mdwn
index 203689c..5963446 100644
--- a/dev/ports/list.mdwn
+++ b/dev/ports/list.mdwn
@@ -9,6 +9,6 @@ Current
 Planned
 =======
 
-  * [[core-linux-eglibc|dev/ports/core-linux-eglibc-bootstrap]]
+  * [[core-linux-eglibc|dev/ports/core-linux-eglibc/bootstrap]]
   * [[i686-linux-eglibc|dev/ports/i686-linux-eglibc-bootstrap]]
   * k8-linux-eglibc
diff --git a/dev/releases/1.mdwn b/dev/releases/1.mdwn
index 81ae82a..cb3bc9c 100644
--- a/dev/releases/1.mdwn
+++ b/dev/releases/1.mdwn
@@ -57,7 +57,7 @@ Architectures
 -------------
 
   * cortexa8-linux-eglibc
-  * [[core-linux-eglibc|dev/ports/core-linux-eglibc-bootstrap]]
+  * [[core-linux-eglibc|dev/ports/core-linux-eglibc/bootstrap]]
   * [[i686-linux-eglibc|dev/ports/i686-linux-eglibc-bootstrap]]
   * k8-linux-eglibc