Document upcoming distribution build system.

1 files changed, 101 insertions, 0 deletions

diff --git a/dev/build-sys.mdwn b/dev/build-sys.mdwn
new file mode 100644
index 0000000..651a2e1
--- /dev/null
+++ b/dev/build-sys.mdwn
@@ -0,0 +1,101 @@
+[[!meta title="Distribution Build System"]]
+
+Source package format 2.0 and opkhelper 2.0 are in development.  This page
+describes the design goals and details for the mostly rewritten version 2.0 of
+the distribution build system that is to replace opkhelper 1.0.
+
+Goals for Distribution Release 1.0
+==================================
+
+Split Codebases, Support Use of Any Build Helper
+------------------------------------------------
+
+opkhelper 1.0 included a user-facing package build program named
+**opkbuild**(1), a number of "build helper" utilities (whose names began with
+"oh-"), a couple of auxiliary utilities used by **opkbuild**(1) (whose names
+also began with "oh-"), and a rudimentary opkhelper library.
+
+This codebase will be split into two codebases: opkbuild and opkhelper.
+
+opkbuild will provide a user-facing package build program named **opkbuild**(1),
+a library named libopkbuild (with a stable versioned API and documentation for
+all public functions), and locale files for the library's output messages.  It
+may also include auxiliary utilities to be called by **opkbuild**(1) and/or
+directly by the user.
+
+opkhelper will provide a number of package build assistance utilities to be used
+by packages' `build` makefiles.  It will also provide locale files for the
+utilities' output messages.
+
+Move Common Build Logic Into Build System
+-----------------------------------------
+
+To the extent feasible, opkbuild will contain build logic common to all
+packages.  This reduces the amount of "boilerplate" commands package maintainers
+need to include in their `build` makefiles and reduces the effort needed to
+effect changes to the Packaging Policy throughout the distribution.
+
+
+Overall Build System Design
+===========================
+
+The overall process for building binary packages is as follows:
+
+    parse source package metadata (control and changelog files)
+    make the work area
+    install "src" package data files
+    generate "src" package control information
+    detect build system architecture and platform
+    determine host system architecture and platform
+    check build dependencies (for host arch)
+    parse binary package metadata (control files)
+    build list of binary packages to be built (for host arch)
+    set up package build helper, if any
+    set toolchain
+    set up build flags
+    unpack sources, if any
+    apply patches, if any
+    install platform configuration files
+    run build makefile for "build", "build-arch", or "build-indep" target
+    run build makefile for "install", "install-arch", or "install-indep" target
+    install data files for each binary package
+    post-process (e.g. compress, fix modes of, or move) data files
+    install source package documentation files
+    generate control files for each binary package
+    install maintainer scripts for each binary package
+    generate conffiles for each binary package
+    generate md5sums for each binary package
+    build opk for each binary package
+    clean work area
+
+Data files must be installed before they are post-processed in any way.  This is
+because automatic post-processing done by a build helper may move files (e.g. by
+appending ".gz" extensions to a new set of files or by moving incorrectly-placed
+manual pages into the correct section directories) and thus break old patterns
+in binary package `install` files.
+
+All of the setup that happens before the `build` makefile is actually executed
+can be performed by **opkbuild**(1).  Packages' `build` makefiles will need to
+be responsible for data file installation and post-processing.  Installation of
+source package documentation files and everything thereafter is done for every
+source package, so **opkbuild**(1) can handle those tasks.
+
+This puts **opkbuild**(1) in charge of handling the package metadata and build
+environment and leaves `build` makefiles responsible only for binary package
+data files.
+
+
+opkhelper
+=========
+
+Utilities
+---------
+
+  * oh-autoconfigure
+  * oh-autobuild
+  * oh-autotest
+  * oh-autoinstall
+  * oh-strip
+  * oh-install
+  * oh-compress
+  * oh-fixperms