Mercurial > vanilla
comparison HOWTO.md @ 349:7b000befead5
vanilla: improve docs and hierarchy
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 28 Mar 2019 20:15:00 +0100 |
parents | |
children | 0b7acfc69fec |
comparison
equal
deleted
inserted
replaced
348:c669b5463d04 | 349:7b000befead5 |
---|---|
1 # vanilla HOWTO | |
2 | |
3 This documentation explains how to write a package file. | |
4 | |
5 Each package lives under a dedicated directory broken down into several | |
6 categories. Change the directory to the desired package and use `vpk build` to | |
7 construct a package. The repository does not contain the distribution files from | |
8 upstream but `vpk build` will download them for you if not present (see also | |
9 `vpk download` command). | |
10 | |
11 Note: vpk build does not handle dependencies. | |
12 | |
13 Example with lib/zlib | |
14 | |
15 # cd lib/zlib | |
16 # vpk build | |
17 | |
18 If build succeeded, you can install the package as | |
19 /tmp/vpk/zlib#version-revision-arch.txz | |
20 | |
21 Tip: you can use `vpk build -q` to silent the process. | |
22 | |
23 # How to create a new package | |
24 | |
25 To create a new package, create a directory in the appropriate category | |
26 directory. Then create the sscript file. See Templates directory. | |
27 | |
28 Example, if you want to create a package abc in category lib you must have the | |
29 following files. | |
30 | |
31 lib/abc | |
32 lib/abc/abc.sh | |
33 | |
34 The following variables must be present: | |
35 | |
36 - PKGNAME: the package name | |
37 - PKGVERSION: the package upstream version | |
38 - PKGREVISION: the vanilla revision (starts at 1) | |
39 - PKGLICENSE: a space separated list of licenses (see README.licenses.md) | |
40 - PKGSUMMARY: a short summary | |
41 | |
42 The following variables are optional | |
43 | |
44 - PKGDEPENDS: a space separated list of packages required to build. Use the | |
45 syntax category/package for runtime requirement (includes building too) and | |
46 category/package:build for build requirement only. | |
47 - PKGDOWNLOAD: a space separated list of files to download from the web, if the | |
48 package does not need to download anything don't set it. | |
49 - PKGUIDS: a space separated list of uid to create | |
50 - PKGGIDS: a space separated list of gid to create | |
51 - PKGPROTECT: a space separated list of relative path to files to preserve on | |
52 installation (e.g. etc/nginx/nginx.conf) | |
53 - PKGOPTIONS: a space separated list of CAPITALIZED options. | |
54 | |
55 The script file is the build procedure for the package. It must be as simple as | |
56 possible as its sole purpose is to build and install files through the DESTDIR | |
57 variable. | |
58 | |
59 There are already various of templates in the templates/ directory. | |
60 | |
61 # Topics | |
62 | |
63 ## Licenses | |
64 | |
65 Use the following licenses in *PKGLICENSE* or CUSTOM. | |
66 | |
67 - AGPLv3 | |
68 - AGPLv3+ | |
69 - APACHE10 | |
70 - APACHE11 | |
71 - APACHE20 | |
72 - BOOST | |
73 - BSD | |
74 - BSD2CLAUSE | |
75 - BSD3CLAUSE | |
76 - BSD4CLAUSE | |
77 - GFDL | |
78 - GPLv1 | |
79 - GPLv1+ | |
80 - GPLv2 | |
81 - GPLv2+ | |
82 - GPLv3 | |
83 - GPLv3+ | |
84 - ISC | |
85 - LGPLv20 | |
86 - LGPLv20+ | |
87 - LGPLv21 | |
88 - LGPLv21+ | |
89 - LGPLv3 | |
90 - LGPLv3+ | |
91 - MIT | |
92 - UNLICENSE | |
93 | |
94 ## Dependencies | |
95 | |
96 The variable *PKGDEPENDS* is filled up with package origins, thus you need to | |
97 write *lib/zlib* NOT *zlib*. | |
98 | |
99 Also, the following qualifiers may be appended to the dependency to alter the | |
100 meaning: | |
101 | |
102 - `:build` the dependency is only required for building, | |
103 - `:optional` the dependency is optional and not strictly required. | |
104 - `:recommended` same as optional but installed by default. | |
105 | |
106 Example: | |
107 | |
108 PKGDEPENDS="dev/cmake:build graphics/qt5:recommended lib/zlib" | |
109 | |
110 ## Configuration files | |
111 | |
112 Configuration files (usually everything under /etc) must be marked as well in | |
113 *PKGPROTECT* variables. This prevents `vpk` for overriding user configurations. | |
114 | |
115 Note: if the package ships a init script file, it must be marked as well. | |
116 | |
117 Example: | |
118 | |
119 PKGPROTECT="/etc/nginx.conf /etc/rc.d/nginx" | |
120 | |
121 ## Uids / Gids | |
122 | |
123 If the package requires UNIX users and groups, adapt the *PKGUIDS* and *PKGGIDS* | |
124 variables as a space separated list. You can assign a default numeric id using | |
125 the syntax `:number`. | |
126 | |
127 Example: | |
128 | |
129 PKGUIDS="messagebus" # vpk will assign an id | |
130 PKGUIDS="gdm:55" # vpk will use 55 | |
131 | |
132 Warning: if you need to change file permissions, do it *ONLY* in a post install | |
133 script as users may have set different numeric id than the package defaults. | |
134 | |
135 ## Options | |
136 | |
137 Some packages are configurable via compile time options. Check the variable | |
138 PKGOPTIONS in the script file and read the associated documentation for more | |
139 explanation. Options are usually passed as environment variables | |
140 | |
141 Example with network/wget: | |
142 | |
143 # cd network/wget | |
144 # SSL=openssl NLS=no vpk build | |
145 | |
146 Add the desired options in *PKGOPTIONS* variable and don't forget to set default | |
147 values. | |
148 | |
149 Example with NLS | |
150 | |
151 PKGOPTIONS="NLS" | |
152 | |
153 : ${NLS:=yes} | |
154 | |
155 if [ "$NLS" = "yes" ]; then | |
156 PKGDEPENDS="core/gettext $PKGDEPENDS" | |
157 with_nls="--enable-nls" | |
158 else | |
159 with_nls="--disable-nls" | |
160 fi | |
161 | |
162 Then at configure step: | |
163 | |
164 ./configure $with_nls | |
165 | |
166 Proper handling of options is done by explicitly disabling/enabling options. | |
167 Most programs will try to enable/disable features depending on what is available | |
168 on the system thus, if the package finds a dependency and enable it you need to | |
169 adapt *PKGDEPENDS*. Always check what options are available in the package and | |
170 use their default as explicit knobs to avoid invisible dependencies. | |
171 | |
172 Use the following predefined options before creating your own. | |
173 | |
174 - ACL: enable access control list support | |
175 - BLUETOOTH: enable bluetooth support | |
176 - BZIP2: enable bzip2 compression support | |
177 - DBUS: enable D-Bus support | |
178 - DOXYGEN: enable doxygen documentation support | |
179 - DRM: enable direct rendering manager support | |
180 - DTD: enable XML validation support | |
181 - EGL: enable EGL support | |
182 - FONTCONFIG: enable fontconfig support | |
183 - FREETYPE: enable freetype support | |
184 - GALLIUM: enable LLVM gallium support | |
185 - GDBM: enable GNU database support | |
186 - GLAMOR: enable 2D graphics support | |
187 - GLES2: enable GLES2 support | |
188 - GLES3: enable GLES3 support | |
189 - GMP: enable GNU multiple precision library | |
190 - GTK2: enable Gtk 2 toolkit support | |
191 - GTK3: enable Gtk 3 toolkit support | |
192 - GTK4: enable Gtk 4 toolkit support | |
193 - GUILE: enable GNU guile support | |
194 - IDN2: enable libidn2 support | |
195 - KMS: enable kernel mode settings support | |
196 - LLVM: enable LLVM support | |
197 - LZ4: enable lz4 compression support | |
198 - LZMA: enable lzma compression support | |
199 - MNL: enable netlink minimalistic library support | |
200 - NLS: enable native language support | |
201 - PAM: enable PAM support | |
202 - PCRE: enable perl-like regular expression support | |
203 - PULSEAUDIO: enable PulseAudio support | |
204 - PYTHON: enable Python 3 bindings or support | |
205 - QT5: enable Qt 5 toolkit support | |
206 - SPHINX: enable sphinx documentation support | |
207 - SSH: enable SSH support | |
208 - SSL: enable SSL/TLS, some packages offer several choices (e.g. openssl, gnutls) | |
209 - UDEV: enable eudev support | |
210 - UUID: enable UUID support | |
211 - WACOM: enable wacom support | |
212 - WAYLAND: enable wayland support | |
213 - X: enable X.Org support | |
214 - XML: enable XML support | |
215 - XZ: enable XZ support | |
216 - ZLIB: enable zlib compression support | |
217 - ZSTD: enable zstd compression support | |
218 | |
219 Always try to make an option easy to understand and not package specific. For | |
220 example BLUETOOTH is preferred over BLUEZ because a user knows what bluetooth is | |
221 but may not know that bluez is the current reference implementation. Also, it is | |
222 preferred to make an option generic to allow multiple values in case the | |
223 package offers it. | |
224 | |
225 Example, if a package offers different implementations for SSL, consider the | |
226 option with a value (e.g. SSL=openssl, SSL=gnutls, and such). | |
227 | |
228 Also, if a package offers different implementations that can be enabled all | |
229 together, use a list separated by space (e.g. XML="libxml2 expat"). | |
230 | |
231 Those options should only change the package behaviour, for example: manual | |
232 pages or any other resource files that are not strictly required; they must be | |
233 installed and the user may exclude them via `vpk` instead. | |
234 | |
235 The following options should be available for any package that builds C or C++ | |
236 code: | |
237 | |
238 - CBUILD: build system (usually ARCH-linux-musl) | |
239 - CHOST: host system (usually ARCH-linux-musl) | |
240 - CTARGET: target system (usually ARCH-linux-musl) | |
241 - CC: C compiler (defaults to gcc) | |
242 - CFLAGS: C flags (defaults to -O2) | |
243 - CXX: C++ compiler (defaults to g++) | |
244 - CXXFLAGS: C++ flags (defaults to -O2) | |
245 | |
246 ## Keep vanilla | |
247 | |
248 Do not make any modifications to the package. Keep it as close to upstream as | |
249 possible. Only minor tweaks are allowed including: | |
250 | |
251 - adjusting pid/uid/gid in a default configuration file for easier deployment | |
252 (but not on the original file example) | |
253 - disabling static libraries | |
254 - making sure paths are consolidated | |
255 - making sure system libraries are used rather than in-source bundles | |
256 | |
257 ## Package naming | |
258 | |
259 The following prefixes must be used for those packages: | |
260 | |
261 - py-: for python modules | |
262 - ruby-: for native ruby modules | |
263 - rubygem-: for rubygems modules | |
264 - p5-: for perl 5 modules | |
265 - hs-: for haskell modules | |
266 - font-: for fonts (of any kind) | |
267 | |
268 When a package is available with different versions (e.g. Gtk, Qt) we add the | |
269 major number as suffix to the PKGNAME to *old* versions. Example, if Qt 5 is the | |
270 current major version and Qt 4 is also shipped then, the package *qt* refers to | |
271 version 5 while *qt4* to version 4. | |
272 | |
273 ## Paths | |
274 | |
275 The package must ensure appropriate directories for installing files. This | |
276 includes: | |
277 | |
278 - /etc/rc.d for service files | |
279 - /usr/lib/pkgconfig: for .pc files | |
280 - /usr/lib/cmake: for CMake config files | |
281 - /usr/lib: for libraries (no lib64 suffix) | |
282 - /usr/share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form) | |
283 - /usr/share/doc/PKGNAME (exact directory, no version) | |
284 | |
285 ## Services | |
286 | |
287 Services files must be installed in /etc/rc.d. You must use the following | |
288 conventions regarding messages the service will print. | |
289 | |
290 The script must at least support start, stop and restart. | |
291 | |
292 #### start (required) | |
293 | |
294 Always add arguments with the invocation. | |
295 | |
296 Starting foo: /usr/bin/foo -d | |
297 | |
298 #### stop (required) | |
299 | |
300 If the service is not running, don't write any message. Otherwise write: | |
301 | |
302 Stopping foo. | |
303 | |
304 #### restart (required) | |
305 | |
306 Basically, this command just calls stop and start. | |
307 | |
308 Stopping foo. | |
309 Starting foo: /usr/bin/foo -d | |
310 | |
311 #### status | |
312 | |
313 Depending on the status, write the following messages. | |
314 | |
315 foo is running with pid: 1234 | |
316 foo is not running | |
317 | |
318 #### usage | |
319 | |
320 If the script is invoked with invalid arguments or none, write the usage like | |
321 this through stderr and exit 1. Also keep all subcommands sorted. | |
322 | |
323 usage: foo restart|start|status|stop | |
324 | |
325 If your script may support additional operations, messages and usage are up to | |
326 the maintainer discretion. | |
327 | |
328 See also the template file as Templates/rc. | |
329 | |
330 ## Static libraries and libtool files | |
331 | |
332 Do not ship static libraries and libtool files. Make sure your build script | |
333 suppress static builds if possible or delete the .a file. | |
334 | |
335 Note: the C and C++ library are shipped for technical reasons though. | |
336 | |
337 ## Don't delete blindly | |
338 | |
339 Do never delete global files through the prefix installation as some people may | |
340 use scripts directly for the system. | |
341 | |
342 Example (BAD): | |
343 | |
344 rm -f $DESTDIR/usr/lib/*.la | |
345 | |
346 Example (BETTER): | |
347 | |
348 rm -f $DESTDIR/usr/lib/libfoo.la | |
349 | |
350 Assuming the package is "foo". |