Mercurial > vanilla

comparison HOWTO.md @ 349:7b000befead5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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".