diff options
| -rw-r--r-- | dev/plat/simpler-porting.mdwn | 157 |
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 +-------------- + + |