Mercurial > vanilla

annotate Docs/manual.md @ 1231:1b84538ac65c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
python/python2: upgrade to 2.7.18
author David Demelier <markand@malikania.fr>
date Sat, 30 Oct 2021 10:24:16 +0200
parents 8cbb83c16868
children
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.
1178
8cbb83c16868 vanilla: add PKGWWW in templates
David Demelier <markand@malikania.fr>
parents: 1165
diff changeset
46 - PKGWWW: the project homepage with the scheme (e.g. http://example.org).
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
47
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 The following variables are optional
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
49
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 - PKGDEPENDS: a space separated list of packages required to build (see below).
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 - 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
52 package does not need to download anything don't set it.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 - PKGUIDS: a space separated list of uid to create (see below)
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 - PKGGIDS: a space separated list of gid to create (see below)
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 - 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
56 installation (e.g. etc/nginx/nginx.conf)
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 - PKGOPTIONS: a space separated list of CAPITALIZED options.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
58
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 Build
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
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 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
63 package into the $DESTDIR variable.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
64
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 Usually, the build function does:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
66
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 1. Clean the build directory in case the previous build failed.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 2. Extract distribution files.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 3. Process build and installs into $DESTDIR.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 4. Clean up again the build directory.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
71
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
72 Package naming
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
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 The following prefixes must be used for those packages:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
76
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 - py-: for python modules.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 - py2-: for python modules (only for exceptional cases).
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
79 - ruby-: for native ruby modules.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 - rubygem-: for rubygems modules.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 - p5-: for perl 5 modules.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 - hs-: for haskell modules.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 - font-: for fonts (of any kind).
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
84
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 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
86 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
87 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
88 version 5 while *qt4* to version 4.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
89
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
90 Handling dependencies
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
1080
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
93 Add any dependencies the packages requires in *PKGDEPENDS* variable.
714
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
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 Example:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
102
1080
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
103 PKGDEPENDS="cmake:build qt5:optional zlib"
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
104
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
105 The following dependencies are implicit and must *never* be marked in
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
106 *PKGDEPENDS*:
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
107
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
108 - autoconf
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
109 - automake
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
110 - busybox
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
111 - clang
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
112 - compiler-rt
1106
477457540aa0 vanilla: update implicit dependencies paragraph
David Demelier <markand@malikania.fr>
parents: 1080
diff changeset
113 - etc
1080
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
114 - filesystem
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
115 - libc++
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
116 - libc++abi
1106
477457540aa0 vanilla: update implicit dependencies paragraph
David Demelier <markand@malikania.fr>
parents: 1080
diff changeset
117 - libtool (except linked to it)
1080
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
118 - libunwind
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
119 - lld
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
120 - musl
120e458a2e33 vanilla: update manual page with implicit dependencies
David Demelier <markand@malikania.fr>
parents: 821
diff changeset
121 - pkgconf
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
122
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
123 Protected files
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
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 Configuration files (usually everything under /etc) must be marked as well in
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 *PKGPROTECT* variables. This prevents `vpk` for overriding user configurations.
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 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
130
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 Example:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
132
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
133 PKGPROTECT="etc/nginx.conf etc/rc.d/nginx"
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
134
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
135 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
136 */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
137 on the disk or not manually modified.
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 Uids / Gids
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 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
143 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
144 the syntax `:number`.
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 Example:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
147
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
148 PKGUIDS="messagebus" # vpk will assign an id
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
149 PKGUIDS="gdm:55" # vpk will use 55
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 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
152 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
153
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
154 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
155
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
156 Options
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
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
159 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
160 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
161 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
162 separated list of values.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
163
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
164 Example:
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
165
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
166 PKGOPTIONS="NLS DRIVERS"
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
167
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
168 : ${NLS:=yes}
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
169 : ${DRIVERS:=amd intel}
714
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 if [ "$NLS" = "yes" ]; then
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
172 PKGDEPENDS="core/gettext $PKGDEPENDS"
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
173 with_nls="--enable-nls"
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
174 else
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
175 with_nls="--disable-nls"
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
176 fi
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
177
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
178 Then at configure step:
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 ./configure $with_nls
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
181
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
182 Proper handling of options is done by explicitly disabling/enabling options.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
183 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
184 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
185 adapt *PKGDEPENDS*. Always check what options are available in the package and
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
186 use their default as explicit knobs to avoid invisible dependencies.
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 See the file options.md for predefined options and proper naming.
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 Paths
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
191 =====
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 The package must ensure appropriate directories for installing files. This
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
194 includes:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
195
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
196 - /etc/rc.d: for service files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
197 - /lib/pkgconfig: for .pc files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
198 - /lib/cmake: for CMake config files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
199 - /lib: for libraries (no lib64 suffix),
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
200 - /share/PKGNAME: data directory (if applicable),
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
201 - /share/locale: for NLS files,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
202 - /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
203 - /share/doc/PKGNAME (exact directory, no version): arbitrary documentation.
714
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 Keep neutral
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
206 ============
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
207
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
208 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
209 possible. Only minor tweaks are allowed including:
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 - 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
212 (but not on the original file example),
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
213 - making sure paths are consolidated,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
214 - 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
215 - replacing PAM files (see below).
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
216
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
217 PAM files
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
218 =========
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 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
221 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
222 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
223 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
224 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
225 recommandation regarding PAM files.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
226
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
227 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
228 meant to be edited by the system administrator.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
229
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
230 Patches
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
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
233 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
234 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
235 distributions fix the problem with a local workaround.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
236
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
237 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
238
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
239 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
240 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
241 original one.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
242
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
243 Example:
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
244
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
245 cp Makefile.orig Makefile
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
246 vim Makefile
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
247 diff -ub Makefile.orig Makefile > patch-musl.patch
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
248
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
249 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
250 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
251 busybox patch and edit if required.
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 The following names are recommended depending on the situation:
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 - 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
256 Vanilla Linux file system hierarchy,
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
257 - 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
258 - 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
259 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
260
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
261 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
262 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
263 musl, use only one *patch-musl.patch* file.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
264
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
265 Services
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
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
268 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
269
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
270 Example:
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
271
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
272 install -Dm0644 food $DESTDIR/etc/rc.d/food
714
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 The script must at least support start, stop and restart.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
275
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
276 UX style
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
277 --------
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
278
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
279 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
280 print.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
281
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
282 ### start (required)
714
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 Always add arguments with the invocation.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
285
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
286 Starting foo: /bin/foo -d
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
287
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
288 If the service is already running, show:
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
289
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
290 foo is already running with pid: 1234
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
291
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
292 ### stop (required)
714
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 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
295
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
296 Stopping foo.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
297
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
298 ### restart (required)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
299
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
300 Basically, this command just calls stop and start.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
301
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
302 Stopping foo.
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
303 Starting foo: /bin/foo -d
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
304
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
305 ### status (recommended)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
306
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
307 Depending on the status, write the following messages.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
308
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
309 foo is running with pid: 1234
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
310 foo is not running
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 ### usage (required)
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
313
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
314 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
315 this through stderr and exit 1. Also keep all subcommands sorted.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
316
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
317 usage: foo restart|start|status|stop
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
318
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
319 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
320 the maintainer discretion.
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 See also the template file in Templates/rc.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
323
1165
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
324 Static and shared libraries
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
325 ===========================
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
326
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
327 By default, your package *MUST* ship both static and shared libraries if
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
328 applicable.
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
329
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
330 If possible, the package should provide the option *STATIC* that should do the
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
331 following if set to *yes*:
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
332
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
333 - On library packages, disable generation of shared libraries,
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
334 - On executables, build static binaries,
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
335 - If the package provides both, do the two steps.
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
336
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
337 This option should not be enabled by default unless absolutely necessary.
8d2032c88258 vanilla: add note about static and shared libraries
David Demelier <markand@malikania.fr>
parents: 1106
diff changeset
338
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
339 Libtool files
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
340 =============
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
341
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
342 Do not ship libtool files.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
343
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
344 Manual pages
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
345 ============
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
346
821
c5cbe07af6a9 vanilla: update manual.md
David Demelier <markand@malikania.fr>
parents: 714
diff changeset
347 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
348 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
349 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
350 destination directory.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
351
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
352 Post install scripts
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
353 ====================
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 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
356 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
357 script must be written also in pure POSIX shell language.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
358
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
359 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
360
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
361 - pre-install: before the extraction of the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
362 - post-install: after the extraction of the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
363 - pre-uninstall: before removing the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
364 - post-uninstall: after the removal of the package.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
365
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
366 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
367 a good idea to check it's presence first.
714
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
368
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
369 Example:
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
370
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
371 #!/bin/sh
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
372
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
373 if [ -x /bin/gtk-update-icon-cache ]; then
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
374 gtk-update-icon-cache -vf /share/icons/hicolor
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
375 fi
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
376
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
377 Desktop files
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
378 =============
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
379
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
380 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
381 itself. This also includes terminal based applications.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
382
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
383 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
384 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
385 once).
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
386
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
387 See [desktop entry specification][] for more information.
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
388
6b4ba668a43c vanilla: update documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
389 [desktop entry specification]: https://specifications.freedesktop.org/desktop-entry-spec/latest