Rewrite multiarch task and design information.

2 files changed, 203 insertions, 63 deletions

diff --git a/dev/multiarch/design.mdwn b/dev/multiarch/design.mdwn
new file mode 100644
index 0000000..fff2864
--- /dev/null
+++ b/dev/multiarch/design.mdwn
@@ -0,0 +1,185 @@
+[[!meta title="Multiarch Design"]]
+
+There are three high-level design aspects to this multiarch implementation: the
+filesystem hierarchy that primarily enables package coinstallability, control
+information documenting package coinstallability and dependency satisfaction,
+and coinstallability considerations in package management.
+
+For reference, see the [specification][wuc-mas] and [other
+documentation][wdo-ma] for multiarch in Debian and Ubuntu.
+
+
+Filesystem Hierarchy
+====================
+
+For packages to be coninstallable with themselves (such that a user can have
+multiple architecture builds of one package installed simultaneously), all
+architecture-dependent files must be installed in architecture-dependent
+locations.  The most straightforward way to do this is to embed architecture
+strings into filesystem paths.
+
+Debian and Ubuntu do something similar to this.  In a Debian library package
+that supports multiarch, shared object files are installed in
+`/usr/lib/<triplet>`, where `<triplet>` is a [GNU system type][ac-systemtype].
+
+The scope of Debian's and Ubuntu's multiarch work [does not include][wdo-ma-fut]
+coinstallable executable programs.
+
+Such work, however, would help enable cross installation of packages.  So a goal
+of this multiarch implementation is to support coinstallation of shared object
+files, header files, and executable programs.
+
+There are two proposed filesystem hierarchies (see below) to support this.
+
+Parts of the toolchain (especially the dynamic linker) need to be configured
+and/or patched to use multiarch library paths.  Additionally, at least the
+native-architecture executable program directories have to be added to the PATH
+environment variable.
+
+Proposal 1: `/usr` Organized Primarily by Architecture
+------------------------------------------------------
+
+It may be useful to install all architecture-dependent files under
+`/usr/<arch>`, where `<arch>` is a distribution architecture string.  The
+filesystem hierarchy would then look something like this:
+
+    /
+     +- bin/
+     |   +- core-linux-eglibc/
+     |   \- cortexa8-linux-eglibc/
+     +- lib/
+     |   +- core-linux-eglibc/
+     |   \- cortexa8-linux-eglibc/
+     +- sbin/
+     |   +- core-linux-eglibc/
+     |   \- cortexa8-linux-eglibc/
+     \- usr/
+         +- core-linux-eglibc/
+         |   +- bin/
+         |   +- games/
+         |   +- include/
+         |   +- lib/
+         |   +- sbin/
+         +- cortexa8-linux-eglibc/
+         |   +- bin/
+         |   +- games/
+         |   +- include/
+         |   +- lib/
+         |   +- sbin/
+         +- bin/
+         +- games/
+         +- include/
+         +- local/
+         +- sbin/
+         +- share/
+         \- src/
+
+Note that `/usr/lib` doesn't exist, as no architecture-independent files should
+be installed there.
+
+Proposal 2: `/usr` Organized Secondarily by Architecture
+--------------------------------------------------------
+
+It may be cleaner and slightly more efficient to install architecture-dependent
+files within an architecture-dependent directory under otherwise standard paths.
+This is similar to how Debian and Ubuntu have designed their multiarch
+filesystem hierarchy.  Such an organized filesystem hierarchy would look
+something like this:
+
+    /
+     +- bin/
+     |   +- core-linux-eglibc/
+     |   \- cortexa8-linux-eglibc/
+     +- lib/
+     |   +- core-linux-eglibc/
+     |   \- cortexa8-linux-eglibc/
+     +- sbin/
+     |   +- core-linux-eglibc/
+     |   \- cortexa8-linux-eglibc/
+     \- usr/
+         +- bin/
+             +- core-linux-eglibc/
+             +- cortexa8-linux-eglibc/
+         +- games/
+             +- core-linux-eglibc/
+             +- cortexa8-linux-eglibc/
+         +- include/
+             +- core-linux-eglibc/
+             +- cortexa8-linux-eglibc/
+         +- lib/
+             +- core-linux-eglibc/
+             +- cortexa8-linux-eglibc/
+         +- local/
+         +- sbin/
+             +- core-linux-eglibc/
+             +- cortexa8-linux-eglibc/
+         +- share/
+         \- src/
+
+
+Control Information
+===================
+
+New package control information will be needed to indicate whether a package is
+coinstallable with itself and to mark its purpose.
+
+During build-time, there are two possible architectures for any dependent package:
+
+  * Host-architecture (architecture for which packages are built).  Packages for
+    this architecture provide things like libraries and headers.  An example is
+    libexpat.1-dev.
+  * Build-architecture (architecture on which packages are built).  Packages for
+    this architecture provide things like build utilities An example is
+    pkg-config.
+
+During install-time, there are also two possible architectures for any dependent
+package:
+
+  * Host-architecture (architecture for which packages are installed).  Packages
+    for this architecture provide things like libraries and utilities.  Examples
+    include libz.1, gcc-4.7-<arch> (dependency of gcc-<arch>), and fakeroot
+    (recommendation of opkhelper-1.0).
+  * Install-architecture (architecture on which packages are installed).
+    Packages for this architecture provide things like utilities used by
+    maintainer scripts.  An example is insserv (or a similar tool).
+
+Host-architecture packages should be coinstallable with themselves, and they
+should satisfy dependencies of the same architecture.  For example, the
+dependency of libexpat.1-dev:cortexa8-linux-eglibc on libexpat.1 should resolve
+to a dependency on libexpat.1:cortexa8-linux-eglibc.
+
+Build- and install-architecture packages need not be coinstallable with
+themselves, and they should satisfy dependencies of any architecture.  For
+example, the build dependency of glib (built on core-linux-eglibc for
+cortexa8-linux-eglibc) on pkg-config should resolve to a build dependency on
+pkg-config:core-linux-eglibc.
+
+Debian and Ubuntu specify such properties in a `Multi-Arch` control field.  A
+value of `same` indicates that a package satisfies dependencies of the same
+architecture; a value of `foreign` indicates that a package satisfies
+dependencies of any architecture.  We can implement something similar, perhaps
+even using the same terminology.
+
+Logic to handle the new control information will need to be added to opkg and
+opkhelper (specifically oh-checkbuilddeps).
+
+Special design considerations need to be given to install-time dependencies.
+Specific use case analysis can help here.
+
+
+Architecture-Independent Files
+==============================
+
+Many packages provide architecture-independent files (configuration files,
+documentation, data, etc.).  To the extent possible and feasible, these should
+simply be provided by architecture-independent packages (with names like
+"*-common", "*-data", or "*-base").
+
+If this is not possible in all cases, then some modifications to opkg will be
+necessary (reference counting, implicit "Breaks" relationships, etc.).
+
+
+[wdo-ma]: http://wiki.debian.org/Multiarch
+[wuc-mas]: https://wiki.ubuntu.com/MultiarchSpec
+[ac-systemtype]: https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf-2.69/html_node/System-Type.html
+[wdo-ma-fut]: http://wiki.debian.org/Multiarch#Future_development
diff --git a/dev/todo/multiarch.mdwn b/dev/todo/multiarch.mdwn
index 4bf5413..2f34940 100644
--- a/dev/todo/multiarch.mdwn
+++ b/dev/todo/multiarch.mdwn
@@ -1,77 +1,32 @@
 [[!meta title="Multiarch"]]
 
 Multiarch refers to the ability to install and use packages built for non-native
-architectures.  It is currently being [documented and implemented][wdo-ma] in
-Debian and Ubuntu.  Multiarch is useful for this distribution because it makes
-cross compiling easy (see "Package Cross Building Tool" and "Multiarch Cross
-Toolchain Packages").
+architectures and the ability to coinstall multiple architecture builds of any
+supporting package.
 
-Simply speaking, there are six [aspects of a multiarch implementation][ma-des]:
+It is currently being [designed][wuc-mas] and [implemented][wdo-ma] in Debian
+and Ubuntu.  Multiarch is useful for this distribution because it can make cross
+building and cross installing easy.
 
-  * **Filesystem Hierarchy**
-    
-    To accomodate simultaneous installation of shared libraries built for
-    different architectures, library paths are suffixed with a directory name
-    that identifies a particular architecture.  For this distribution, that
-    directory name will be the name of the binary architecture; for example,
-    library paths for the `cortexa8-linux-eglibc` architecture will be
-    `/lib/cortexa8-linux-eglibc` and `/usr/lib/cortexa8-linux-eglibc`.
-    
-    The toolchain (especially the dynamic linker) needs to be configured to use
-    these library paths.
 
-  * **A `Multi-Arch` Control Field**
-    
-    A `Multi-Arch` control field specifies how a package can satisfy
-    dependencies of other packages.  A value of `same` means that a package can
-    only satisfy dependencies of packages built for the architecture for which
-    it was built.  This is useful for shared libraries, which can only be
-    dynamically linked against binary objects built for the same architecture.
-    A value of `foreign` means that a package can satisfy dependencies of
-    packages built for any architecture.  This is useful for utility programs,
-    which can be used by software built for any architecture.
-    
-    The package manager (opkg in our case) and package building tools
-    (specifically oh-checkbuilddeps of opkhelper) must be able to understand
-    and use this field in resolving package dependencies.
+Design Aspects
+==============
 
-  * **Architecture Specification in Package Relationships**
-    
-    Control fields like `Depends` are extended to support an architecture
-    specification of either `any` or `same`, allowing a package to specify
-    whether or not it needs a package of the same architecture.  The dependent
-    package has a `Multi-Arch` field with value `allowed`.
-    
-    The package manager and package building tools must be able to understand
-    and use this architecture syntax in relationship fields.
+There are three high-level design aspects to this multiarch implementation: the
+filesystem hierarchy that primarily enables package coinstallability, control
+information documenting package coinstallability and dependency satisfaction,
+and coinstallability considerations in package management.
 
-  * **Handling of Packages with `Architecture: all`**
-    
-    Dependence on packages installable and usable on any architecture
-    (especially considering opkg's ability to install packages of multiple
-    architectures) must be researched.
+For more details, see the [[multiarch_design_document|dev/multiarch/design]].
 
-  * **Non-Library Files in Library Packages**
-    
-    Library packages provide files outside of system library paths, such as
-    configuration and package documentation files.  A solution must be designed
-    to allow a package built for one architecture to be co-installable with the
-    same package built for a different architecture (or to determine if they are
-    co-installable at all).
 
-  * **Ability to Install Packages Built for Non-Native Architectures**
-    
-    The package manager must be able to install packages built for multiple
-    architectures (the whole point of multiarch).  Fortunately for us, opkg
-    already handles this.  The `arch` option in `opkg.conf` [allows the user to
-    specify architectures][opkg-conf-arch] for which packages can be installed.
+Goals
+=====
 
-In summary, there is much design work to be done, opkg and opkhelper must be
-modified to support multiarch, and certain packages will need to be built to
-handle multiarch library paths.  Of course Debian is a great reference
-implementation, but there still remains much original work to be done.
+The design and implementation of the filesystem hierarchy is
+[[a_goal_for_release_1.0.0|dev/releases/1]].  Package coinstallability is not a
+goal for this release.
 
 
 [wdo-ma]: http://wiki.debian.org/Multiarch
-[ma-des]: https://wiki.ubuntu.com/MultiarchSpec#Design
-[opkg-conf-arch]: http://wiki.openwrt.org/doc/techref/opkg#adjust.architectures
+[wuc-mas]: https://wiki.ubuntu.com/MultiarchSpec