Chroot for package testing

From Gentoo Wiki
Jump to:navigation Jump to:search

Preparing a chroot environment

An efficient way of preparing a reusable chroot environment is by using a btrfs file system [1] and use snapshots. If one do not have access to such a file system then one can use a subdirectory instead of a btrfs subvolume.

You can also use bwrap to boot into a container instead of a chroot.

root #btrfs subvolume create /mnt/gentoo

Get the stage 3 tarball [2]. Then unpack stage 3 in it

root #cp stage3-*.tar.xz /mnt/gentoo
root #cd /mnt/gentoo
root #tar xpvf stage3-*.tar.xz --xattrs-include='*.*' --numeric-owner

When using a btrfs file system, space and operations will be saved by creating a snapshot:

root #btrfs subvolume snapshot /mnt/gentoo /mnt/stage3

Then you can chroot and set up a stable gentoo from stage 3 by following [3].

If you want to use containers instead, you can use bwrap:

root #bwrap --bind /mnt/gentoo / --dev /dev --proc /proc --tmpfs /dev/shm /bin/bash --login --ro-bind /etc/resolv.conf /etc/resolv.conf
The default permission of /dev/shm given by bwrap is 0755, and this permission may expects build failures (see bug #496328). A workaround is add chmod 1777 /dev/shm to /mnt/gentoo/etc/profiles.d/ Bubblewrap is adding a new feature (, the permission can be set by --perms 1777 --tmpfs /dev/shm when it's done.

Inside the chroot (or container), you may want to install repoman and portage with the gentoo-dev USE flag enabled:

root #echo "sys-apps/portage gentoo-dev" >> /etc/portage/package.use/portage
root #emerge -1av sys-apps/portage app-portage/repoman

At this point if you are using a btrfs file system, exit the chroot / bwrap and then make a snapshot. You may then delete the original subvolume:

root # btrfs subvolume snapshot /mnt/gentoo /mnt/stable_stage3

Testing the package foo

If you are using a btrfs filesystem, create a snapshot of the stable stage 3 and chroot in it. If not, just chroot into the stable stage 3.

root #btrfs subvolume snapshot /mnt/stable_stage3 /mnt/foo

For a chroot:

root #mount --types proc /proc /mnt/foo/proc
root #mount --rbind /sys /mnt/foo/sys
root #mount --make-rslave /mnt/foo/sys
root #mount --rbind /dev /mnt/foo/dev
root #mount --make-rslave /mnt/foo/dev
root #chroot /bin/bash /mnt/foo

For Bwrap:

root #bwrap --bind /mnt/gentoo / --dev /dev --proc /proc /bin/bash --login --ro-bind /etc/resolv.conf /etc/resolv.conf

If you are testing multiple packages, you may want to rename the prompt according to the package you are testing :

root # export PS1="(foo) ${PS1}"

Next create a custom repository [4] and copy in it the ebuild you want to test. Before testing the package foo/bar , emerge all its test depencencies.

root # emerge -1av --onlydeps --with-test-deps foo

Then make the adjustments of the make.conf [5], and then emerge the package

root # emerge -1av foo

Once you are done with the test, if you are using a btrfs file system you may delete your test subvolume :

root # btrfs subvolume delete /mnt/foo

And make another test by going back to the beginning of this section. If you are using another file system, then execute the following after each test to get back to a stable stage 3.

root # emerge --depclean

Keeping up to date

Do not forget to keep your stable_stage3 up to date by chrooting in it from time to time and execute :

root # emerge --sync && emerge --quiet --update --deep --newuse @world


  1. [1] - Btrfs file system
  2. [2] - Download the stage 3 tarball
  3. Handbook:AMD64/Installation/Base#Chrooting - Chrooting
  4. [3] - Defining a custom repository
  5. [4] - Package testing