dev/plat/simpler-porting: New file

1 files changed, 157 insertions, 0 deletions

diff --git a/dev/plat/simpler-porting.mdwn b/dev/plat/simpler-porting.mdwn
new file mode 100644
index 0000000..3836963
--- /dev/null
+++ b/dev/plat/simpler-porting.mdwn
@@ -0,0 +1,157 @@
+[[!meta title="Simpler Platform Porting"]]
+
+ProteanOS is unique as a purely binary distribution that is also highly
+configurable.  It's easy to install on a supported computer.  But its nature
+makes it not so easy to [[port it to a new computer|doc/plat/porting]].
+
+There are four main steps to porting ProteanOS to a new platform:
+
+ 1. **Configure**: First, the platform-specific source packages (`busybox` and
+    `linux-libre` need to be configured for the new platform.
+ 2. **Build**: Next, those platform-specific packages need to be built for the
+    new platform.
+ 3. **Install**: Then, a bootable ProteanOS system with the newly built
+    platform-specific binary packages needs to be installed.
+ 4. **Test**: Finally, the ProteanOS system can be booted and the features of
+    the new platform can be tested.
+
+If any issues are found in testing, the process returns to step one.  If not,
+the `config-*` source package for the new platform may be sent for inclusion in
+ProteanOS.
+
+Testing is the easy part and will not be discussed for the remainder of this
+document.
+
+The currently [[documented|doc/plat/porting]] method for porting ProteanOS
+blurs the first two steps and involves a hack to hide from opkbuild the
+`platconf` file(s) of the package(s) being configured.  The hardest and least
+well documented part of the current method is the installation step.
+
+The rest of this document specifies potential improvements to the platform
+porting process, organized by steps of the process.
+
+Configuration
+=============
+
+Interface
+---------
+
+The porter runs `ppt-make` (from the `platconf-pkg-tools` package) or a similar
+tool to generate a basic configuration package.
+
+The porter then runs a command which presents the configuration options of
+platform-specific packages using kconfig's `mconf` utility (as seen when running
+`make menuconfig` in Linux-libre, BusyBox, and other packages).
+
+Implementation: Maintaining Platform-Specific Packages
+------------------------------------------------------
+
+A new [`kbuild-kconfig` package][kbuild-kconfig] is built and uploaded,
+providing standalone versions of the Kconfig programs from Linux, as well as a
+[kconfigpp][] preprocessor to extract a single complete Kconfig file from a
+source tree, handling `source` directives (as in Linux-libre) and generating
+Kconfig directives from `//config:` comments in source files (as in BusyBox).
+
+Source packages with `platconf` files (currently `busybox` and `linux-libre`)
+are modified to `Build-Depend` on `kbuild-kconfig` and to build `*-kconfig`
+packages (`Architecture: any` and `Platform: platconf`) containing Kconfig input
+files generated from the upstream source tree by kconfigpp.
+
+[SPF 2.0 § 4.6][spf-2.0-src-ver] is amended to allow `~<dist>~<distrev>` in
+addition to `+<dist>~<distrev>`.  opkbuild is modified to allow the same.
+
+Then, when a new upstream version of a source package with a `platconf` file
+(e.g. `linux-libre`) is prepared, `~platconf~1` is appended to its version
+string and the distribution in `changelog` is set to `platconf` (instead of
+`trunk`).  The package is built for the `platconf` platform of all architectures
+and uploaded (source and binary packages) to the package archive, where it will
+be included in the `dev/platconf` suite (instead of `dev/trunk`).
+
+The reason for the `~` in the version string is as follows.  The version that
+will later be uploaded to `dev/trunk` should replace the version uploaded to
+`dev/platconf`; that is, the former needs to have a later version string.
+Versions can be compared with opkg's `compare-versions` subcommand:
+
+    # opkg compare-versions '3.10.55~gnu-1' '<<' '3.10.60~gnu-1' && echo false || echo true
+    true
+
+Appending a distribution revision with `+` is to be done for distributions that
+are downstream of `dev/trunk`, like `dev/rs1`.  It won't work for distributions
+that are upstream of `dev/trunk`, like `dev/platconf`:
+
+    # opkg compare-versions '3.10.60~gnu-1+platconf~1' '<<' '3.10.60~gnu-1' && echo false || echo true
+    false
+
+Instead, we need a different character, like `~`.  A version with `~platconf~1`
+can replace a version without a distribution revision (a version in
+`dev/trunk`):
+
+    # opkg compare-versions '3.10.60~gnu-1~platconf~1' '<<' '3.10.60~gnu-1' && echo false || echo true
+    true
+
+Debian also appends distribution revisions with `~` to the version strings of
+packages uploaded to its `experimental` distribution.
+
+[kbuild-kconfig]: http://git.proteanos.com/users/pehjota/kbuild-kconfig.git/
+[kconfigpp]: http://git.proteanos.com/users/pehjota/kbuild-kconfig.git/tree/kconfigpp/kconfigpp.sh
+[spf-2.0-src-ver]: http://specs.proteanos.com/spf-2.0/metadata.html#src-ver
+
+Implementation: Maintaining Platform Ports
+------------------------------------------
+
+The `opkg` binary package provides a `/usr/bin/opkg` wrapper script that
+combines configuration files under `/etc/opkg/` to form a temporary
+configuration file for `usr/bin/opkg-cl`.  It also provides a new
+`/usr/bin/opkg-feed` script (similar to Ubuntu's add-apt-repository) that
+manages `src` options in opkg configuration files, e.g. to add a new packages
+feed.  Example usage, for adding the feed for the `dev/platconf` suite, `src`
+architecture, `all` platform, and `base` section to opkg's configuration and
+updating opkg's package lists:
+
+    # opkg-feed -a dev/platconf src all base
+    # opkg update
+
+`ppt-make` (which generates a new `config-*` package) from `platconf-pkg-tools`
+asks two more questions: the architecture of the platform and the name of an
+existing platform on which to base the new one.  `ppt-make` runs opkg to install
+the `config-*` package for the platform the user specifies.
+
+A new `ppt-configure` tool is added to `platconf-pkg-tools`.  This tool finds
+and installs all of the available `*-kconfig` packages, builds a single unified
+Kconfig input file from those of the `*-kconfig` packages, runs `mconf` on the
+generated Kconfig file, and splits the `.config` file the user saves into files
+in `src/build/<package>/<version>/`, where `<package>` is the name of the
+configurable source package (e.g. `linux-libre`) and `<version>` is the upstream
+version of the package (e.g. `3.10.60~gnu`).
+
+
+Building
+========
+
+Interface
+---------
+
+The porter runs a command which builds their `config-*` package, installs the
+resulting binary packages, and builds platform-specific packages for the new
+platform.
+
+Implementation
+--------------
+
+
+
+
+Installation
+============
+
+Interface
+---------
+
+The porter runs a command and specifies a block device to use, and a ProteanOS
+system with the newly built platform-specific packages is installed and ready to
+boot.
+
+Implementation
+--------------
+
+