| blob | 687ef94912bec9e2cdbf9ad2589d21dc48ca2f3d |
1 .TH AUR\-BUILD 1 2022-07-12 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 .
27 .SH OPTIONS
28 .TP
29 .BI \-a " FILE" "\fR,\fP \-\-arg\-file=" FILE
30 A text file describing directories containing a PKGBUILD relative to
31 the current directory. If unspecified, the current directory is
32 assumed.
33 .
34 .TP
35 .BR \-c ", " \-\-chroot
36 Build packages inside a
37 .BR systemd\-nspawn (1)
38 container with
39 .BR aur\-chroot .
40 Specifying
41 .BR aur\-chroot (1)
42 options such as
43 .B \-\-bind
44 or
45 \-\-temp
46 will append these options to
47 .BR aur\-chroot .
48 .
49 .TP
50 .BI \-d " NAME" "\fR,\fP \-\-database=" NAME
51 The name of the
52 .BR pacman (8)
53 database.
54 .
55 .TP
56 .BI \-\-root= DIR
57 The root directory for the repository. The
58 .I root
59 is the location for the pacman database
60 .RI ( foo.db ),
61 built packages, and secondary files such as the files database
62 .RI ( foo.files ).
63 This defaults to the value of the
64 .B Server
65 directive for the configured repository.
66 .IP
67 .B Note:
68 The
69 .I Server
70 directive configured in
71 .BR pacman.conf (5)
72 is used for
73 .BR pacman (8)
74 sync operations regardless of this setting. See also
75 .BR \-\-no\-sync .
76 .
77 .TP
78 .BR \-f ", " \-\-force
79 Continue the build process if a package with the same name is
80 found. Without this option,
81 .B aur\-build
82 will add existing packages to the local repository and (if
83 .B \-\-sign
84 is specified)
85 .BR gpg (1)
86 sign them.
87 .IP
88 .B Note:
89 Packages are checked for existence
90 .I prior
91 to calling
92 .B makepkg
93 or
94 .B aur\-chroot
95 with
96 .BR "makepkg \-\-packagelist" .
97 If a package script has a
98 .B pkgver()
99 function, package names may be outdated. The check can then be bypassed
100 with
101 .BR \-\-force ,
102 or the
103 .B pkgver()
104 function run priorly with
105 .BR \-\-pkgver .
106 .
107 .TP
108 .BR \-S ", " \-\-sign ", " \-\-gpg\-sign
109 Sign built packages and the database
110 .RB ( "repo\-add \-s" )
111 with
112 .BR gpg (1).
113 To use another key than the default, the
114 .B GPGKEY
115 environment variable can be set to the appropriate key identifier.
116 .IP
117 Should the signing process fail for any reason, corresponding packages are
118 .I not
119 moved to the local repository.
120 .B aur\-build
121 will instead exit with a diagnostic containing the package paths.
122 .
123 .TP
124 .BR \-\-pkgver
125 Run
126 .B "makepkg \-od"
127 before checking existing packages, effectively running the
128 .B pkgver()
129 function if present. The
130 .BR \-\-noextract
131 option is added to the default
132 .BR makepkg (8)
133 options.
134 .IP
135 The
136 .BR \-\-rmdeps ,
137 .BR \-\-syncdeps ,
138 and
139 .BR \-\-noconfirm
140 options are forwarded to the above command. Other
141 .BR makepkg (8)
142 options are ignored.
143 .
144 .TP
145 .BI \-\-makepkg\-conf= FILE
146 The
147 .BR makepkg.conf (5)
148 file used for
149 .BR makepkg (8)
150 operations. For chroot builds, the file is also used inside the container.
151 .RB ( makepkg " " \-\-config ", " aur\-chroot " " \-\-makepkg\-conf ).
152 .
153 .TP
154 .BI \-\-pacman\-conf= FILE
155 The file used for retrieving local repositories
156 .RB ( aur\-repo " " \-\-config ).
157 For chroot builds, the file is also used for
158 .BR pacman (8)
159 operations inside the container
160 .RB ( aur\-chroot " " \-\-pacman\-conf ).
161 .IP
162 .BR pacman (5)
163 calls made by
164 .BR makepkg (8)
165 and local repository upgrades (see the
166 .B Repository updates
167 section)
168 are unaffected by this option.
169 .
170 .TP
171 .BR \-\-no\-sync
172 Do not sync the local repository after building.
173 .
174 .TP
175 .BI \-\-results= FILE
176 Write colon-delimited output in the following form to
177 .IR FILE :
178 .IP
179 .I <action>:file://<path>
180 .IP
181 where
182 .I <action>
183 is either
184 .BR build
185 or
186 .BR exist ,
187 for built packages and packages already available in the local
188 repository, respectively.
189 .
190 .SS makepkg options
191 Additional options may be passed to
192 .B makepkg
193 by placing them after
194 .B \-\-margs
195 (comma-separated).
196 .BR \-\-margs ,
197 .BR \-\-ignorearch ,
198 and
199 .B \-\-nocheck
200 are forwarded to
201 .BR aur\-chroot
202 when the
203 .B \-\-chroot
204 option is specified.
205 .
206 .TP
207 .BR \-\-nocheck
208 Do not run the check() function in the PKGBUILD.
209 .RB ( makepkg " " \-\-nocheck )
210 .
211 .TP
212 .BR \-n ", " \-\-noconfirm ", " \-\-no\-confirm
213 Do not wait for user input.
214 .RB ( makepkg " " \-\-noconfirm )
215 .
216 .TP
217 .BR \-r ", " \-\-rmdeps
218 Remove dependencies installed by makepkg.
219 .RB ( makepkg " " \-\-rmdeps )
220 .
221 .TP
222 .BR \-s ", " \-\-syncdeps
223 Install missing dependencies using
224 .BR pacman .
225 .RB ( makepkg " " \-\-syncdeps )
226 .
227 .TP
228 .BR \-A ", " \-\-ignorearch
229 Ignore a missing or incomplete
230 .I arch
231 field in the build script.
232 .RB ( makepkg " " \-\-ignorearch )
233 .
234 .TP
235 .BR \-L ", " \-\-log
236 Enable logging to a text file in the build directory.
237 .RB ( makepkg " " \-\-log )
238 .
239 .TP
240 .BR -C ", " \-\-clean
241 Clean up leftover work files and directories after a successful build.
242 .RB ( makepkg " " \-\-clean )
243 .
244 .TP
245 .BI \-\-buildscript= NAME
246 Read the package script
247 .I NAME
248 instead of the
249 .I PKGBUILD
250 default.
251 .RB ( makepkg " " \-p )
252 .
253 .SS repo\-add options
254 .TP
255 .BR \-v ", " \-\-verify
256 Verify the PGP signature of the database before
257 updating.
258 .RB ( repo\-add " " \-v )
259 .
260 .TP
261 .BR \-R ", " \-\-remove
262 Remove old package files from disk when updating their entry in the
263 database.
264 .RB ( repo\-add " " \-R )
265 .
266 .TP
267 .BR \-\-new
268 Only add packages that are not already in the database.
269 .RB ( repo\-add " " \-n )
270 .
271 .TP
272 .BR \-\-prevent\-downgrade
273 Do not add packages to the database if a newer version is already
274 present.
275 .RB ( repo\-add " " \-p )
276 .
277 .SH ENVIRONMENT
278 .TP
279 .B AUR_REPO
280 The repository used for building packages. If unspecified, the name is
281 selected with
282 .BR aur\-repo (1).
283 .
284 .TP
285 .B AUR_DBROOT
286 The root directory of the repository. If unspecified, the path is
287 retrieved with
288 .BR aur\-repo (1).
289 .
290 .TP
291 .B AUR_DBEXT
292 The extension name of the repository. Defaults to
293 .IR .db .
294 .
295 .TP
296 .B AUR_MAKEPKG
297 The command used to build packages. Any
298 .BR makepkg (8)
299 options (see the
300 .B makepkg options
301 section) forwarded must be supported by this command, as well as the
302 .IR \-o ,
303 .IR \-d ,
304 and
305 .I \-\-noextract
306 options if
307 .B aur\-build \-\-pkgver
308 is used.
309 .
310 .B AUR_BUILD_PKGLIST
311 The command used to check for built packages in the local
312 repository. Defaults to
313 .BR "aur build\-\-pkglist" .
314 Compared to
315 .BR "makepkg \-\-packagelist" ,
316 the default command runs faster by not linting the
317 .IR PKGBUILD .
318 .
319 .TP
320 .B AUR_GPG
321 The command used to sign packages. The arguments
322 .BR \-\-batch ,
323 .BR \-\-detach\-sign ,
324 and
325 .BR \-\-no\-armor
326 must be supported by this command.
328 .TP
329 .B AUR_REPO_ADD
330 The command used to update the local repository. Any
331 .BR repo\-add (8)
332 options (see the
333 .B repo\-add options
334 section) forwarded must be supported by this command.
335 .
336 .B AUR_PACMAN_AUTH
337 A command prefix for running
338 .BR pacman (8)
339 as root. If unset,
340 .BR sudo (8)
341 is used. See also
342 .B PACMAN_AUTH
343 in
344 .BR makepkg.conf (5).
345 .
346 .TP
347 .B GNUPGHOME
348 Directory where the gpg keyring for signing built packages and the
349 database file is stored.
350 .
351 .TP
352 .B GPGKEY
353 The GPG key used for signing packages. This environment variable is
354 respected by
355 .B aur\-build
356 and
357 .BR repo\-add .
358 When the variable is set in
359 .BR makepkg.conf (5),
360 is it only respected by
361 .BR makepkg .
362 .
363 .TP
364 .B TMPDIR
365 The directory for temporary files. (This includes intermediary storage
366 of built packages, defaulting to
367 .IR /var/tmp .)
368 .
369 .SH NOTES
370 .SS Repository updates
371 When building on the host (outside of a container), installed packages in the
372 local repository are upgraded to the latest available version by running
373 .BI "pacsync " <repository>
374 followed by
375 .BI "pacman \-S \-\-noconfirm " <repository>/<upgrades...> \fR.
376 This is comparable to
377 .BR "makepkg \-i" ,
378 except that only priorly installed packages are upgraded to a new version.
379 .
380 .SS Using a dedicated build user
381 While using a dedicated user for the build process does not increase
382 security (beyond protecting against packaging errors that write to
383 .IR $HOME ),
384 it may be useful when the local repository will be accessible to
385 multiple users, or as a way to avoid password prompts. Note that such
386 a user must be unprivileged; as of pacman 4.2,
387 .BR makepkg (8)
388 may not run directly as root.
389 .PP
390 New users may be created with
391 .BR useradd (8)
392 as follows:
393 .PP
394 .EX
395 # useradd build \-\-system \-\-home\-dir /var/cache/aurbuild \-\-create\-home
396 .EE
397 .PP
398 Because dependency resolution is not replicated and left to
399 .BR makepkg (8)
400 (see
401 .B handle_deps()
402 in
403 .BR /usr/bin/makepkg )
404 the
405 .I aurbuild
406 user should be allowed to run
407 .BR pacman (8)
408 with elevated privileges.
409 .PP
410 For example, create the
411 .I /etc/sudoers.d/10_build
412 file with the following contents:
413 .PP
414 .EX
415 aurbuild ALL = (root) NOPASSWD: /usr/bin/pacman, /usr/bin/pacsync
416 .EE
417 .PP
418 .BR aur\-build (1)
419 and related programs such as
420 .BR aur\-sync (1)
421 can now run as the new
422 .I aurbuild
423 user.
424 For example:
425 .PP
426 .EX
427 # cd /var/cache/aurbuild
428 # sudo \-u aurbuild git clone https://aur.archlinux.org/mypackage.git
429 # cd mypackage
430 # sudo \-u aurbuild aur build \-d custom
431 .EE
432 .PP
433 Any created files in the local repository (such as packages,
434 signatures and database files) will be owned by the
435 .I aurbuild
436 user and group.
437 .PP
438 See also
439 .B Avoiding password prompts
440 in
441 .BR aur\-chroot (1).
442 .TP
443 .B Note:
444 The following
445 .B aur\-build
446 options require root access:
447 .BR \-\-syncdeps ,
448 .BR \-\-rmdeps ,
449 .BR \-\-chroot .
450 Root access are also required for
451 .BR pacsync (1)
452 and
453 .BR "pacman \-S" ,
454 unless the
455 .B \-\-nosync
456 or
457 .B \-\-chroot
458 options are specified.
459 .
460 .SS PKGBUILD signatures
461 GPG signatures defined in the
462 .B validpgpkeys
463 array may be automatically retrieved by setting the
464 .I auto\-key\-retrieve
465 option in
466 .BR gpg.conf .
467 Note that this option only works with signatures that include an
468 issuer fingerprint. See
469 .B \-\-auto\-key\-retrieve
470 in
471 .BR gpg (1)
472 for details.
473 .
474 .SS Signing packages unattended
475 By default,
476 .BR gpg (1)
477 will cache passphrases for a duration set by the
478 .B default-cache-ttl
479 option. If extending this duration is not desired, the passphrase can be
480 cached manually with
481 .B gpg\-preset\-passphrase
482 before running
483 .BR aur\-build (1).
484 .PP
485 The duration of the cached passphrase is set by the
486 .B max\-cache\-ttl
487 option, which defaults to 2 hours. See
488 .BR gpg\-preset\-passphrase (1)
489 for details.
491 .SS Rebuilding packages against updated dependencies
492 It is sometimes required to rebuild packages when their dependencies
493 are updated, for example in the case of dynamic library linking. To
494 detect which packages require a rebuild, the
495 .UR https://\:github.com/\:maximbaz/\:rebuild-detector
496 rebuild-detector
497 .UE
498 package can be used.
499 .PP
500 To propagate rebuilt packages to clients,
501 .B pkgver
502 should be increased beforehand, e.g. with
503 .BR setconf (1).
504 .
505 .SS Installing dependencies with makepkg
506 If
507 .B \-\-syncdeps
508 is specified, package dependencies are installed with
509 .BR "makepkg \-s" .
510 .B makepkg
511 uses the
512 .B pacman \-S \-\-asdeps
513 command for this purpose. Other pacman options can be specified with a
514 wrapper script and the
515 .B PACMAN
516 environment variable. See
517 .B ENVIRONMENT VARIABLES
518 in
519 .BR makepkg (8)
520 for details.
521 .
522 .SS Thread safety
523 .B aur\-build
524 builds and signs packages inside a private directory located in
525 .IR /var/tmp .
526 On success, packages and their signatures are moved with
527 .BR mv (1),
528 which is atomic if the local repository is on the same file system as
529 .BR /var/tmp .
530 .BR makepkg (8)
531 may still write to the
532 .B PKGBUILD
533 in a shared directory, for example when a
534 .I pkgver()
535 function is available. Because of this, it is advised to split the
536 argument file
537 .RB ( "\-a FILE" )
538 into independent arguments, or increase the number of jobs with
539 .B MAKEFLAGS
540 per
541 .BR makepkg.conf (5).
542 .
543 .SH BUGS
544 Databases are built with
545 .B LANG=C
546 to avoid libalpm from skipping entries if the locale is not set
547 (FS#49342).
548 .PP
549 Packages are signed manually with
550 .B "gpg \-\-batch \-\-detach\-sign \-\-no\-armor"
551 since chroot builds have no access to
552 .I pinenentry
553 variables, and to allow signing existing packages without signature.
554 .PP
555 .BR pacman (8)
556 has a size-limit of 25\~MiB for databases. The use of larger databases
557 may result in an
558 .B expected download size exceeded
559 error. To avoid this issue, compress the database with
560 .BR gzip (1).
561 See
562 .UR https://\:git.archlinux.org/\:pacman.git/\:commit/\:?id=\:6dc71926f9b16ebcf11b924941092d6eab204224
563 .UE
564 for details.
565 .PP
566 While
567 .BR pacman (8)
568 options can be passed to
569 .B makepkg \-s
570 .RB ( "aur\-build \-\-syncdeps" )
571 by setting the
572 .B PACMAN
573 environment variable, the value of
574 .B pacman \-\-dbpath
575 is fixed.
576 .
577 .SH SEE ALSO
578 .ad l
579 .nh
580 .BR aur (1),
581 .BR aur\-chroot (1),
582 .BR aur\-repo (1),
583 .BR makepkg.conf (5),
584 .BR pacman.conf (5),
585 .BR sudoers (5),
586 .BR makepkg (8),
587 .BR pacman (8),
588 .BR repo\-add (8),
589 .BR sudo (8)
590 .
591 .SH AUTHORS
592 .MT https://github.com/AladW
593 Alad Wenter
594 .ME
595 .
596 .\" vim: set textwidth=72: