man1/aur-chroot.1

   1 .TH AUR-CHROOT 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 .SH OPTIONS
  62 .TP
  63 .BI \-D " DIR" "\fR,\fP \-\-directory=" DIR
  64 The base directory for containers. This directory usually contains a
  65 .B /root
  66 subdirectory that serves as template for user containers (named after
  67 .IR $SUDO_USER ,
  68 or
  69 .B /copy
  70 if unset).
  71 .IP
  72 .B Note:
  73 If the
  74 .B \-T
  75 parameter is specified to
  76 .BR makechrootpkg ,
  77 the user container has a random name and is removed on build
  78 completion.
  79 .
  80 .TP
  81 .BI \-C " FILE" "\fR,\fP \-\-pacman\-conf=" FILE
  82 The
  83 .BR pacman.conf (5)
  84 file used inside the container. Defaults to
  85 .IR /usr/share/devtools/pacman\-extra.conf .
  86 .IP
  87 This file is read with
  88 .B pacman\-conf
  89 to retrieve listed
  90 .B file://
  91 repositories for bind mounting. (See
  92 .BR "Accessing a local repository")
  93 .
  94 .TP
  95 .BI \-M " FILE" "\fR,\fP \-\-makepkg\-conf=" FILE
  96 The
  97 .BR makepkg.conf (5)
  98 file used inside the container. Defaults to devtools'
  99 .IR makepkg\-<machine>.conf .
 100 .
 101 .TP
 102 .BI \-\-cargs= ARG
 103 Arguments (comma-separated) to be passed to
 104 .B makechrootpkg
 105 for
 106 .BR \-\-build .
 107 Defaults to
 108 .BR "makechrootpkg \-c" .
 109 .
 110 .TP
 111 .BI \-\-margs= ARG
 112 Additional (comma-separated)
 113 .B makepkg
 114 arguments for
 115 .BR makechrootpkg .
 116 A default list of arguments can be listed with
 117 .BR "makechrootpkg \-\-help" .
 118 .
 119 .TP
 120 .B \-\-bind
 121 Bind a directory read-only to the container.
 122 .RB ( makechrootpkg " " \-D )
 123 .
 124 .TP
 125 .B \-\-bind\-rw
 126 Bind a directory read-write to the container.
 127 .RB ( makechrootpkg " " \-d )
 128 .
 129 .TP
 130 .B \-\-path
 131 Print the path to the container template
 132 .RI ( $directory/root ).
 133 .
 134 .TP
 135 .BR \-x ", " \-\-suffix
 136 The path component
 137 .B <suffix>
 138 in the pacman configuration
 139 .BR /usr/share/devtools/pacman\-<suffix>.conf .
 140 Defaults to
 141 .BR extra .
 142 A full path may be specified with
 143 .BR \-\-pacman\-conf .
 144 .
 145 .SH ENVIRONMENT
 146 Packages are placed in the directory set in
 147 .BR PKGDEST .
 148 If unset, the current directory
 149 .RB ( $PWD )
 150 is used. See also
 151 .BR makepkg.conf (5)
 152 and
 153 .BR "makechrootpkg \-h" .
 154 .
 155 .SH NOTES
 156 .SS Building with makechrootpkg
 157 Changes to the pacman database are
 158 .I not
 159 propagated from the container to the local system. Packages must be
 160 installed and updated separately, typically through
 161 .BI "pacman \-Syu " package_name\fR.
 162 .PP
 163 Package conflicts inside the container must be resolved manually, as
 164 .B makechrootpkg
 165 uses
 166 .B "makepkg \-\-noconfirm \-s"
 167 internally. For example, to replace
 168 .I gcc
 169 with
 170 .IR gcc\-multilib ,
 171 run
 172 .B "arch\-nspawn /var/lib/aurbuild/root pacman \-S gcc\-multilib"
 173 as root.
 174 .
 175 .SS Accessing a local repository
 176 To install packages from the local repository (for example, on
 177 dependency resolution with
 178 .BR "makepkg \-s" ,
 179 the container requires read access to the host directory where it is
 180 located. This is ensured through a (read-write)
 181 .IR "bind mount" .
 182 In particular, paths to
 183 .B file://
 184 repositories are passed to
 185 .B arch\-nspawn
 186 and
 187 .B makechrootpkg
 188 with
 189 .BR \-\-bind
 190 and
 191 .BR \-d ,
 192 respectively.
 193 .PP
 194 .
 195 .SS Avoiding password prompts
 196 .BR makepkg (8)
 197 must be run as a regular user as of version 4.2, with privileged
 198 operations done via
 199 .BR sudo (8).
 200 It follows that
 201 .BR aur\-chroot (1)
 202 and
 203 .BR aur\-build (1)
 204 can not run directly as root. To avoid password prompts,
 205 .BR sudoers (5)
 206 can be used instead. For example, if
 207 .BR aur\-chroot (1)
 208 is run as the
 209 .I archie
 210 user, create the following sudoers policy:
 211 .EX
 212
 213   archie ALL = (root) NOPASSWD: SETENV: /usr/bin/makechrootpkg
 214   archie ALL = (root) NOPASSWD: /usr/bin/mkarchroot, /usr/bin/arch-nspawn
 215
 216 .EE
 217 Should the rule only apply to specific hosts, replace
 218 .B ALL
 219 with the respective
 220 .IR hostname .
 221 .
 222 .SS Using ccache and distcc
 223 As in
 224 .BR "Building with makechrootpkg" ,
 225 install the required packages:
 226 .EX
 227
 228   # aur chroot --update ccache distcc
 229
 230 .EE
 231 Ensure write access to
 232 .B ccache
 233 directories on the host:
 234 .EX
 235
 236   # aur chroot --build --bind /home/_ccache:/build/.ccache
 237
 238 .EE
 239 Necessary
 240 .BR makepkg (8)
 241 options may be set in a specified (\-M)
 242 .BR makepkg.conf (5)
 243 file. See GitHub issue #334 for details.
 244 .
 245 .SS Building for a different architecture
 246 To build packages for a different architecture, prepend
 247 .BI setarch " arch"
 248 to the
 249 .B aur\-build
 250 command line.
 251 .PP
 252 The target architecture must be supported both by the host (run
 253 .B "setarch \-\-list"
 254 for an approximation), and have a matching
 255 .BR makepkg.conf (5)
 256 file available in
 257 .B /usr/share/devtools
 258 (such as
 259 .I /usr/share/devtools/makepkg\-i686.conf
 260 for
 261 .IR i686 ).
 262 .PP
 263 Building for other CPU architectures may be done through
 264 QEMU user mode. See
 265 .UR https://www.qemu.org/docs/master/user/index.html
 266 .UE
 267 for details.
 268 .
 269 .SS Devtools limitations
 270 .B PKGDEST
 271 is not checked for existing packages when building with
 272 .BR makechrootpkg .
 273 This happens because packages are built to the
 274 .B /build
 275 path inside the container, and moved afterward to
 276 .B PKGDEST
 277 on the host. Checking for existing packages must thus be done
 278 manually, e.g.  with
 279 .BR "makepkg \-\-packagelist" .
 280 .PP
 281 GPG signing packages with
 282 .B makepkg \-\-sign
 283 is not possible inside the container as the necessary environment
 284 variables are not set (see
 285 .UR https://lists.archlinux.org/pipermail/arch-projects/2016-May/004341.html
 286 .UE
 287 for details.)
 288 Signing packages should thus be done in the host environment e.g. with
 289 .BR "aur\-build \-\-sign" .
 290 .PP
 291 Default
 292 .B makepkg
 293 arguments used in
 294 .B makechrootpkg
 295 (as listed in
 296 .BR "makechrootpkg \-h" )
 297 can be extended but not overriden. In particular, package conflicts
 298 can not solved interactively.
 299 .RB ( "makepkg \-\-noconfirm" )
 300 .PP
 301 .B arch\-nspawn
 302 will unconditionally modify the supplied
 303 .BR pacman.conf (5)
 304 to copy mirrors (and other settings) from the host (see
 305 .B FS#27544
 306 and
 307 .B FS#38641
 308 for details.) Furthermore, repositories must be configured explicitly
 309 in this configuration file, and not part of a separate file configured
 310 with the
 311 .B Include
 312 directive.
 313 .
 314 .SH SEE ALSO
 315 .BR aur (1),
 316 .BR aur\-build (1),
 317 .BR pacconf (1),
 318 .BR pacman (1),
 319 .BR makepkg (8),
 320 .BR makepkg.conf (5),
 321 .BR pacman.conf (5),
 322 .BR setarch (8)
 323 .
 324 .SH AUTHORS
 325 .MT https://github.com/AladW
 326 Alad Wenter
 327 .ME
 328
 329 .\" vim: set textwidth=72: