doc/plat/porting: New page.

1 files changed, 113 insertions, 0 deletions

diff --git a/doc/plat/porting.mdwn b/doc/plat/porting.mdwn
new file mode 100644
index 0000000..65a9be7
--- /dev/null
+++ b/doc/plat/porting.mdwn
@@ -0,0 +1,113 @@
+Set Up a ProteanOS System
+-------------------------
+
+Get miniprokit, the "Mini ProteanOS Development Kit", as instructed here:
+<http://www.proteanos.com/get/>.
+
+Connect the storage medium (e.g. a hard disk drive connected using a USB
+adapter/dock or a USB flash drive).  On it, create one primary partition of type
+0x83 (Linux) and mark it as bootable.  cfdisk, sfdisk, or fdisk can be used for
+this.
+
+Run the following commands (replacing "/dev/sdc1" with the path to the newly
+created partition) to make and mount an ext4 file system, install ProteanOS into
+it, and enter a ProteanOS shell:
+
+    # mke2fs -t ext4 /dev/sdc1
+    # mount /dev/sdc1 /mnt
+    # /path/to/miniprokit.sh install -a i686-linux-glibc -P dev /mnt
+    # /path/to/miniprokit.sh shell /mnt
+
+Install, Configure, and Build the `linux-libre` Source Package
+--------------------------------------------------------------
+
+Choose a platform on which this new platform will be based.  In this tutorial,
+`ao751h` is used.
+
+Install toolchain packages, the source package, and build dependencies:
+
+    / # opkg install build-essential-$(cat /etc/proteanos_arch) \
+    > src-linux-libre config-linux-libre-ao751h bc xz \
+    > libncursesw.5-dev libtinfo-dev terminfo
+
+Change to the source package directory and use opkbuild to unpack the upstream
+sources and install platform configuration files:
+
+    / # cd /usr/src/linux-libre_3.10.40~gnu-2/
+    /usr/src/linux-libre_3.10.40~gnu-2 # opkbuild -bcT nop -P ao751h
+
+Hide the list of platform configuration files from opkbuild, so the modified
+configuration won't get overwritten:
+
+    /usr/src/linux-libre_3.10.40~gnu-2 # mv platconf platconf.no
+
+Enter the upstream source tree and configure Linux-libre:
+
+    /usr/src/linux-libre_3.10.40~gnu-2 # cd tmp/src/
+    /usr/src/linux-libre_3.10.40~gnu-2/tmp/src # make menuconfig
+
+Return to the source package directory and build the package for a platform
+other than `dev`:
+
+    /usr/src/linux-libre_3.10.40~gnu-2/tmp/src # cd ../../
+    /usr/src/linux-libre_3.10.40~gnu-2 # opkbuild -bcdP dimension2400
+
+Make the System Bootable
+------------------------
+
+Install the newly built linux-image package:
+
+    /usr/src/linux-libre_3.10.40~gnu-2 # opkg install \
+    > ../linux-image_3.10.40~gnu-2_i686-linux-glibc_dimension2400.opk
+
+Set a hostname and enable initialization of services:
+
+    /usr/src/linux-libre_3.10.40~gnu-2 # cd /
+    / # printf 'proteanos\n' >/etc/hostname
+    / # printf 'enabled\n' >/etc/rc.policy
+
+Exit the ProteanOS shell:
+
+    / # exit
+
+Back on the host system, unmount the file system:
+
+    # umount /mnt
+
+The storage medium can then be removed and connected to the target computer.
+
+Boot it!
+
+Make a `config-*` Source Package
+--------------------------------
+
+Once the `linux-libre` configuration is tested to boot and support all the
+relevant hardware and features, a configuration package should be made.
+
+Download the `config-*` package for the base platform you chose, either by
+running, for example, `opkg install src-config-ao751h` on ProteanOS or by
+cloning the relevant Git repository, e.g. `git clone
+git://git.proteanos.com/pkg/config-ao751h.git`.
+
+Set the `Maintainer` field in the `control` file.
+
+Clear the `changelog` file and add an initial revision entry.  This also names
+the package.  For example:
+
+    config-dimension2400 (0.1) trunk
+    
+      * Initial release.
+    
+     -- "P. J. McDermott" <pj@pehjota.net>  Mon, 16 Jun 2014 21:23:20 -0400
+
+Regenerate the metadata for the binary packages:
+
+    $ ./config clean
+    $ ./config
+
+Copy the `linux-libre` configuration file (`tmp/src/.config` under the source
+package directory) into `src/linux-libre/*/`.
+
+The `config-*` package can then be built, e.g. `opkbuild -S` to build the source
+package.  Please notify the ProteanOS community of your porting work, if you
+haven't already, and offer to upload and maintain the `config-*` package.