1 .\"
2 .\" Pkgfile manual page.
3 .\" (C) 2018 by Fun, updated 2021 by John McQuah <jmcquah at disroot dot org>
4 .\"
5 .TH Pkgfile 5 "" "pkgutils #VERSION#" ""
6 .SH NAME
7 Pkgfile \- sourced by \fBpkgmk\fP(8) when building a package in the ports tree
8 .SH DESCRIPTION
9 a \fBbash\fP(1) script that tells \fBpkgmk\fP(8) where the source code for a port may be downloaded,
10 and what to do once that source code is unpacked.
11 .SH FILE FORMAT
12 \fBPkgfile\fP starts with a header of commented lines, which are read by \fBprt-get\fP(8)
13 to resolve dependencies, or by \fBportspage\fP(1) to generate an HTML index of the ports collection.
14 After the header \fBpkgmk\fP will expect to find definitions of several mandatory variables, including
15 \fIname\fP, \fIversion\fP, \fIrelease\fP, the bash array \fIsource\fP, and
16 the bash function \fIbuild()\fP.
17 .SS Example:
18 .EX
19 # Description: A library for demonstrating how to create delicious ports.
20 # URL: http://www.gnu.org/software/somelib/index.html
21 # Maintainer: Joe Maintainer, joe at myfantasticisp dot net
22 # Depends on: someotherlib coolness
23
24 name=somelib
25 version=1.2.3
26 release=1
27 source=(ftp://ftp.gnu.org/gnu/$name/archive/$version/$version.tar.gz Makefile.in.patch)
28 renames=($name-$version.tar.gz SKIP)
29
30 build() {
31 cd $name-$version
32 patch -p1 < ../Makefile.in.patch
33 ./configure --prefix=/usr
34 make
35 make DESTDIR=$PKG install
36 rm -rf $PKG/usr/info
37 }
38 .EE
39
40 .SS General guidelines
41 The name of a package should always be lowercase (e.g. \fBname=eterm\fP and
42 not \fBname=Eterm\fP). In case the package is added to the CRUX ports system
43 the exact same name should be used for the name of the directory in the
44 ports structure, i.e. \fI/usr/ports/???/eterm\fP.
45 .LP
46 Do not combine several separately distributed programs/libraries into
47 one package. Make several packages instead.
48 .LP
49 Use \fBprtverify\fP to check the port.
50
51 .SS Variable names
52 .LP
53 Do not add new variables to the \fBPkgfile\fP. Only in very few cases
54 does this actually improve the readability or the quality of the
55 package. Further, the only variables that are guaranteed to work with
56 future versions of \fBpkgmk\fP are \fIname\fP, \fIversion\fP, \fIrelease\fP,
57 and \fIsource\fP. Other names could be in conflict with internal variables
58 in \fBpkgmk\fP.
59 .LP
60 Use the \fI$name\fP and \fI$version\fP variables to make the
61 package easier to update/maintain. For example,
62
63 .EX
64 source=(http://xyz.org/$name-$version.tar.gz)
65 .EE
66
67 is better than
68
69 .EX
70 source=(http://xyz.org/myprog-1.0.3.tar.gz)
71 .EE
72
73 since the URL will automatically update when you modify the \fI$version\fP variable.
74
75 .SS Support for renaming source files
76 Note that in the \fBsomelib\fP example above, Joe Maintainer chose to define the optional bash array
77 \fIrenames\fP (same length as \fIsource\fP), so that the ambiguously-named file retrieved by FTP
78 would not collide with another port's files, if downloaded into a common directory.
79 The keyword \(oqSKIP\(cq was given in the \fIrenames\fP array to indicate that renaming was not
80 necessary for the corresponding source file. SKIP should always be used for a file retrieved by
81 \(oqports -u\(cq, because the port maintainer has the freedom to choose an unambiguous name in the
82 \fisource\fP array itself.
83 .PP
84 Tools from prior versions of CRUX, ignorant of the \fIrenames\fP array, will
85 execute the \fIbuild\fP function using the original filenames given by the remote sources.
86 For maximum compatibility, nothing in your \fIbuild\fP function should rely on the specific names
87 you choose for the downloaded tarballs (their contents will be unpacked into identically-named
88 work directories anyway, assuming you do not take the liberty of redefining \fIunpack_source()\fP in your
89 Pkgfile). But because earlier CRUX tools also have to be instructed to disregard md5 and signature
90 mismatches, port creators should avoid the renaming feature unless absolutely necessary.
91
92 .SS Directories
93 In general packages should install files in these directories. Exceptions
94 are of course allowed if there is a good reason. But try to follow the
95 following directory structure as closely as possible.
96
97 .EX
98 Directory Description
99 --------- ------------
100 /usr/bin/ User command/application binaries
101 /usr/sbin/ System binaries (e.g. daemons)
102 /usr/lib/ Libraries
103 /usr/include/ Header files
104 /usr/lib/<prog>/ Plug-ins, addons, etc
105 /usr/share/man/ Man pages
106 /usr/share/<prog>/ Data files
107 /usr/etc/<prog>/ Configuration files
108 /etc/ Configuration files for system software (daemons, etc)
109 .EE
110 .LP
111 \fI/opt\fP directory is reserved for manually compiled/installed
112 applications. Packages should never place anything there.
113 .LP
114 \fI/usr/libexec/\fP is not used in CRUX, thus packages should never
115 install anything there. Use \fI/usr/lib/<prog>/\fP instead.
116
117 .SS Junk files
118 .LP
119 Packages should not contain "junk files". This includes:
120 .IP \[bu] 2
121 info pages and other online documentation, man pages excluded (e.g. \fIusr/doc/*\fP,
122 \fIREADME\fP, \fI*.info\fP, \fI*.html\fP, etc).
123 .IP \[bu]
124 Files related to NLS (national language support). If \fB--disable-nls\fP is not available as
125 an option to \fBconfigure\fP, then manually inserting \(oqrm -rf $PKG/usr/share/locale\(cq near the
126 end of the \fBbuild\fP function is an acceptable alternative.
127 .IP \[bu]
128 Useless or obsolete binaries (e.g. \fI/usr/games/banner\fP and \fI/sbin/mkfs.minix\fP).
129 .LP
130 Apart from these global rules, the definition of "junk" is often a matter of personal taste.
131 One user might regard as "junk" the same files that another user sees as indispensible. See
132 \fBOptional dependencies\fP below for a simple way to let your port handle such
133 individual preferences automatically.
134
135 .SS Header
136
137 Provide a header including the following fields:
138
139 .EX
140 Name Meaning
141 ---- -------
142 Description A short description of the package; keep it factual
143 Maintainer Your full name and e-mail address, obfuscated if you want
144 Packager The original packager's full name and e-mail address
145 URL A webpage with more information on this software package
146 Depends on A list of dependencies, separated either by spaces or commas
147 .EE
148
149 Note that you should use the obfuscated email address (illustrated in the example above) if
150 you want to put your ports in any of the official CRUX repositories.
151
152 \fIDepends on\fP can be omitted if there are no dependencies.
153
154 .SS Dependencies
155
156 Dependencies are supported by CRUX tools like \fBprt-get\fP and \fBpkg-get\fP.
157 The following rules should be respected:
158
159 .IP "" 4
160 List all runtime dependencies except for gcc (libstdc++) and glibc.
161 .IP "" 4
162 \fBcore\fP contains essential packages for a CRUX system, and our scripts
163 and ports expect the programs provided by \fBcore\fP to be installed; this
164 means that:
165 .IP "" 8
166 build dependencies provided by \fBcore\fP are not listed in the dependency header
167 .IP "" 8
168 run-time dependencies from \fBcore\fP which aren't dynamically linked in are not to be listed, either
169 .TP
170 Examples:
171 .IP "" 4
172 \fBopt/sloccount\fP does \fInot\fP list \fBperl\fP, because the program is a perl script -- there's no binary that links to \fBlibperl\fP
173 .IP "" 4
174 \fBopt/libxml2\fP \fIdoes\fP list \fBzlib\fP, because \fBlibxml\fP is linked to \fBlibz\fP.
175 .LP
176 The reasoning for these guidelines is that you can use \fBrevdep\fP to find ports
177 that need to be updated if one of the dependent libraries has become
178 binary incompatible. To find out what libraries a binary is linked to,
179 use \fBldd\fP or \fBfinddeps\fP.
180 .LP
181 It \fIis\fP permissible to list build dependencies outside of \fBcore\fP, whose only purpose is to
182 generate the manpage of the port. But if the dependency chain is too convoluted, try to find
183 alternative ways of providing such static documentation.
184 .TP
185 Examples:
186 .IP "" 4
187 \fBgreetd\fP \fIdoes\fP list \fBscdoc\fP (only needed to generate the manpages), because the dependency chain
188 leading to this dependency is just \fBscdoc\fP itself.
189 .IP "" 4
190 \fBmpd\fP does \fInot\fP list \fBpython3-sphinx\fP (only needed to generate the manpages), because of the
191 long dependency chain leading to \fBpython3-sphinx\fP, and the possibility of delivering the manpages by
192 simpler means.
193
194 .SS Optional dependencies
195
196 A common practice among port maintainers is to put filesystem tests in the \fIbuild\fP function,
197 allowing the package configuration to vary depending on what other packages the system administrator
198 has installed. This practice can result in footprint mismatches. It is recommended that
199 maintainers build their ports in a container with the bare minimum of dependencies, or prune the
200 auto-generated footprint so that the spurious files are not reported as MISSING on another user's
201 system.
202 .PP
203 Filesystem tests are also useful at the end of a \fIbuild\fP function, for example when determining
204 which shell completions should be installed. Here is a template for tests of this kind:
205 .EX
206 prt-get isinst bash-completion || rm -rf $PKG/usr/share/bash-completion
207 prt-get isinst zsh || rm -rf $PKG/usr/share/zsh
208 prt-get isinst fish || rm -rf $PKG/usr/share/fish
209 .EE
210 .PP
211 If the maintainer built the package in a clean container, then another user with fish installed will
212 see the path /usr/share/fish listed as NEW in the footprint mismatch, and that user can proceed with
213 installation if PKGMK_IGNORE_NEW was enabled in \fBpkgmk.conf\fP(5). More dangerous is the reverse
214 situation: the maintainer built the package in a system with fish, and a user without fish sees
215 /usr/share/fish listed as MISSING in the footprint mismatch. Users should not be encouraged to disregard
216 MISSING, but enabling PKGMK_IGNORE_NEW is generally safe.
217
218 .SS rc start scripts
219
220 You can use the following template for ports that provide some
221 sort of daemon. The runnable script should be called \fI$name.rc\fP,
222 and your port should install it to \fI/etc/rc.d/$name\fP. The installation
223 can happen by calling the following in your \fIbuild\fP function:
224
225 .EX
226 install -D -m 755 $SRC/$name.rc $PKG/etc/rc.d/$name
227 .EE
228 .LP
229 See the existing scripts under /etc/rc.d for examples of using \fBstart-stop-daemon\fP(8)
230 to generate the necessary pid files, temp directories, and logs for your daemon.
231
232 .SH ENVIRONMENT
233 .LP
234 The \fIbuild\fP function should use the \fI$SRC\fP variable whenever it needs
235 to access the files listed in the source variable, and the \fI$PKG\fP
236 variable as the root destination of the output files.
237 .LP
238 Being a shell script executed in the context of \fBpkgmk\fP(8), the
239 entire \fBPkgfile\fP has access to the variables initialized
240 in \fBpkgmk.conf\fP(5) and the default values set by \fBpkgmk\fP(8). Also, as a
241 side effect of how it is used by \fBpkgmk\fP(8), the Pkgfile can also
242 change the behaviour of \fBpkgmk\fP(8) by rewriting some of its functions
243 and variables before \fIbuild()\fP is called. However, the \fIbuild\fP
244 function itself has only read access to these environment variables
245 and shell functions.
246 .SH ERRORS
247 .LP
248 Most of the command failures in \fIbuild()\fP will stop
249 the build process. There is no need to explicitly check the return
250 codes. If you need/want to handle a command failure you should use
251 constructs like:
252
253 .EX
254 \fBif ! command...; then ...\fP
255 \fBcommand || ...\fP
256 .EE
257 .SH SEE ALSO
258 pkgmk(8), pkgmk.conf(5),
259 .UR https://crux.nu/Main/PortGuidelines
260 .UE ,
261 .UR https://crux.nu/Main/PrePostInstallGuidelines
262 .UE .
263 .SH COPYRIGHT
264 pkgmk (pkgutils) is Copyright (c) 2000-2005 Per Liden and Copyright (c) 2006-2021 CRUX team (http://crux.nu).
265 pkgmk (pkgutils) is licensed through the GNU General Public License.
266 Read the COPYING file for the complete license.
|
