Mercurial > vanilla

annotate Docs/manual.md @ 788:6a808b0ef460

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