Mercurial > vanilla
annotate Docs/manual.md @ 1341:9f35c15329d1 default tip @
dev/meson: downgrade to 0.59.4 due to many regression
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 22 Dec 2021 21:52:57 +0100 |
parents | 8cbb83c16868 |
children |
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 |