Difference between revisions of "DeveloperWiki:Building in a Clean Chroot"

From ArchWiki
Jump to: navigation, search
m (update link)
 
(19 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 
[[Category: DeveloperWiki]]
 
[[Category: DeveloperWiki]]
 
+
== Introduction ==
= Introduction =
+
  
 
This article is part of the [[DeveloperWiki]].
 
This article is part of the [[DeveloperWiki]].
  
= Why =
+
== Why ==
  
 
Building in a clean chroot prevents missing dependencies in packages, whether due to unwanted linking or packages missing in the depends array in the PKGBUILD.  It also allows users to build a package for the stable repositories (core, extra, community) while having packages from [testing] installed.
 
Building in a clean chroot prevents missing dependencies in packages, whether due to unwanted linking or packages missing in the depends array in the PKGBUILD.  It also allows users to build a package for the stable repositories (core, extra, community) while having packages from [testing] installed.
  
= Convenience Way =
+
== Convenience Way ==
To quickly build a package in a chroot without any further tinkering, one can use the helper scripts from the devtools package.
+
To quickly build a package in a clean chroot without any further tinkering, one can use the helper scripts from the {{Pkg|devtools}} package.
  
These helper scripts should be called in the same directory where the PKGBUILD is, just like with makepkg. For instance, {{ic|extra-i686-build}} automatically sets up chroot in {{ic|/var/lib/archbuild}}, updates it, and builds a package for the extra repository. For multilib builds there is just {{ic|multilib-build}} without an architecture.
+
These helper scripts should be called in the same directory where the PKGBUILD is, just like with makepkg. For instance, {{ic|extra-i686-build}} automatically sets up a chroot from a clean chroot matrix in {{ic|/var/lib/archbuild}}, updates it, and builds a package for the extra repository. For multilib builds there is just {{ic|multilib-build}} without an architecture. Consult the table below for information on which script to use when building for a specific repository and architecture.
  
{{Tip|Consult the table below for information on which script to use when building for a specific repository and architecture.}}
+
The {{ic|-c}} parameter resets the chroot matrix, which can be useful in case of breakage. It is not needed for building in a clean chroot.
  
 
{{Note|[core] is omitted because those packages are required to go through [testing] first before landing in [core].}}
 
{{Note|[core] is omitted because those packages are required to go through [testing] first before landing in [core].}}
 +
 +
{{Note|If the objective is to build a [core] package for your own local usage, it may be desirable to use the stable repositories instead of the testing. In this case you may simply use the extra build scripts.}}
  
 
{| class="wikitable"
 
{| class="wikitable"
! Target repository || Architecture || Build script to use
+
! Target repository || Architecture || Build script to use || Pacman configuration file used
 
|-
 
|-
| extra / community || i686 || extra-i686-build
+
| extra / community || i686 || extra-i686-build || /usr/share/devtools/pacman-extra.conf
 
|-
 
|-
| extra / community || x86_64 || extra-x86_64-build
+
| extra / community || x86_64 || extra-x86_64-build || /usr/share/devtools/pacman-extra.conf
 
|-
 
|-
| testing / community-testing || i686 || testing-i686-build
+
| testing / community-testing || i686 || testing-i686-build || /usr/share/devtools/pacman-testing.conf
 
|-
 
|-
| testing / community-testing || x86_64 || testing-x86_64-build
+
| testing / community-testing || x86_64 || testing-x86_64-build || /usr/share/devtools/pacman-testing.conf
 
|-
 
|-
| staging / community-staging || i686 || staging-i686-build
+
| staging / community-staging || i686 || staging-i686-build || /usr/share/devtools/pacman-staging.conf
 
|-
 
|-
| staging / community-staging || x86_64 || staging-x86_64-build
+
| staging / community-staging || x86_64 || staging-x86_64-build || /usr/share/devtools/pacman-staging.conf
 
|-
 
|-
| multilib || x86_64 || multilib-build
+
| multilib || x86_64 || multilib-build || /usr/share/devtools/pacman-multilib.conf
 
|-
 
|-
| multilib-testing || x86_64 || multilib-testing-build
+
| multilib-testing || x86_64 || multilib-testing-build || /usr/share/devtools/pacman-multilib-testing.conf
 
|-
 
|-
| multilib-staging || x86_64 || multilib-staging-build
+
| multilib-staging || x86_64 || multilib-staging-build || /usr/share/devtools/pacman-multilib-staging.conf
 
|}
 
|}
  
= Classic Way =
+
== Classic Way ==
== Setting Up A Chroot ==
+
=== Setting Up A Chroot ===
  
 
The devtools package provides tools for creating and building within clean chroots. Install it if not done already:
 
The devtools package provides tools for creating and building within clean chroots. Install it if not done already:
  
  pacman -S devtools
+
  # pacman -S devtools
  
 
To make a clean chroot, create a directory in which the chroot will reside.  For example, {{ic|$HOME/chroot}}.
 
To make a clean chroot, create a directory in which the chroot will reside.  For example, {{ic|$HOME/chroot}}.
  
Now create the chroot:
+
$ mkdir ~/chroot
  
CHROOT=$HOME/chroot
+
Define the {{ic|CHROOT}} variable:
mkdir $CHROOT
+
sudo mkarchroot $CHROOT/root base-devel
+
  
{{Note|One can also define the CHROOT variable in $HOME/.bashrc using the export command if the location is to be repeatedly used. }}
+
$ CHROOT=$HOME/chroot
  
Edit {{ic|~/.makepkg.conf}} to set the packager name and any makeflags.  Also adjust the mirror list in {{ic|$CHROOT/root/etc/pacman.d/mirrorlist}} and enable '''[testing]''' in {{ic|$CHROOT/root/etc/pacman.conf}} if desired.
+
Now create the chroot (the sub directory {{ic|root}} is required because the {{ic|$CHROOT}} directory will get other sub directories for clean working copies):
  
Alternatively, provide a custom{{ic|pacman.conf}} and {{ic|makepkg.conf}} with the following:
+
# mkarchroot $CHROOT/root base-devel
 +
 
 +
{{Note|One can also define the {{ic|CHROOT}} variable in {{ic|$HOME/.bashrc}} using the export command if the location is to be repeatedly used. }}
 +
{{Note|On [[btrfs]] disks, the chroot is created as a subvolume, so you have to remove it by removing the subvolume with {{ic|# btrfs subvolume delete $CHROOT/root}}. }}
 +
 
 +
Edit {{ic|~/.makepkg.conf}} to set the packager name and any makeflags.  Also adjust the [[Pacman#Repositories and mirrors|mirrorlist]] in {{ic|$CHROOT/root/etc/pacman.d/mirrorlist}} and enable the [[testing]] repository in {{ic|$CHROOT/root/etc/pacman.conf}}, if desired.
 +
 
 +
==== Custom pacman.conf ====
 +
 
 +
Alternatively, provide a custom {{ic|pacman.conf}} and {{ic|makepkg.conf}} with the following:
 
   
 
   
  sudo mkarchroot -C <pacman.conf> -M <makepkg.conf> $CHROOT/root base-devel
+
  # mkarchroot -C <pacman.conf> -M <makepkg.conf> $CHROOT/root base base-devel
  
It is recommended however users do not use custom {{ic|pacman.conf}} and {{ic|makepkg.conf}} during the initial creation of clean chroot to ensure no user-specific adjustments are made. ''Use with caution.''
+
{{Warning|
 +
Using a custom {{ic|pacman.conf}} or {{ic|makepkg.conf}} during the initial creation of clean chroot can result in unintended custom adjustments to the chroot environment. ''Use with caution.''}}
  
== Building in the Chroot ==
+
=== Building in the Chroot ===
  
 
Firstly, make sure the chroot is up to date with:
 
Firstly, make sure the chroot is up to date with:
  
  sudo arch-nspawn $CHROOT/root pacman -Syu
+
  # arch-nspawn $CHROOT/root pacman -Syu
  
 
Then, to build a package in the chroot, run the following from the dir containing the PKGBUILD:
 
Then, to build a package in the chroot, run the following from the dir containing the PKGBUILD:
  
  sudo makechrootpkg -c -r $CHROOT
+
  $ makechrootpkg -c -r $CHROOT
  
 
Passing the -c flag to makechrootpkg ensures that the working chroot (named {{ic|$CHROOT/$USERNAME}}) is cleaned before building starts.
 
Passing the -c flag to makechrootpkg ensures that the working chroot (named {{ic|$CHROOT/$USERNAME}}) is cleaned before building starts.
  
== Manual package installation ==
+
=== Manual package installation ===
 
Packages can be installed manually to the working chroot by using:
 
Packages can be installed manually to the working chroot by using:
  sudo makechrootpkg -r $CHROOT -I package-1.0-1-i686.pkg.tar.xz
+
 
 +
  # makechrootpkg -r $CHROOT -I package-1.0-1-i686.pkg.tar.xz
  
 
If done from a directory that contains a PKGBUILD, the package will then be built. Avoid being in such a directory if you want to just install the package.
 
If done from a directory that contains a PKGBUILD, the package will then be built. Avoid being in such a directory if you want to just install the package.
  
== Installation after building ==
+
=== Installation after building ===
 
Tell makechrootpkg to simply install a package to the rw layer of the chroot after building by passing the -i arg. Unrecognized args get passed to makepkg, so this calls `makepkg` with the -i arg.
 
Tell makechrootpkg to simply install a package to the rw layer of the chroot after building by passing the -i arg. Unrecognized args get passed to makepkg, so this calls `makepkg` with the -i arg.
sudo makechrootpkg -r $CHROOT -- -i
 
  
= Handling Major Rebuilds =
+
# makechrootpkg -r $CHROOT -- -i
 +
 
 +
== Handling Major Rebuilds ==
  
 
The cleanest way to handle a major rebuild is to use the [staging] repositories. Build the first package against [extra] and push it to [staging]. Then rebuild all following packages against [staging] and push them there.
 
The cleanest way to handle a major rebuild is to use the [staging] repositories. Build the first package against [extra] and push it to [staging]. Then rebuild all following packages against [staging] and push them there.
Line 93: Line 104:
 
If you can't use [staging], you can build against custom packages using a command like this:
 
If you can't use [staging], you can build against custom packages using a command like this:
  
  sudo extra-x86_64-build -- -I ~/packages/foobar/foobar-2-1-any.pkg.tar.xz
+
  # extra-x86_64-build -- -I ~/packages/foobar/foobar-2-1-any.pkg.tar.xz
  
 
You can specify more than one package to be installed using multiple -I arguments.
 
You can specify more than one package to be installed using multiple -I arguments.
Line 99: Line 110:
 
A simpler, but dirtier way to handle a major rebuild is to install all built packages in the chroot, never cleaning it. Build the first package using:
 
A simpler, but dirtier way to handle a major rebuild is to install all built packages in the chroot, never cleaning it. Build the first package using:
  
  sudo extra-x86_64-build
+
  # extra-x86_64-build
  
 
And build all following packages using:
 
And build all following packages using:
  
  sudo makechrootpkg -n -r /var/lib/archbuild/extra-x86_64
+
  # makechrootpkg -n -r /var/lib/archbuild/extra-x86_64
  
 
Running namcap (the -n argument) implies installing the package in the chroot. *-build also does this by default.
 
Running namcap (the -n argument) implies installing the package in the chroot. *-build also does this by default.

Latest revision as of 02:43, 20 April 2016

Introduction

This article is part of the DeveloperWiki.

Why

Building in a clean chroot prevents missing dependencies in packages, whether due to unwanted linking or packages missing in the depends array in the PKGBUILD. It also allows users to build a package for the stable repositories (core, extra, community) while having packages from [testing] installed.

Convenience Way

To quickly build a package in a clean chroot without any further tinkering, one can use the helper scripts from the devtools package.

These helper scripts should be called in the same directory where the PKGBUILD is, just like with makepkg. For instance, extra-i686-build automatically sets up a chroot from a clean chroot matrix in /var/lib/archbuild, updates it, and builds a package for the extra repository. For multilib builds there is just multilib-build without an architecture. Consult the table below for information on which script to use when building for a specific repository and architecture.

The -c parameter resets the chroot matrix, which can be useful in case of breakage. It is not needed for building in a clean chroot.

Note: [core] is omitted because those packages are required to go through [testing] first before landing in [core].
Note: If the objective is to build a [core] package for your own local usage, it may be desirable to use the stable repositories instead of the testing. In this case you may simply use the extra build scripts.
Target repository Architecture Build script to use Pacman configuration file used
extra / community i686 extra-i686-build /usr/share/devtools/pacman-extra.conf
extra / community x86_64 extra-x86_64-build /usr/share/devtools/pacman-extra.conf
testing / community-testing i686 testing-i686-build /usr/share/devtools/pacman-testing.conf
testing / community-testing x86_64 testing-x86_64-build /usr/share/devtools/pacman-testing.conf
staging / community-staging i686 staging-i686-build /usr/share/devtools/pacman-staging.conf
staging / community-staging x86_64 staging-x86_64-build /usr/share/devtools/pacman-staging.conf
multilib x86_64 multilib-build /usr/share/devtools/pacman-multilib.conf
multilib-testing x86_64 multilib-testing-build /usr/share/devtools/pacman-multilib-testing.conf
multilib-staging x86_64 multilib-staging-build /usr/share/devtools/pacman-multilib-staging.conf

Classic Way

Setting Up A Chroot

The devtools package provides tools for creating and building within clean chroots. Install it if not done already:

# pacman -S devtools

To make a clean chroot, create a directory in which the chroot will reside. For example, $HOME/chroot.

$ mkdir ~/chroot

Define the CHROOT variable:

$ CHROOT=$HOME/chroot

Now create the chroot (the sub directory root is required because the $CHROOT directory will get other sub directories for clean working copies):

# mkarchroot $CHROOT/root base-devel
Note: One can also define the CHROOT variable in $HOME/.bashrc using the export command if the location is to be repeatedly used.
Note: On btrfs disks, the chroot is created as a subvolume, so you have to remove it by removing the subvolume with # btrfs subvolume delete $CHROOT/root.

Edit ~/.makepkg.conf to set the packager name and any makeflags. Also adjust the mirrorlist in $CHROOT/root/etc/pacman.d/mirrorlist and enable the testing repository in $CHROOT/root/etc/pacman.conf, if desired.

Custom pacman.conf

Alternatively, provide a custom pacman.conf and makepkg.conf with the following:

# mkarchroot -C <pacman.conf> -M <makepkg.conf> $CHROOT/root base base-devel
Warning: Using a custom pacman.conf or makepkg.conf during the initial creation of clean chroot can result in unintended custom adjustments to the chroot environment. Use with caution.

Building in the Chroot

Firstly, make sure the chroot is up to date with:

# arch-nspawn $CHROOT/root pacman -Syu

Then, to build a package in the chroot, run the following from the dir containing the PKGBUILD:

$ makechrootpkg -c -r $CHROOT

Passing the -c flag to makechrootpkg ensures that the working chroot (named $CHROOT/$USERNAME) is cleaned before building starts.

Manual package installation

Packages can be installed manually to the working chroot by using:

# makechrootpkg -r $CHROOT -I package-1.0-1-i686.pkg.tar.xz

If done from a directory that contains a PKGBUILD, the package will then be built. Avoid being in such a directory if you want to just install the package.

Installation after building

Tell makechrootpkg to simply install a package to the rw layer of the chroot after building by passing the -i arg. Unrecognized args get passed to makepkg, so this calls `makepkg` with the -i arg.

# makechrootpkg -r $CHROOT -- -i

Handling Major Rebuilds

The cleanest way to handle a major rebuild is to use the [staging] repositories. Build the first package against [extra] and push it to [staging]. Then rebuild all following packages against [staging] and push them there.

If you can't use [staging], you can build against custom packages using a command like this:

# extra-x86_64-build -- -I ~/packages/foobar/foobar-2-1-any.pkg.tar.xz

You can specify more than one package to be installed using multiple -I arguments.

A simpler, but dirtier way to handle a major rebuild is to install all built packages in the chroot, never cleaning it. Build the first package using:

# extra-x86_64-build

And build all following packages using:

# makechrootpkg -n -r /var/lib/archbuild/extra-x86_64

Running namcap (the -n argument) implies installing the package in the chroot. *-build also does this by default.