[[!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 `~~` in addition to `+~`. 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. The syntax for adding a feed is `opkg-feed -a `. Following is an example usage, for adding feeds for platform porting: # opkg-feed -a dev/platconf src all base # opkg-feed -a dev/platconf i686-linux-glibc platconf 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-feed to add the necessary feeds and then 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///`, where `` is the name of the configurable source package (e.g. `linux-libre`) and `` 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 --------------