Mercurial > vanilla

comparison Docs/manual.md @ 714:6b4ba668a43c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
vanilla: update documentation
author David Demelier <markand@malikania.fr>
date Fri, 02 Aug 2019 21:20:00 +0200
parents
children c5cbe07af6a9
comparison
equal deleted inserted replaced
713:393525a3ecc3 714:6b4ba668a43c
1 Getting started
2 ===============
3
4 This documentation explains how to write a package file from scratch.
5
6 Synopsis
7 ========
8
9 Each package lives under a dedicated directory broken down into several
10 categories. A package consists of the following files:
11
12 - NAME.sh: a pure POSIX shell that process the build and contains some
13 metadata required for installation.
14 - NAME.sha1: contains the checksums for individual source files (Optional).
15 - NAME-post.sh: a script to be executed before/after the installation
16 (Optional).
17
18 In the listing above, replace NAME with the actual package name. For example the
19 package *zlib* contains the following files:
20
21 - compression/zlib/zlib.sh
22 - compression/zlib/zlib.sha1
23
24 The build script
25 ================
26
27 The build script (NAME.sh) is a pure POSIX shell that defines various
28 information about the package and how to build it. To be included within the
29 official Vanilla Linux repository it must be licensed under the terms of the ISC
30 license.
31
32 Several templates are already available for most build systems in the Templates
33 directory.
34
35 Metadata
36 --------
37
38 A package requires several information to be installed, the following variables
39 must be present:
40
41 - PKGNAME: the package name (same as the directory).
42 - PKGVERSION: the package upstream version.
43 - PKGREVISION: the initial revision (starts at 1).
44 - PKGLICENSE: a space separated list of licenses (see licenses.md file).
45 - PKGSUMMARY: a short summary.
46
47 The following variables are optional
48
49 - PKGDEPENDS: a space separated list of packages required to build (see below).
50 - PKGDOWNLOAD: a space separated list of files to download from the web, if the
51 package does not need to download anything don't set it.
52 - PKGUIDS: a space separated list of uid to create (see below)
53 - PKGGIDS: a space separated list of gid to create (see below)
54 - PKGPROTECT: a space separated list of relative path to files to preserve on
55 installation (e.g. etc/nginx/nginx.conf)
56 - PKGOPTIONS: a space separated list of CAPITALIZED options.
57
58 Build
59 -----
60
61 To build the package, you need to define a build function that install the
62 package into the $DESTDIR variable.
63
64 Usually, the build function does:
65
66 1. Clean the build directory in case the previous build failed.
67 2. Extract distribution files.
68 3. Process build and installs into $DESTDIR.
69 4. Clean up again the build directory.
70
71 Package naming
72 ==============
73
74 The following prefixes must be used for those packages:
75
76 - py-: for python modules.
77 - py2-: for python modules (only for exceptional cases).
78 - ruby-: for native ruby modules.
79 - rubygem-: for rubygems modules.
80 - p5-: for perl 5 modules.
81 - hs-: for haskell modules.
82 - font-: for fonts (of any kind).
83
84 When a package is available with different versions (e.g. Gtk, Qt) we add the
85 major number as suffix to the PKGNAME to *old* versions. Example, if Qt 5 is the
86 current major version and Qt 4 is also shipped then, the package *qt* refers to
87 version 5 while *qt4* to version 4.
88
89 Handling dependencies
90 =====================
91
92 The variable *PKGDEPENDS* is filled up with package origins, thus you need to
93 write *lib/zlib* NOT *zlib*.
94
95 Also, the following selectors may be appended to the dependency to alter the
96 meaning:
97
98 - `:build` the dependency is only required for building,
99 - `:optional` the dependency is optional and not strictly required.
100 - `:recommended` same as optional but installed by default.
101
102 Example:
103
104 PKGDEPENDS="dev/cmake:build graphics/qt5:recommended lib/zlib"
105
106 Protected files
107 ===============
108
109 Configuration files (usually everything under /etc) must be marked as well in
110 *PKGPROTECT* variables. This prevents `vpk` for overriding user configurations.
111
112 Note: if the package ships a init script file, it must be marked as well.
113
114 Example:
115
116 PKGPROTECT="etc/nginx.conf etc/rc.d/nginx"
117
118 In this case, `vpk` will rename the file to *etc/nginx.conf.vpk* and
119 */etc/rc.d/nginx.vpk* in the archive and only be renamed if they are not present
120 on the disk or not manually modified.
121
122 Uids / Gids
123 ===========
124
125 If the package requires UNIX users and groups, adapt the *PKGUIDS* and *PKGGIDS*
126 variables as a space separated list. You can assign a default numeric id using
127 the syntax `:number`.
128
129 Example:
130
131 PKGUIDS="messagebus" # vpk will assign an id
132 PKGUIDS="gdm:55" # vpk will use 55
133
134 Warning: if you need to change file permissions, do it *ONLY* in a post install
135 script as users may have set different numeric id than the package defaults.
136
137 Once you need a new UID/GID, edit the file UIDS.md in this directory as well.
138
139 Options
140 =======
141
142 ...
143
144 Example with network/wget:
145
146 # cd network/wget
147 # SSL=openssl NLS=no vpk build
148
149 Add the desired options in *PKGOPTIONS* variable and don't forget to set default
150 values.
151
152 Example with NLS
153
154 PKGOPTIONS="NLS"
155
156 : ${NLS:=yes}
157
158 if [ "$NLS" = "yes" ]; then
159 PKGDEPENDS="core/gettext $PKGDEPENDS"
160 with_nls="--enable-nls"
161 else
162 with_nls="--disable-nls"
163 fi
164
165 Then at configure step:
166
167 ./configure $with_nls
168
169 Proper handling of options is done by explicitly disabling/enabling options.
170 Most programs will try to enable/disable features depending on what is available
171 on the system thus, if the package finds a dependency and enable it you need to
172 adapt *PKGDEPENDS*. Always check what options are available in the package and
173 use their default as explicit knobs to avoid invisible dependencies.
174
175 See the file options.md for predefined options and proper naming.
176
177 Paths
178 =====
179
180 The package must ensure appropriate directories for installing files. This
181 includes:
182
183 - /etc/rc.d for service files
184 - /lib/pkgconfig: for .pc files
185 - /lib/cmake: for CMake config files
186 - /lib: for libraries (no lib64 suffix)
187 - /share/locale: for NLS files
188 - /share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form)
189 - /share/doc/PKGNAME (exact directory, no version)
190
191 Keep neutral
192 ============
193
194 Do not make any modifications to the package. Keep it as close to upstream as
195 possible. Only minor tweaks are allowed including:
196
197 - adjusting pid/uid/gid in a default configuration file for easier deployment
198 (but not on the original file example)
199 - disabling static libraries
200 - making sure paths are consolidated
201 - making sure system libraries are used rather than in-source bundles
202
203 Services
204 ========
205
206 Services files must be installed in /etc/rc.d. You must use the following
207 conventions regarding messages the service will print.
208
209 The script must at least support start, stop and restart.
210
211 #### start (required)
212
213 Always add arguments with the invocation.
214
215 Starting foo: /bin/foo -d
216
217 #### stop (required)
218
219 If the service is not running, don't write any message. Otherwise write:
220
221 Stopping foo.
222
223 #### restart (required)
224
225 Basically, this command just calls stop and start.
226
227 Stopping foo.
228 Starting foo: /bin/foo -d
229
230 #### status
231
232 Depending on the status, write the following messages.
233
234 foo is running with pid: 1234
235 foo is not running
236
237 #### usage
238
239 If the script is invoked with invalid arguments or none, write the usage like
240 this through stderr and exit 1. Also keep all subcommands sorted.
241
242 usage: foo restart|start|status|stop
243
244 If your script may support additional operations, messages and usage are up to
245 the maintainer discretion.
246
247 See also the template file in Templates/rc.
248
249 Libraries
250 =========
251
252 Do not ship static libraries and libtool files. Make sure your build script
253 suppress static builds if possible or delete the .a file.
254
255 Note: the C and C++ library are shipped for technical reasons though.
256
257 Post install scripts
258 ====================
259
260 If you need to perform some custom steps after the installation of the binary
261 package in the target systems, you may create the NAME-post.sh script. This
262 script must be written also in pure POSIX shell language.
263
264 As unique argument, `vpk` will provide one of these to the post script:
265
266 - pre-install: before the extraction of the package.
267 - post-install: after the extraction of the package.
268 - pre-uninstall: before removing the package.
269 - post-uninstall: after the removal of the package.
270
271 Note: if the package wants to call a binary from an other package, it is usually
272 a good idea to check it's presence first.
273
274 Example:
275
276 #!/bin/sh
277
278 if [ -x /bin/gtk-update-icon-cache ]; then
279 gtk-update-icon-cache -vf /share/icons/hicolor
280 fi
281
282 Desktop files
283 =============
284
285 We usually never add .desktop files for any package that doesn't provide one by
286 itself. This also includes terminal based applications.
287
288 If a .desktop is provided by the package, make sure though that it is valid and
289 specifies the appropriate category (i.e. it does not appear in multiple menus at
290 once).
291
292 See [desktop entry specification][] for more information.
293
294 [desktop entry specification]: https://specifications.freedesktop.org/desktop-entry-spec/latest