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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
[[!meta title="Simpler Platform Porting"]]
ProteanOS is unique as a purely binary distribution that is also highly
configurable. It's easy to install on a supported computer. But its nature
makes it not so easy to [[port it to a new computer|doc/plat/porting]].
There are four main steps to porting ProteanOS to a new platform:
1. **Configure**: First, the platform-specific source packages (`busybox` and
`linux-libre`) need to be configured for the new platform.
2. **Build**: Next, those platform-specific packages need to be built for the
new platform.
3. **Install**: Then, a bootable ProteanOS system with the newly built
platform-specific binary packages needs to be installed.
4. **Test**: Finally, the ProteanOS system can be booted and the features of
the new platform can be tested.
If any issues are found in testing, the process returns to step one. If not,
the `config-*` source package for the new platform may be sent for inclusion in
ProteanOS.
Testing is the easy part and will not be discussed for the remainder of this
document.
The currently [[documented|doc/plat/porting]] method for porting ProteanOS
blurs the first two steps and involves a hack to hide from opkbuild the
`platconf` file(s) of the package(s) being configured. The hardest and least
well documented part of the current method is the installation step.
The rest of this document specifies potential improvements to the platform
porting process, organized by steps of the process.
Configuration
=============
Interface
---------
The porter runs `ppt-make` (from the `platconf-pkg-tools` package) or a similar
tool to generate a basic configuration package.
The porter then runs a command which presents the configuration options of
platform-specific packages using kconfig's `mconf` utility (as seen when running
`make menuconfig` in Linux-libre, BusyBox, and other packages).
Implementation: Maintaining Platform-Specific Packages
------------------------------------------------------
A new [`kbuild-kconfig` package][kbuild-kconfig] is built and uploaded,
providing standalone versions of the Kconfig programs from Linux, as well as a
[kconfigpp][] preprocessor to extract a single complete Kconfig file from a
source tree, handling `source` directives (as in Linux-libre) and generating
Kconfig directives from `//config:` comments in source files (as in BusyBox).
Source packages with `platconf` files (currently `busybox` and `linux-libre`)
are modified to `Build-Depend` on `kbuild-kconfig` and to build `*-kconfig`
packages (`Architecture: any` and `Platform: platconf`) containing Kconfig input
files generated from the upstream source tree by kconfigpp.
[SPF 2.0 ยง 4.6][spf-2.0-src-ver] is amended to allow `~<dist>~<distrev>` in
addition to `+<dist>~<distrev>`. opkbuild is modified to allow the same.
Then, when a new upstream version of a source package with a `platconf` file
(e.g. `linux-libre`) is prepared, `~platconf~1` is appended to its version
string and the distribution in `changelog` is set to `platconf` (instead of
`trunk`). The package is built for the `platconf` platform of all architectures
and uploaded (source and binary packages) to the package archive, where it will
be included in the `dev/platconf` suite (instead of `dev/trunk`).
The reason for the `~` in the version string is as follows. The version that
will later be uploaded to `dev/trunk` should replace the version uploaded to
`dev/platconf`; that is, the former needs to have a later version string.
Versions can be compared with opkg's `compare-versions` subcommand:
# opkg compare-versions '3.10.55~gnu-1' '<<' '3.10.60~gnu-1' && echo false || echo true
true
Appending a distribution revision with `+` is to be done for distributions that
are downstream of `dev/trunk`, like `dev/rs1`. It won't work for distributions
that are upstream of `dev/trunk`, like `dev/platconf`:
# opkg compare-versions '3.10.60~gnu-1+platconf~1' '<<' '3.10.60~gnu-1' && echo false || echo true
false
Instead, we need a different character, like `~`. A version with `~platconf~1`
can replace a version without a distribution revision (a version in
`dev/trunk`):
# opkg compare-versions '3.10.60~gnu-1~platconf~1' '<<' '3.10.60~gnu-1' && echo false || echo true
true
Debian also appends distribution revisions with `~` to the version strings of
packages uploaded to its `experimental` distribution.
[kbuild-kconfig]: http://git.proteanos.com/users/pehjota/kbuild-kconfig.git/
[kconfigpp]: http://git.proteanos.com/users/pehjota/kbuild-kconfig.git/tree/kconfigpp/kconfigpp.sh
[spf-2.0-src-ver]: http://specs.proteanos.com/spf-2.0/metadata.html#src-ver
Implementation: Maintaining Platform Ports
------------------------------------------
The `opkg` binary package provides a `/usr/bin/opkg` wrapper script that
combines configuration files under `/etc/opkg/` to form a temporary
configuration file for `/usr/bin/opkg-cl`. It also provides a new
`/usr/bin/opkg-feed` script (similar to Ubuntu's add-apt-repository) that
manages `src` options in opkg configuration files, e.g. to add a new packages
feed. The syntax for adding a feed is `opkg-feed -a <suite> <arch> <plat>
<sect>`. Following is an example usage, for adding feeds for platform porting:
# opkg-feed -a dev/platconf src all base
# opkg-feed -a dev/platconf i686-linux-glibc platconf base
# opkg update
`ppt-make` (which generates a new `config-*` package) from `platconf-pkg-tools`
asks two more questions: the architecture of the platform and the name of an
existing platform on which to base the new one. `ppt-make` runs opkg-feed to
add the necessary feeds and then opkg to install the `config-*` package for the
platform the user specifies.
A new `ppt-configure` tool is added to `platconf-pkg-tools`. This tool finds
and installs all of the available `*-kconfig` packages, builds a single unified
Kconfig input file from those of the `*-kconfig` packages, runs `mconf` on the
generated Kconfig file, and splits the `.config` file the user saves into files
in `src/build/<package>/<version>/`, where `<package>` is the name of the
configurable source package (e.g. `linux-libre`) and `<version>` is the upstream
version of the package (e.g. `3.10.60~gnu`).
Building
========
Interface
---------
The porter runs a command which builds their `config-*` package, installs the
resulting binary packages, and builds platform-specific packages for the new
platform.
Implementation
--------------
Installation
============
Interface
---------
The porter runs a command and specifies a block device to use, and a ProteanOS
system with the newly built platform-specific packages is installed and ready to
boot.
Implementation
--------------
|
