| blob | 7e03240177cee1aab957ce3dcbc9c25f0a678e54 |
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 .BR \-\-cleanbuild
246 Remove the source directory before building the package.
247 .RB ( "makepkg \-\-cleanbuild" )
248 .
249 .TP
250 .BI \-\-buildscript= NAME
251 Read the package script
252 .I NAME
253 instead of the
254 .I PKGBUILD
255 default.
256 .RB ( makepkg " " \-p )
257 .
258 .SS repo\-add options
259 .TP
260 .BR \-v ", " \-\-verify
261 Verify the PGP signature of the database before
262 updating.
263 .RB ( repo\-add " " \-v )
264 .
265 .TP
266 .BR \-R ", " \-\-remove
267 Remove old package files from disk when updating their entry in the
268 database.
269 .RB ( repo\-add " " \-R )
270 .
271 .TP
272 .BR \-\-new
273 Only add packages that are not already in the database.
274 .RB ( repo\-add " " \-n )
275 .
276 .TP
277 .BR \-\-prevent\-downgrade
278 Do not add packages to the database if a newer version is already
279 present.
280 .RB ( repo\-add " " \-p )
281 .
282 .SH ENVIRONMENT
283 .TP
284 .B AUR_REPO
285 The repository used for building packages. If unspecified, the name is
286 selected with
287 .BR aur\-repo (1).
288 .
289 .TP
290 .B AUR_DBROOT
291 The root directory of the repository. If unspecified, the path is
292 retrieved with
293 .BR aur\-repo (1).
294 .
295 .TP
296 .B AUR_DBEXT
297 The extension name of the repository. Defaults to
298 .IR .db .
299 .
300 .TP
301 .B AUR_MAKEPKG
302 The command used to build packages. Any
303 .BR makepkg (8)
304 options (see the
305 .B makepkg options
306 section) forwarded must be supported by this command, as well as the
307 .IR \-o ,
308 .IR \-d ,
309 and
310 .I \-\-noextract
311 options if
312 .B aur\-build \-\-pkgver
313 is used.
314 .
315 .B AUR_BUILD_PKGLIST
316 The command used to check for built packages in the local
317 repository. Defaults to
318 .BR "aur build\-\-pkglist" .
319 Compared to
320 .BR "makepkg \-\-packagelist" ,
321 the default command runs faster by not linting the
322 .IR PKGBUILD .
323 .
324 .TP
325 .B AUR_GPG
326 The command used to sign packages. The arguments
327 .BR \-\-batch ,
328 .BR \-\-detach\-sign ,
329 and
330 .BR \-\-no\-armor
331 must be supported by this command.
333 .TP
334 .B AUR_REPO_ADD
335 The command used to update the local repository. Any
336 .BR repo\-add (8)
337 options (see the
338 .B repo\-add options
339 section) forwarded must be supported by this command.
340 .
341 .B AUR_PACMAN_AUTH
342 A command prefix for running
343 .BR pacman (8)
344 as root. If unset,
345 .BR sudo (8)
346 is used. See also
347 .B PACMAN_AUTH
348 in
349 .BR makepkg.conf (5).
350 .
351 .TP
352 .B GNUPGHOME
353 Directory where the gpg keyring for signing built packages and the
354 database file is stored.
355 .
356 .TP
357 .B GPGKEY
358 The GPG key used for signing packages. This environment variable is
359 respected by
360 .B aur\-build
361 and
362 .BR repo\-add .
363 When the variable is set in
364 .BR makepkg.conf (5),
365 is it only respected by
366 .BR makepkg .
367 .
368 .TP
369 .B TMPDIR
370 The directory for temporary files. (This includes intermediary storage
371 of built packages, defaulting to
372 .IR /var/tmp .)
373 .
374 .SH NOTES
375 .SS Repository updates
376 When building on the host (outside of a container), installed packages in the
377 local repository are upgraded to the latest available version by running
378 .BI "pacsync " <repository>
379 followed by
380 .BI "pacman \-S \-\-noconfirm " <repository>/<upgrades...> \fR.
381 This is comparable to
382 .BR "makepkg \-i" ,
383 except that only priorly installed packages are upgraded to a new version.
384 .
385 .SS Using a dedicated build user
386 While using a dedicated user for the build process does not increase
387 security (beyond protecting against packaging errors that write to
388 .IR $HOME ),
389 it may be useful when the local repository will be accessible to
390 multiple users, or as a way to avoid password prompts. Note that such
391 a user must be unprivileged; as of pacman 4.2,
392 .BR makepkg (8)
393 may not run directly as root.
394 .PP
395 New users may be created with
396 .BR useradd (8)
397 as follows:
398 .PP
399 .EX
400 # useradd build \-\-system \-\-home\-dir /var/cache/aurbuild \-\-create\-home
401 .EE
402 .PP
403 Because dependency resolution is not replicated and left to
404 .BR makepkg (8)
405 (see
406 .B handle_deps()
407 in
408 .BR /usr/bin/makepkg )
409 the
410 .I aurbuild
411 user should be allowed to run
412 .BR pacman (8)
413 with elevated privileges.
414 .PP
415 For example, create the
416 .I /etc/sudoers.d/10_build
417 file with the following contents:
418 .PP
419 .EX
420 aurbuild ALL = (root) NOPASSWD: /usr/bin/pacman, /usr/bin/pacsync
421 .EE
422 .PP
423 .BR aur\-build (1)
424 and related programs such as
425 .BR aur\-sync (1)
426 can now run as the new
427 .I aurbuild
428 user.
429 For example:
430 .PP
431 .EX
432 # cd /var/cache/aurbuild
433 # sudo \-u aurbuild git clone https://aur.archlinux.org/mypackage.git
434 # cd mypackage
435 # sudo \-u aurbuild aur build \-d custom
436 .EE
437 .PP
438 Any created files in the local repository (such as packages,
439 signatures and database files) will be owned by the
440 .I aurbuild
441 user and group.
442 .PP
443 See also
444 .B Avoiding password prompts
445 in
446 .BR aur\-chroot (1).
447 .TP
448 .B Note:
449 The following
450 .B aur\-build
451 options require root access:
452 .BR \-\-syncdeps ,
453 .BR \-\-rmdeps ,
454 .BR \-\-chroot .
455 Root access are also required for
456 .BR pacsync (1)
457 and
458 .BR "pacman \-S" ,
459 unless the
460 .B \-\-nosync
461 or
462 .B \-\-chroot
463 options are specified.
464 .
465 .SS PKGBUILD signatures
466 GPG signatures defined in the
467 .B validpgpkeys
468 array may be automatically retrieved by setting the
469 .I auto\-key\-retrieve
470 option in
471 .BR gpg.conf .
472 Note that this option only works with signatures that include an
473 issuer fingerprint. See
474 .B \-\-auto\-key\-retrieve
475 in
476 .BR gpg (1)
477 for details.
478 .
479 .SS Signing packages unattended
480 By default,
481 .BR gpg (1)
482 will cache passphrases for a duration set by the
483 .B default-cache-ttl
484 option. If extending this duration is not desired, the passphrase can be
485 cached manually with
486 .B gpg\-preset\-passphrase
487 before running
488 .BR aur\-build (1).
489 .PP
490 The duration of the cached passphrase is set by the
491 .B max\-cache\-ttl
492 option, which defaults to 2 hours. See
493 .BR gpg\-preset\-passphrase (1)
494 for details.
496 .SS Rebuilding packages against updated dependencies
497 It is sometimes required to rebuild packages when their dependencies
498 are updated, for example in the case of dynamic library linking. To
499 detect which packages require a rebuild, the
500 .UR https://\:github.com/\:maximbaz/\:rebuild-detector
501 rebuild-detector
502 .UE
503 package can be used.
504 .PP
505 To propagate rebuilt packages to clients,
506 .B pkgver
507 should be increased beforehand, e.g. with
508 .BR setconf (1).
509 .
510 .SS Installing dependencies with makepkg
511 If
512 .B \-\-syncdeps
513 is specified, package dependencies are installed with
514 .BR "makepkg \-s" .
515 .B makepkg
516 uses the
517 .B pacman \-S \-\-asdeps
518 command for this purpose. Other pacman options can be specified with a
519 wrapper script and the
520 .B PACMAN
521 environment variable. See
522 .B ENVIRONMENT VARIABLES
523 in
524 .BR makepkg (8)
525 for details.
526 .
527 .SS Thread safety
528 .B aur\-build
529 builds and signs packages inside a private directory located in
530 .IR /var/tmp .
531 On success, packages and their signatures are moved with
532 .BR mv (1),
533 which is atomic if the local repository is on the same file system as
534 .BR /var/tmp .
535 .BR makepkg (8)
536 may still write to the
537 .B PKGBUILD
538 in a shared directory, for example when a
539 .I pkgver()
540 function is available. Because of this, it is advised to split the
541 argument file
542 .RB ( "\-a FILE" )
543 into independent arguments, or increase the number of jobs with
544 .B MAKEFLAGS
545 per
546 .BR makepkg.conf (5).
547 .
548 .SH BUGS
549 Databases are built with
550 .B LANG=C
551 to avoid libalpm from skipping entries if the locale is not set
552 (FS#49342).
553 .PP
554 Packages are signed manually with
555 .B "gpg \-\-batch \-\-detach\-sign \-\-no\-armor"
556 since chroot builds have no access to
557 .I pinenentry
558 variables, and to allow signing existing packages without signature.
559 .PP
560 .BR pacman (8)
561 has a size-limit of 25\~MiB for databases. The use of larger databases
562 may result in an
563 .B expected download size exceeded
564 error. To avoid this issue, compress the database with
565 .BR gzip (1).
566 See
567 .UR https://\:git.archlinux.org/\:pacman.git/\:commit/\:?id=\:6dc71926f9b16ebcf11b924941092d6eab204224
568 .UE
569 for details.
570 .PP
571 While
572 .BR pacman (8)
573 options can be passed to
574 .B makepkg \-s
575 .RB ( "aur\-build \-\-syncdeps" )
576 by setting the
577 .B PACMAN
578 environment variable, the value of
579 .B pacman \-\-dbpath
580 is fixed.
581 .
582 .SH SEE ALSO
583 .ad l
584 .nh
585 .BR aur (1),
586 .BR aur\-chroot (1),
587 .BR aur\-repo (1),
588 .BR makepkg.conf (5),
589 .BR pacman.conf (5),
590 .BR sudoers (5),
591 .BR makepkg (8),
592 .BR pacman (8),
593 .BR repo\-add (8),
594 .BR sudo (8)
595 .
596 .SH AUTHORS
597 .MT https://github.com/AladW
598 Alad Wenter
599 .ME
600 .
601 .\" vim: set textwidth=72: