vanilla

David Demelier 2019-07-18 Parent:860ab66f5f71

606:25cecc6dca48 Go to Latest

vanilla/HOWTO.md

vanilla: use POSIX shell and busybox tar

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