path: root/dev/multiarch.mdwn
diff options
Diffstat (limited to 'dev/multiarch.mdwn')
1 files changed, 101 insertions, 0 deletions
diff --git a/dev/multiarch.mdwn b/dev/multiarch.mdwn
new file mode 100644
index 0000000..0669fba
--- /dev/null
+++ b/dev/multiarch.mdwn
@@ -0,0 +1,101 @@
+[[!meta title="Multiarch Design"]]
+This is a [[release_goal|dev/releases/1/multiarch]] for release 1.0. Earlier
+design proposals are documented at in [[another_page|dev/multiarch/design]] kept
+for historical purposes.
+ProteanOS is a self-hosting binary distribution that builds its own packages.
+It is also an embedded distribution, intended to be suitable for small
+resource-limited systems. It may not be practical to natively build all of
+ProteanOS on real hardware for every architecture to be supported. Thus, it
+will be preferable to cross-build all of ProteanOS's packages, making ProteanOS
+a highly ambitious cross-built self-hosting binary distribution.
+Cross-compiling and cross-assembling self-contained code is a solved problem,
+however programs typically use separately built libraries, which must be
+installed at build time to be available for compiling and linking. Sometimes,
+these dependency libraries will already be installed for use by the native
+system. So it needs to be possible to "coinstall" different architecture builds
+of each library. Package management and build tools also need to be able to
+install dependency packages of the correct architecture; for example, libraries
+must be of the *host* architecture (the architecture **for** which a package is
+being built), but build utilities must be of the *build* architecture (the
+architecture **on** which a package is being built). Further complicating
+dependency resolution, such build utilities often themselves depend on
+libraries, which must also be of the build architecture (not the host
+architecture like libraries that are direct build-dependencies). These are the
+two main problems in cross-building distribution packages: coinstallability and
+dependencies. The solution is a design known as "multiarch".
+ProteanOS's multiarch design is inspired by, but different from, that
+[specified][wuc-mas] and [documented][wdo-ma] in Debian and Ubuntu.
+ProteanOS's design solves the coinstallability and dependency problems without
+*any* modifications to its package manager, opkg-lede. This is desirable
+because opkg-lede is a tool used by many distributions separate from ProteanOS,
+and its upstream maintainers (OpenWrt) would likely be unwilling to merge and
+maintain invasive patches specific to a different distribution (making the
+patches impossible to test upstream).
+opkg-lede doesn't allow multiple packages to provide the same file path, so, in
+order to be coinstallable, library packages must install all of their files into
+architecture-qualified locations. [Debian and Ubuntu][wuc-mas-arch-indep-files]
+limit this requirement to only files whose contents differ between
+architectures. This is accomplished by the package manager dpkg requiring all
+packages of the same name to be the same version, verifying that shared files
+have identical contents, and reference counting shared files. As explained
+above, ProteanOS's multiarch design doesn't entail such modifications to the
+package manager.
+opkg-lede also doesn't allow installation of multiple packages with the same
+name and different architectures. The only way to solve this without modifying
+the package manager is to quialify the names of coinstallable packages with
+their host architectures. This will be done by appending a colon followed by
+the host architecture to each coinstallable package name, e.g. `libc.6` becomes
+`libc.6:amd64-linux-glibc`. Package names appear in the file system under
+`/var/cache/opkg/archives/` and `/var/lib/opkg/info/`, so using a colon in
+package names will prevent the use of restricted file systems such as FAT file
+systems as the root file system.
+opkg-lede allows packages from different architectures to be installed, but
+there is no way to select the architecture to install other than blanket
+priority values. Since libraries of different architectures will often need to
+be installed during the same installation transaction, as described above, such
+a blunt solution is insufficient.
+[Debian and Ubuntu][wuc-mas-control-fields] solve this by declaring the kinds of
+dependencies each package is able to satisfy (based on the interfaces it
+provides: executables and/or libraries). Again this requires modifications to
+the package manager to affect dependency resolution. ProteanOS's design is
+similar, but implemented in a way such that *dependent* binary packages are
+responsible for declaring the architectures of *their dependencies* (which can
+be done automatically at build time).
+One way to declare dependency semantics is by introducing a new single-purpose
+control field like Debian's and Ubuntu's `Multi-Arch`. However, ProteanOS will
+instead use a control field that serves multiple purposes:
+[`Section`][spf-fields-bin]. Section `lib` packages will be automatically made
+coinstallable by opkbuild, by architecture-qualifying their names as described
+above. Library dependencies generated by oh-shlibdeps will automatically use
+the architecture-qualified names.