[[!meta title="Porting ProteanOS to a New Platform"]]

You have a computer on which you want to run ProteanOS?  Great!

ProteanOS configures and builds static (i.e. without modules) Linux-libre images
for each target computer and use case to save space and memory.  The result is a
complete Linux-libre image that takes about 4 MiB or less, instead of an image
and modules that all take over 100 MiB.  This also means that you'll probably
have to configure Linux-libre for your computer, unless you happen to have a
computer that ProteanOS already supports (in which case, just go install
ProteanOS!).

So read on to port ProteanOS to your computer!


Set Up a ProteanOS System
=========================

[[Get_prokit|doc/install/prokit]], the ProteanOS Development Kit.

Connect a storage medium (e.g. a hard disk drive connected using a USB
adapter/dock or a USB flash drive).  Run the following commands (replacing
`/dev/sdb` with the path to storage device and `i686-linux-glibc` with the
architecture of the target system) to create a partition layout and file system
and install ProteanOS into it:

    # prokit installer-pc -a i686-linux-glibc -p dev dev/trunk /dev/sdb


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:

    # prokit opkg /dev/sdb1 install build-essential src-linux-libre \
    > config-linux-libre-ao751h bc xz libncursesw.5-dev libtinfo-dev terminfo

Start a ProteanOS shell, change to the source package directory, and use
opkbuild to unpack the upstream sources and install platform configuration
files:

    # prokit shell /dev/sdb1
    # cd /usr/src/linux-libre_*/
    # opkbuild -bcT nop -p ao751h

Hide the list of platform configuration files from opkbuild, so the modified
configuration won't get overwritten:

    # mv platconf platconf.no

Enter the upstream source tree and configure Linux-libre:

    # cd tmp/src/
    # make menuconfig

Return to the source package directory and build the package for a platform
other than `dev`:

    # cd ../../
    # opkbuild -bcdp dimension2400


Make the System Bootable
========================

Install the newly built linux-image package:

    # opkg install ../linux-image_*_i686-linux-glibc_dimension2400.opk

Set a hostname and enable initialization of services:

    # printf 'proteanos\n' >/etc/hostname
    # printf 'enabled\n' >/etc/rc.policy

Exit the ProteanOS shell:

    # exit

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, `prokit opkg install src-config-ao751h` 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/*/` in your new configuration source
package.

Your configuration package can then be built, e.g. `prokit build -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.