summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--dev/build-sys.mdwn101
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