summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/plat/porting.mdwn113
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.