man1/aur-chroot.1

   1 .TH AUR-CHROOT 1 2022-03-04 AURUTILS
   2 .SH NAME
   3 aur\-chroot \- build pacman packages with systemd-nspawn
   4 .
   5 .SH SYNOPSIS
   6 .SY "aur chroot"
   7 .OP \-\-build
   8 .OP \-\-update
   9 .OP \-\-create
  10 .OP \-D directory
  11 .OP \-C pacman_conf
  12 .OP \-M makepkg_conf
  13 .OP \-\-
  14 .RI [ "package..." ]
  15 .YS
  16 .
  17 .SH DESCRIPTION
  18 Build
  19 .BR pacman (8)
  20 packages inside a
  21 .BR systemd\-nspawn (1)
  22 container.
  23 .
  24 .SH OPERATIONS
  25 .TP
  26 .BR \-B ", " \-\-build
  27 Build a package inside the container with
  28 .BR makechrootpkg .
  29 Assumes
  30 .B \-\-create
  31 was run at least once.
  32 .
  33 .TP
  34 .BR \-U ", " \-\-update
  35 Update or create the
  36 .B /root
  37 copy of the container with
  38 .BR arch\-nspawn .
  39 .
  40 .TP
  41 .BR \-\-create
  42 Create a new container with
  43 .BR mkarchroot .
  44 By default, the
  45 .B base\-devel
  46 package group is installed to the container.
  47 .IP
  48 If the host architecture is
  49 .B x86_64
  50 and
  51 .B [multilib]
  52 is set in the pacman configuration (see
  53 .BR \-\-pacman\-conf ),
  54 the
  55 .B multilib\-devel
  56 package group is also installed.
  57 .IP
  58 If packages or package groups are listed on the command-line, these
  59 are installed instead of the above.
  60 .
  61 .TP
  62 .B \-\-path
  63 Print the path to the container template
  64 .RI ( $directory/root ).
  65 .
  66 .SH OPTIONS
  67 .TP
  68 .BI \-D " DIR" "\fR,\fP \-\-directory=" DIR
  69 The base directory for containers. Defaults to
  70 .BI /var/lib/aurbuild/ <machine> \fR.
  71 This directory usually contains a
  72 .B /root
  73 subdirectory that serves as template for user containers (named after
  74 .IR $SUDO_USER ,
  75 or
  76 .B /copy
  77 if unset).
  78 .IP
  79 .B Note:
  80 If the
  81 .B \-T
  82 parameter is specified to
  83 .BR makechrootpkg ,
  84 the user container has a random name and is removed on build
  85 completion.
  86 .
  87 .TP
  88 .BI \-C " FILE" "\fR,\fP \-\-pacman\-conf=" FILE
  89 The
  90 .BR pacman.conf (5)
  91 file used inside the container. When unspecified, the following files
  92 are checked in order:
  93 .IP
  94 .BI /etc/aurutils/pacman-<suffix>.conf
  95 .br
  96 .BI /etc/aurutils/pacman-<machine>.conf
  97 .br
  98 .BI /usr/share/devtools/pacman.conf.d/<suffix>.conf
  99 .br
 100 .BI /usr/share/devtools/pacman.conf.d/aurutils\-<machine>.conf
 101 .IP
 102 The component
 103 .I <suffix>
 104 is optional and specified with the
 105 .B \-\-suffix
 106 option. The component
 107 .I <machine>
 108 is taken from
 109 .BR "uname \-m" .
 110 The resulting file is read with
 111 .B pacman\-conf
 112 to retrieve listed
 113 .B file://
 114 repositories for bind mounting. (See
 115 .BR "Accessing a local repository")
 116 .IP
 117 .B Warning:
 118 Care should be taken when copying the configuration from
 119 .BR /etc/pacman.conf ,
 120 because certain directives (e.g.
 121 .BR IgnorePkg )
 122 may cause issues in the container.
 123 .IP
 124 It is recommended to use
 125 the template in
 126 .B /usr/share/devtools/pacman.conf.d/extra.conf
 127 or
 128 .B /usr/share/devtools/pacman.conf.d/multilib.conf
 129 instead and make the necessary adjustments. Due to devtools limitations, any
 130 desired repositories should be configured explicitly in this copy.
 131 .
 132 .TP
 133 .BI \-M " FILE" "\fR,\fP \-\-makepkg\-conf=" FILE
 134 The
 135 .BR makepkg.conf (5)
 136 file used inside the container. When unspecified, the following files
 137 are checked in order:
 138 .IP
 139 .BI /etc/aurutils/makepkg-<suffix>.conf
 140 .br
 141 .BI /etc/aurutils/makepkg-<machine>.conf
 142 .br
 143 .BI /usr/share/devtools/makepkg.conf.d/<suffix>.conf
 144 .br
 145 .BI /usr/share/devtools/makepkg.conf.d/<machine>.conf
 146 .
 147 .SS makechrootpkg options
 148 .TP
 149 .BI \-\-cargs= ARGS "\fR,\fP \-\-makechrootpkg\-args=" ARGS
 150 Arguments (comma-separated) to be passed to
 151 .B makechrootpkg
 152 for
 153 .BR \-\-build .
 154 Defaults to
 155 .BR "makechrootpkg \-cu" .
 156 .
 157 .TP
 158 .BI \-\-margs= ARGS "\fR,\fP \-\-makepkg\-args=" ARGS
 159 Additional (comma-separated)
 160 .B makepkg
 161 arguments for
 162 .BR makechrootpkg .
 163 A default list of
 164 .BR makepkg (8)
 165 arguments can be listed with
 166 .BR "makechrootpkg \-\-help" .
 167 .
 168 .TP
 169 .B \-\-bind
 170 Bind a directory read-only to the container.
 171 .RB ( makechrootpkg " " \-D )
 172 .
 173 .TP
 174 .B \-\-bind\-rw
 175 Bind a directory read-write to the container.
 176 .RB ( makechrootpkg " " \-d )
 177 .
 178 .TP
 179 .BR \-\-checkpkg
 180 Run
 181 .BR checkpkg (1)
 182 on the built package.
 183 .
 184 .TP
 185 .BR \-N ", " \-\-namcap
 186 Run
 187 .BR namcap (1)
 188 on the built package.
 189 .
 190 .TP
 191 .BR \-T ", " \-\-temp
 192 Build in a temporary container. (\fBmakechrootpkg \-T\fR) Temporary
 193 means that the user container has a random name and is removed on
 194 build completion.
 195 .
 196 .TP
 197 .BI \-\-user= USER
 198 Run the host
 199 .BR makepkg (8)
 200 instance as the specified user. (\fBmakechrootpkg \-U\fR)
 201 .
 202 .SH ENVIRONMENT
 203 .TP
 204 .B AUR_PACMAN_AUTH
 205 The agent used to elevate commands. If unset,
 206 .BR sudo (8)
 207 is used. When running
 208 .BR makechrootpkg ,
 209 the following variables should be preserved:
 210 .IR PKGDEST ,
 211 .IR GNUPGHOME
 212 and
 213 .IR SSH_AUTH_SOCK .
 214 By default, these variables are preserved with
 215 .BR "sudo \-\-preserve-env" ,
 216 which assumes an
 217 .BR ALL
 218 directive or a
 219 .BR SETENV
 220 tag for
 221 .BR /usr/bin/makechrootpkg .
 222 See
 223 .B SETENV
 224 in
 225 .BR sudoers (5)
 226 for details.
 227 .TP
 228 .B PATH
 229 The contents of this variable are ignored and replaced with
 230 .IR /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin .
 231 .TP
 232 .B PKGDEST
 233 The directory where packages are placed. If unset, the current directory
 234 .RB ( $PWD )
 235 is used. See
 236 .BR makepkg.conf (5)
 237 and
 238 .BR "makechrootpkg \-h" .
 239 .
 240 .SH NOTES
 241 .SS Building with makechrootpkg
 242 Changes to the pacman database are
 243 .I not
 244 propagated from the container to the local system. Packages must be
 245 installed and updated separately, typically through
 246 .BI "pacman \-Syu " package_name\fR.
 247 .PP
 248 Package conflicts inside the container must be resolved manually, as
 249 .B makechrootpkg
 250 uses
 251 .B "makepkg \-\-noconfirm \-s"
 252 internally. For example, to replace
 253 .I gcc
 254 with
 255 .IR gcc\-multilib ,
 256 run
 257 .B "arch\-nspawn /var/lib/aurbuild/<machine>/root pacman \-S gcc\-multilib"
 258 as root.
 259 .
 260 .SS Accessing a local repository
 261 To install packages from the local repository (for example, on
 262 dependency resolution with
 263 .BR "makepkg \-s" ,
 264 the container requires read access to the host directory where it is
 265 located. This is ensured through a (read-write)
 266 .IR "bind mount" .
 267 In particular, paths to
 268 .B file://
 269 repositories are passed to
 270 .B arch\-nspawn
 271 and
 272 .B makechrootpkg
 273 with
 274 .BR \-\-bind
 275 and
 276 .BR \-d ,
 277 respectively.
 278 .PP
 279 .
 280 .SS Avoiding password prompts
 281 .BR makepkg (8)
 282 must be run as a regular user as of version 4.2, with privileged
 283 operations done via
 284 .BR sudo (8).
 285 It follows that
 286 .BR aur\-chroot (1)
 287 and
 288 .BR aur\-build (1)
 289 can not run directly as root. To avoid password prompts,
 290 .BR sudoers (5)
 291 can be used instead. For example, if
 292 .BR aur\-chroot (1)
 293 is run as the
 294 .I archie
 295 user, create the following sudoers policy:
 296 .EX
 297
 298   archie ALL = (root) NOPASSWD: SETENV: /usr/bin/makechrootpkg
 299   archie ALL = (root) NOPASSWD: /usr/bin/mkarchroot, /usr/bin/arch-nspawn
 300
 301 .EE
 302 Should the rule only apply to specific hosts, replace
 303 .B ALL
 304 with the respective
 305 .IR hostname .
 306 .PP
 307 .B Warning:
 308 Due to bugs in
 309 .BR makechrootpkg ,
 310 a
 311 .I NOPASSWD
 312 rule for
 313 .I /usr/bin/makechrootpkg
 314 is equivalent to
 315 .IR "NOPASSWD: ALL" .
 316 .
 317 .SS Using ccache and distcc
 318 As in
 319 .BR "Building with makechrootpkg" ,
 320 install the required packages:
 321 .EX
 322
 323   # aur chroot --update ccache distcc
 324
 325 .EE
 326 Ensure write access to
 327 .B ccache
 328 directories on the host:
 329 .EX
 330
 331   # aur chroot --build --bind /home/_ccache:/build/.ccache
 332
 333 .EE
 334 Necessary
 335 .BR makepkg (8)
 336 options may be set in a specified (\-M)
 337 .BR makepkg.conf (5)
 338 file. See GitHub issue #334 for details.
 339 .
 340 .SS Building for a different architecture
 341 To build packages for a different architecture, prepend
 342 .BI setarch " arch"
 343 to the
 344 .B aur\-build
 345 command line.
 346 .PP
 347 The target architecture must be supported both by the host (run
 348 .B "setarch \-\-list"
 349 for an approximation), and have a matching
 350 .BR makepkg.conf (5)
 351 file available in
 352 .B /usr/share/devtools
 353 (such as
 354 .I /usr/share/devtools/makepkg\-i686.conf
 355 for
 356 .IR i686 ).
 357 .PP
 358 Building for other CPU architectures may be done through
 359 QEMU user mode. See
 360 .UR https://www.qemu.org/docs/master/user/index.html
 361 .UE
 362 for details.
 363 .
 364 .SH BUGS
 365 .B PKGDEST
 366 is not checked for existing packages when building with
 367 .BR makechrootpkg .
 368 This happens because packages are built to the
 369 .B /build
 370 path inside the container, and moved afterward to
 371 .B PKGDEST
 372 on the host. Checking for existing packages must thus be done
 373 manually, e.g.  with
 374 .BR "makepkg \-\-packagelist" .
 375 .PP
 376 GPG signing packages with
 377 .B makepkg \-\-sign
 378 is not possible inside the container as the necessary environment
 379 variables are not set (see
 380 .UR https://lists.archlinux.org/pipermail/arch-projects/2016-May/004341.html
 381 .UE
 382 for details.)
 383 Signing packages should thus be done in the host environment e.g. with
 384 .BR "aur\-build \-\-sign" .
 385 .PP
 386 Default
 387 .B makepkg
 388 arguments used in
 389 .B makechrootpkg
 390 (as listed in
 391 .BR "makechrootpkg \-h" )
 392 can be extended but not overridden. In particular, package conflicts
 393 can not solved interactively.
 394 .RB ( "makepkg \-\-noconfirm" )
 395 .PP
 396 .B arch\-nspawn
 397 will unconditionally modify the supplied
 398 .BR pacman.conf (5)
 399 to copy mirrors (and other settings) from the host (see
 400 .B FS#27544
 401 and
 402 .B FS#38641
 403 for details.) Furthermore, repositories must be configured explicitly
 404 in this configuration file, and not part of a separate file configured
 405 with the
 406 .B Include
 407 directive.
 408 .
 409 .SH SEE ALSO
 410 .BR aur (1),
 411 .BR aur\-build (1),
 412 .BR pacconf (1),
 413 .BR pacman (1),
 414 .BR makepkg (8),
 415 .BR makepkg.conf (5),
 416 .BR pacman.conf (5),
 417 .BR setarch (8)
 418 .
 419 .SH AUTHORS
 420 .MT https://github.com/AladW
 421 Alad Wenter
 422 .ME
 423
 424 .\" vim: set textwidth=72: