| blob | c1a44d4dad2f7295417ee17967c33e6c473b8831 |
1 .TH AUR\-BUILD 1 2022-03-25 AURUTILS
2 .SH NAME
3 aur\-build \- build packages to a local repository
4 .
5 .SH SYNOPSIS
6 .SY "aur build"
7 .OP \-d database
8 .OP \-cfSU
9 .OP \-a queue
10 .OP \-\-no\-sync
11 .OP \-\-pkgver
12 .OP \-\-root DIRECTORY
13 .OP \-\-margs
14 .RI [ makepkg_args... ]
15 .YS
16 .
17 .SH DESCRIPTION
18 Build packages adding the results to a local repository.
19 .
20 A local repository is a
21 .BR pacman (8)
22 repository configured with a
23 .I file://
24 prefix in
25 .BR pacman.conf (5).
26 .PP
27 .B aur\-build
28 runs as a regular user, unless for the following options which require
29 root privileges:
30 .BR \-\-syncdeps ,
31 .BR \-\-rmdeps ,
32 .BR \-\-chroot .
33 Unless the
34 .B \-\-nosync
35 or
36 .B \-\-chroot
37 options are provided,
38 .B aur\-build
39 will also attempt to sync to local the repository with
40 .B pacman \-Syu
41 and
42 .BR "pacman \-Fy" .
43 See the
44 .B Repository updates
45 section for details.
46 .
47 .SH OPTIONS
48 .TP
49 .BI \-a " FILE" "\fR,\fP \-\-arg\-file=" FILE
50 A text file describing directories containing a PKGBUILD relative to
51 the current directory. If unspecified, the current directory is
52 assumed.
53 .
54 .TP
55 .BR \-c ", " \-\-chroot
56 Build packages inside a
57 .BR systemd\-nspawn (1)
58 container with
59 .BR archbuild .
60 The prerequisites for this option are that the
61 .BR devtools
62 package is installed, and the a
63 .BR pacman (8)
64 configuration for the container is placed in
65 .BI /etc/aurutils/pacman-<database>.conf \fR
66 where <database> is specified with
67 .BR \-\-database .
68 If this option is not provided,
69 .B aur\-build
70 falls back to
71 .B /etc/aurutils/pacman-<arch>.conf
72 where
73 .I <arch>
74 is the output from
75 .BR "uname \-m" .
76 A different location can be chosen with the
77 .BR \-\-pacman\-conf
78 option.
79 .IP
80 Care should be taken when copying (or using)
81 .B /etc/pacman.conf
82 for this configuration file, as certain directives (e.g.
83 .BR IgnorePkg )
84 may cause issues in the container. It is recommended to instead copy
85 the template in
86 .B /usr/share/devtools/pacman-extra.conf
87 or
88 .B /usr/share/devtools/pacman-multilib.conf
89 and make the necessary adjustments. Due to devtools limitations, any
90 desired repositories should be configured explicitly in this copy.
91 .
92 .RE
93 .TP
94 .BI \-d " NAME" "\fR,\fP \-\-database=" NAME
95 The name of the
96 .BR pacman (8)
97 database.
98 .
99 .TP
100 .BR \-f ", " \-\-force
101 Continue the build process if a package with the same name is found.
102 .
103 .TP
104 .BR \-S ", " \-\-sign ", " \-\-gpg\-sign
105 Sign built packages and the database
106 .RB ( "repo\-add \-s" )
107 with
108 .BR gpg (1).
109 To use another key than the default, the
110 .B GPGKEY
111 environment variable can be set to the appropriate key identifier.
112 .
113 .TP
114 .BR \-\-dry\-run
115 Display package names in the following format, without building anything:
116 .IP
117 .I <mode>:<pkgbase>:file://<package_path>
118 .IP
119 where
120 .I mode
121 is either
122 .B build
123 or
124 .BR exist ,
125 for packages which need to be built and packages which are already in
126 the local repository, respectively.
128 .TP
129 .BR \-\-no\-sync
130 Do not sync the local repository after building.
131 .
132 .TP
133 .BR \-\-pkgver
134 Run
135 .B "makepkg \-od"
136 before checking existing packages (effectively running an existing
137 .B pkgver()
138 function). The
139 .BR \-\-noextract
140 option is added to the default
141 .BR makepkg (8)
142 options.
143 .IP
144 .RS
145 .B Note:
146 The
147 .BR \-r ,
148 .BR \-s ,
149 and
150 .BR \-\-noconfirm
151 options are forwarded to the above command. Other
152 .BR makepkg (8)
153 options are ignored.
154 .RE
155 .
156 .TP
157 .BI \-\-root= DIR
158 The root directory for the repository. The
159 .I root
160 is the location for the pacman database
161 .RI ( foo.db ),
162 built packages, and secondary files such as the files database
163 .RI ( foo.files ).
164 This defaults to the value of the
165 .B Server
166 directive for the configured repository.
167 .IP
168 .RS
169 .B Note:
170 The
171 .I Server
172 directive configured in
173 .BR pacman.conf (5)
174 is used for
175 .BR pacman (8)
176 sync operations regardless of this setting. See also
177 .BR \-\-no\-sync .
178 .RE
179 .
180 .TP
181 .BI \-\-makepkg\-conf= FILE
182 The
183 .BR makepkg.conf (5)
184 file used for
185 .BR makepkg (8)
186 operations. For chroot builds, the file is also used inside the container.
187 .RB ( makepkg " " \-\-config ", " aur\-chroot " " \-\-makepkg\-conf ).
188 .
189 .TP
190 .BI \-\-pacman\-conf= FILE
191 The file used for syncing and retrieving local repositories. For chroot
192 builds, the file is also used inside the container
193 .RB ( aur\-chroot " " \-\-pacman\-conf ).
194 .BR makepkg (8)
195 calls are unaffected by this option.
196 .
197 .SS makechrootpkg options
198 .TP
199 .BI \-D " DIR" "\fR,\fP \-\-directory=" DIR
200 The base directory for containers. Defaults to
201 .BI /var/lib/archbuild/ <chroot\-suffix> \- <arch> \fR.
202 .IP
203 .RS
204 .B Note:
205 This directory usually contains a
206 .B /root
207 subdirectory that serves as template for user containers (named after
208 .IR $SUDO_USER ,
209 or
210 .B /copy
211 if unset).
212 .RE
213 .
214 .TP
215 .BR \-N ", " \-\-namcap
216 Run
217 .BR namcap (1)
218 on the built package.
219 .
220 .TP
221 .BR \-T ", " \-\-temp
222 Build in a temporary container. (\fBmakechrootpkg \-T\fR) Temporary
223 means that the user container has a random name and is removed on
224 build completion.
225 .
226 .TP
227 .BI \-U " USER" "\fR,\fP \-\-user=" USER
228 Run the host
229 .BR makepkg (8)
230 instance as the specified user. (\fBmakechrootpkg \-U\fR)
231 .
232 .TP
233 .BI \-\-bind= DIR
234 Bind a directory read-only to the container. (\fBmakechrootpkg \-D\fR)
235 .
236 .TP
237 .BI \-\-bind\-rw= DIR
238 Bind a directory read-write to the container. (\fBmakechrootpkg \-d\fR)
239 .
240 .TP
241 .BR \-\-checkpkg
242 Run
243 .BR checkpkg (1)
244 on the built package.
245 .
246 .SS makepkg options
247 Additional options may be passed to
248 .B makepkg
249 by placing them after
250 .BR \-\-margs
251 (comma-separated).
252 .
253 .TP
254 .BR \-\-nocheck
255 Do not run the check() function in the PKGBUILD.
256 .RB ( makepkg " " \-\-nocheck )
257 .
258 .TP
259 .BR \-n ", " \-\-noconfirm ", " \-\-no\-confirm
260 Do not wait for user input.
261 .RB ( makepkg " " \-\-noconfirm )
262 .
263 .TP
264 .BR \-r ", " \-\-rmdeps
265 Remove dependencies installed by makepkg.
266 .RB ( makepkg " " \-\-rmdeps )
267 .
268 .TP
269 .BR \-s ", " \-\-syncdeps
270 Install missing dependencies using
271 .BR pacman .
272 .RB ( makepkg " " \-\-syncdeps )
273 .
274 .TP
275 .BR \-A ", " \-\-ignorearch
276 Ignore a missing or incomplete
277 .I arch
278 field in the build script.
279 .RB ( makepkg " " \-\-ignorearch )
280 .
281 .TP
282 .BR \-L ", " \-\-log
283 Enable logging to a text file in the build directory.
284 .RB ( makepkg " " \-\-log )
285 .
286 .TP
287 .BR -C ", " \-\-clean
288 Clean up leftover work files and directories after a successful build.
289 .RB ( makepkg " " \-\-clean )
290 .
291 .TP
292 .BI \-\-buildscript= NAME
293 Read the package script
294 .I NAME
295 instead of the
296 .I PKGBUILD
297 default.
298 .RB ( makepkg " " \-p )
299 .
300 .SS repo\-add options
301 .TP
302 .BR \-v ", " \-\-verify
303 Verify the PGP signature of the database before
304 updating.
305 .RB ( repo\-add " " \-v )
306 .
307 .TP
308 .BR \-R ", " \-\-remove
309 Remove old package files from disk when updating their entry in the
310 database.
311 .RB ( repo\-add " " \-R )
312 .
313 .TP
314 .BR \-\-new
315 Only add packages that are not already in the database.
316 .RB ( repo\-add " " \-n )
317 .
318 .TP
319 .BR \-\-prevent\-downgrade
320 Do not add packages to the database if a newer version is already
321 present.
322 .RB ( repo\-add " " \-p )
323 .
324 .SH ENVIRONMENT
325 .TP
326 .B AUR_REPO
327 The repository used for building packages. If unspecified, the name is
328 selected with
329 .BR aur\-repo (1).
330 .
331 .TP
332 .B AUR_DBROOT
333 The root directory of the repository. If unspecified, the path is
334 retrieved with
335 .BR aur\-repo (1).
336 .
337 .TP
338 .B GNUPGHOME
339 Directory where the gpg keyring for signing built packages and the
340 database file is stored.
341 .
342 .TP
343 .B GPGKEY
344 The GPG key used for signing packages. This environment variable is
345 respected by
346 .B aur\-build
347 and
348 .BR repo\-add .
349 When the variable is set in
350 .BR makepkg.conf (5),
351 is it only respected by
352 .BR makepkg .
353 .
354 .TP
355 .B MAKEPKG
356 The command used to build packages. Any
357 .BR makepkg (8)
358 options (see the
359 .B makepkg options
360 section) forwarded must be supported by this command, as well as the
361 .IR \-o ,
362 .IR \-d ,
363 and
364 .I \-\-noextract
365 options if
366 .B aur\-build \-\-pkgver
367 is used.
368 .
369 .B AUR_PACMAN_AUTH
370 A command prefix for running
371 .BR pacman (8)
372 as root. If unset,
373 .BR sudo (8)
374 is used. See also
375 .BR makepkg.conf (5).
376 .
377 .TP
378 .B TMPDIR
379 The directory for temporary files. (This includes intermediary storage
380 of built packages, defaulting to
381 .IR /var/tmp .)
382 .
383 .SH NOTES
384 .SS Repository updates
385 When building locally (outside a container),
386 .B "pacman \-Syu"
387 is run with
388 .BR pacman.conf (8)
389 only containing the local repository. This is comparable to
390 .BR "makepkg \-i" ,
391 but without subsequent package installation (if a package was
392 installed before, it is updated to the latest available version). An
393 interesting side-effect is that pacman considers packages inside the
394 official repositories "local", and warns if they are newer than any
395 custom counterpart. Packages which define a
396 .I replaces
397 field are ignored if the target package is installed on the local system.
398 .
399 .SS Using a dedicated build user
400 While using a dedicated user for the build process does not increase
401 security (beyond protecting against packaging errors that write to
402 .IR $HOME ),
403 it may be useful when the local repository will be accessible to
404 multiple users or as a way to avoid password prompts. (Note that such
405 a user must be unprivileged; as of pacman 4.2,
406 .BR makepkg (8)
407 may not run directly as root.)
408 .PP
409 New users may be created with
410 .BR useradd (8)
411 as follows:
412 .PP
413 .EX
414 # useradd build \-\-system \-\-home\-dir /var/cache/build \-\-create\-home
415 .EE
416 .PP
417 Because dependency resolution is not replicated and left to
418 .BR makepkg (8)
419 (see
420 .B handle_deps()
421 in
422 .BR /usr/bin/makepkg )
423 the
424 .I build
425 user should be allowed to run
426 .BR pacman (8)
427 with elevated privileges. For example, create the
428 .I /etc/sudoers.d/10_build
429 file with following contents:
430 .PP
431 .EX
432 build ALL = (root) NOPASSWD: /usr/bin/pacman
433 .EE
434 .PP
435 .BR aur\-build (1)
436 (and related programs such as
437 .BR aur\-sync (1))
438 may now be run as the new
439 .I build
440 user.
441 For example:
442 .PP
443 .EX
444 # cd /var/cache/build
445 # sudo \-u build git clone https://aur.archlinux.org/mypackage.git
446 # cd mypackage
447 # sudo \-u build aur build \-d custom
448 .EE
449 .PP
450 Any created files in the local repository (such as packages,
451 signatures and database files) will be owned by the
452 .I build
453 user.
454 .
455 .SS PKGBUILD signatures
456 GPG signatures defined in the
457 .B validpgpkeys
458 array may be automatically retrieved by setting the
459 .I auto\-key\-retrieve
460 option in
461 .BR gpg.conf .
462 Note that this option only works with signatures that include an
463 issuer fingerprint. See
464 .B \-\-auto\-key\-retrieve
465 in
466 .BR gpg (1)
467 for details.
468 .
469 .SS Signing packages unattended
470 By default, `gpg(1)` will cache passphrases for a duration set by the
471 `default-cache-ttl` option. If extending this duration is not desired, the
472 passphrase can be cached manually with `gpg-set-passphrase` before running
473 `aur-build(1)`. The duration of the cached passphrase is then set by the
474 `max-cache-ttl` option, which defaults to 2 hours. See `gpg-set-passphrase` for
475 details.
477 .SS Rebuilding packages against updated dependencies
478 It is sometimes required to rebuild packages when their dependencies
479 are updated, for example in the case of dynamic library linking. To
480 detect which packages require a rebuild, the
481 .UR https://\:github.com/\:maximbaz/\:rebuild-detector
482 rebuild-detector
483 .UE
484 package can be used. To propagate rebuilt packages to clients,
485 .B pkgver
486 should be increased priorly, e.g. with
487 .BR setconf (1).
488 .
489 .SS Installing dependencies with makepkg
490 If
491 .B \-\-syncdeps
492 is specified, package dependencies are installed with
493 .BR "makepkg \-s" .
494 .B makepkg
495 uses the
496 .B pacman \-S \-\-asdeps
497 command for this purpose. If other pacman options are desired for this
498 command, a wrapper script and the
499 .B PACMAN
500 environment variable have to be used. (See
501 .B ENVIRONMENT VARIABLES
502 in
503 .BR makepkg (8).)
504 .PP
505 For example, to use a custom
506 .BR pacman.conf (5)
507 file, create a wrapper script:
508 .PP
509 .EX
510 #!/bin/sh --
511 pacman --config </path/to/file> "$@"
512 .EE
513 .PP
514 and set the
515 .B PACMAN
516 environment variable to its path. (In this particular example,
517 building inside a container with dedicated
518 .BR pacman.conf(5)
519 is an alternative.)
520 .
521 .SH BUGS
522 Databases are built with
523 .B LANG=C
524 to avoid libalpm from skipping entries if the locale is not set
525 (FS#49342). Packages are signed manually with
526 .B "gpg \-\-batch \-\-detach\-sign \-\-no\-armor"
527 (FS#49946).
528 .PP
529 .BR pacman (8)
530 has a size-limit of 25\~MiB for databases. The use of larger databases
531 may result in an
532 .B expected download size exceeded
533 error. To avoid this issue, compress the database with
534 .BR gzip (1).
535 See
536 .UR https://\:git.archlinux.org/\:pacman.git/\:commit/\:?id=\:6dc71926f9b16ebcf11b924941092d6eab204224
537 .UE
538 for details.
539 .
540 .SH SEE ALSO
541 .ad l
542 .nh
543 .BR aur (1),
544 .BR aur\-chroot (1),
545 .BR aur\-repo (1),
546 .BR makepkg.conf (5),
547 .BR pacman.conf (5),
548 .BR sudoers (5),
549 .BR makepkg (8),
550 .BR pacman (8),
551 .BR repo\-add (8),
552 .BR sudo (8)
553 .
554 .SH AUTHORS
555 .MT https://github.com/AladW
556 Alad Wenter
557 .ME
558 .
559 .\" vim: set textwidth=72: