Diffstat (limited to 'dev/plat/simpler-porting.mdwn')
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
@@ -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
+Testing is the easy part and will not be discussed for the remainder of this
+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.
+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
+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
+Instead, we need a different character, like `~`. A version with `~platconf~1`
+can replace a version without a distribution revision (a version in
+ # opkg compare-versions '3.10.60~gnu-1~platconf~1' '<<' '3.10.60~gnu-1' && echo false || echo true
+Debian also appends distribution revisions with `~` to the version strings of
+packages uploaded to its `experimental` distribution.
+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`).
+The porter runs a command which builds their `config-*` package, installs the
+resulting binary packages, and builds platform-specific packages for the new
+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