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