summaryrefslogtreecommitdiffstats
path: root/dev/build-sys.mdwn
blob: 651a2e1397d1fcb513a63d9b20be98c46b29124f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
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