Mercurial > vanilla

annotate Docs/manual.md @ 1018:a0efa9896267

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
vanilla: cleanup trailing spaces
author David Demelier <markand@malikania.fr>
date Thu, 29 Aug 2019 23:30:00 +0200
parents c5cbe07af6a9
children 120e458a2e33
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
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
142 If the package offer build options, edit the *PKGOPTIONS* variable and always
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
143 add default values that match upstream if possible. Boolean options must always
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
144 be considered as *yes* or *no*. If an option requires a list, use a space
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
145 separated list of values.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
146
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
147 Example:
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
148
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
149 PKGOPTIONS="NLS DRIVERS"
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
150
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
151 : ${NLS:=yes}
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
152 : ${DRIVERS:=amd intel}
714
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 if [ "$NLS" = "yes" ]; then
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
155 PKGDEPENDS="core/gettext $PKGDEPENDS"
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
156 with_nls="--enable-nls"
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
157 else
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
158 with_nls="--disable-nls"
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
159 fi
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
160
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
161 Then at configure step:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
162
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 ./configure $with_nls
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 Proper handling of options is done by explicitly disabling/enabling options.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
166 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
167 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
168 adapt *PKGDEPENDS*. Always check what options are available in the package and
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
169 use their default as explicit knobs to avoid invisible dependencies.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
170
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
171 See the file options.md for predefined options and proper naming.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
172
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
173 Paths
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
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
176 The package must ensure appropriate directories for installing files. This
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
177 includes:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
178
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
179 - /etc/rc.d: for service files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
180 - /lib/pkgconfig: for .pc files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
181 - /lib/cmake: for CMake config files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
182 - /lib: for libraries (no lib64 suffix),
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
183 - /share/PKGNAME: data directory (if applicable),
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
184 - /share/locale: for NLS files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
185 - /share/man/man{1,2,3,4,5,6,7,8}: for man pages (in uncompressed form),
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
186 - /share/doc/PKGNAME (exact directory, no version): arbitrary documentation.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
187
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
188 Keep neutral
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
189 ============
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 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
192 possible. Only minor tweaks are allowed including:
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 - adjusting pid/uid/gid in a default configuration file for easier deployment
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
195 (but not on the original file example),
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
196 - making sure paths are consolidated,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
197 - making sure system libraries are used rather than in-source bundles,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
198 - replacing PAM files (see below).
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
199
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
200 PAM files
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
201 =========
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
202
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
203 The PAM system is an flexible and well designed authentication tool, it has a
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
204 large number of modules and configuration settings. This complexity leads to
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
205 inconsistent upstream PAM files that are not always compatible with the default
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
206 Vanilla Linux generic's files, therefore you *must* always replace the provided
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
207 PAM files with custom alternatives and sane defaults. In general, LFS is a good
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
208 recommandation regarding PAM files.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
209
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
210 Also, don't forget to add PAM files to the *PKGPROTECT* variable as they are
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
211 meant to be edited by the system administrator.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
212
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
213 Patches
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
214 =======
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
215
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
216 If a software requires patching, always try to see if there is already an
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
217 upstream patch that fixes the issue. If not, you may check how other Linux
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
218 distributions fix the problem with a local workaround.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
219
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
220 Then, please consider sending the patch to the upstream if applicable.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
221
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
222 Patches must be named in the form *patch-category.patch*. We encourage old style
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
223 of patches that you usually create by editing the file and comparing with the
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
224 original one.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
225
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
226 Example:
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
227
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
228 cp Makefile.orig Makefile
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
229 vim Makefile
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
230 diff -ub Makefile.orig Makefile > patch-musl.patch
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
231
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
232 Warning: by default busybox patch is used and is much stricter than standalone
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
233 counterpart, in doubt always try to apply the patch manually with
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
234 busybox patch and edit if required.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
235
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
236 The following names are recommended depending on the situation:
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
237
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
238 - patch-fhs.patch: when a patch is required to adapt installation/usage to the
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
239 Vanilla Linux file system hierarchy,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
240 - patch-musl.patch: when the code assume a glibc specific code,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
241 - patch-clang.patch: when the code does not compile with LLVM/Clang. Make sure
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
242 the patch does not break GCC, if it does apply the patch in a conditional.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
243
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
244 Also, do not create a patch for individual files if they all belong to the same
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
245 category. For example, if several source files require patching to build against
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
246 musl, use only one *patch-musl.patch* file.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
247
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
248 Services
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
249 ========
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
250
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
251 Services files must be installed in /etc/rc.d in the mode 0644.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
252
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
253 Example:
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
254
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
255 install -Dm0644 food $DESTDIR/etc/rc.d/food
714
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 The script must at least support start, stop and restart.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
258
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
259 UX style
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
260 --------
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
261
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
262 You must use the following conventions regarding messages the service will
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
263 print.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
264
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
265 ### start (required)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
266
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
267 Always add arguments with the invocation.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
268
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
269 Starting foo: /bin/foo -d
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
270
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
271 If the service is already running, show:
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
272
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
273 foo is already running with pid: 1234
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
274
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
275 ### stop (required)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
276
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
277 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
278
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
279 Stopping foo.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
280
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
281 ### restart (required)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
282
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
283 Basically, this command just calls stop and start.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
284
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
285 Stopping foo.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
286 Starting foo: /bin/foo -d
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
287
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
288 ### status (recommended)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
289
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
290 Depending on the status, write the following messages.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
291
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
292 foo is running with pid: 1234
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
293 foo is not running
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
294
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
295 ### usage (required)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
296
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
297 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
298 this through stderr and exit 1. Also keep all subcommands sorted.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
299
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
300 usage: foo restart|start|status|stop
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
301
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
302 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
303 the maintainer discretion.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
304
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
305 See also the template file in Templates/rc.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
306
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
307 Libtool files
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
308 =============
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
309
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
310 Do not ship libtool files.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
311
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
312 Manual pages
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
313 ============
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
314
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
315 Do never install compressed manual pages. The `vpk` tool performs automatic
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
316 compression on installation depending on the user setting. Check how to disable
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
317 compression in the package or decompress them after installation in the
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
318 destination directory.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
319
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
320 Post install scripts
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
321 ====================
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
322
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
323 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
324 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
325 script must be written also in pure POSIX shell language.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
326
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
327 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
328
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
329 - pre-install: before the extraction of the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
330 - post-install: after the extraction of the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
331 - pre-uninstall: before removing the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
332 - post-uninstall: after the removal of the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
333
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
334 Note: if the package wants to call a binary from an other package, it is usually
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
335 a good idea to check it's presence first.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
336
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
337 Example:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
338
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
339 #!/bin/sh
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
340
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
341 if [ -x /bin/gtk-update-icon-cache ]; then
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
342 gtk-update-icon-cache -vf /share/icons/hicolor
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
343 fi
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
344
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
345 Desktop files
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
346 =============
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
347
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
348 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
349 itself. This also includes terminal based applications.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
350
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
351 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
352 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
353 once).
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
354
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
355 See [desktop entry specification][] for more information.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
356
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
357 [desktop entry specification]: https://specifications.freedesktop.org/desktop-entry-spec/latest