Tools for the work as proxied maintainer

From Gentoo Wiki
Jump to: navigation, search

Document your Gentoo knowledge

app-emacs/org-mode or x11-misc/zim will help you to accumulate your knowledge fast and find everything quickly later.

Compare and merge ebuilds (diff)

GUIs like dev-util/meld and command line tools like app-misc/colordiff or dev-util/imediff2 help to compare ebuilds.

Testing ebuilds

Testing your ebuilds can be a tedious task. Beside a simple re-emerge of the package in question, to see whether it merges successfully, a good testing practice usually needs to take one or more of the following questions into account:

  • Having a clean gentoo installation to test with: Using your day to day desktop, might miss on dependencies, which you happen to have installed already and thus producing false positives, i.e. letting your ebuild successfully install, while on a new system it would have been failed due to missing dependencies.
  • An exhaustive testing of all possible USE flag combinations: To my knowledge, there's currently no easy way to do this with the tools in portage. For ebuilds with only a few USE flags, this can be done easily by hand. For packages with a lot of USE flags, such an approach is error-prone. You might be better by writing a shell or python script to enumerate all the possibilities.
  • Profile testing: Here testing of default vs. hardened and multilib vs. no-multilib profiles is of interest. It may for example uncover problems with PIC/PIE code in hardened profiles or problems of missing proper multiclassing in the ebuild. Usually you don't want to switch profiles just for the purpose of testing an ebuild.
  • Keyword testing: Without the proper hardware this can only be done in a limited way. In my opinion this is best left to the arch developers. If you are interested in this topic, I would recommend getting in touch with the arch teams.

So to run proper and efficient tests for your ebuild, a dedicated test environment seems necessary. There are several options for this, like using a chroot environment, VM's, a containerized enviroment or even dedicated hardware. The table below summarizes some of the pros and cons of these options.

Method Pros Cons
  • fast setup
  • small memory footprint
need to reset the environment after each emerge
  • easy to set up from a live DVD
  • snapshot's can be used to avoid reinstallation
large memory footprint
container re-usable (with some work) large memory footprint

Using gentoo-test-package for ebuild testing

At you can find a python script for testing ebuilds within a app-emulation/docker container. The script compiles a docker container with the parameters passed at invocation time and either installs the specified package or puts the user into a shell inside the container. Usage of the script is simple:

user $gentoo-test-package --help
gentoo-test-package [-h] [--atom ATOM [ATOM ...]] [--manual]
                          --portage-dir PORTAGE_DIR
                          [--overlay-dir OVERLAY_DIR] [--update]
                          [--threads N] [--use USE [USE ...]] [--unmask ATOM]
                          [--gcc-version VER] [--with-X]

optional arguments:

 -h, --help            show this help message and exit
 --atom ATOM [ATOM ...]
                       The package atom(s) to install
 --manual              Install package manually
 --portage-dir PORTAGE_DIR
                       The local portage directory
 --overlay-dir OVERLAY_DIR
                       Add overlay dir (can be used multiple times)
 --update              Update container before installing atom
 --threads N           Use N threads to build packages
 --use USE [USE ...]   The use flags for the atom
 --unmask ATOM         Unmask atom (can be used multiple times)
 --gcc-version VER     Use gcc version VER
--with-X Install VNC server to test graphical applications
The --portage-dir option is mandatory, as well as use of either --atom or --manual. You can pass in one or more additional overlays with the --overlay-dir option. The script maps the portage and overlay dirs into the container, so changes to the files inside the container will affect the files outside the container on your file system. A one time use case for this script could look something like
CODE One-time test
./gentoo-test-package --portage-dir /usr/portage --overlay-dir /usr/local/portage --use R boost imaging python qt5 rendering views --unmask =sci-libs/vtk-8.0.1 --with-X --atom =sci-libs/vtk-8.0.1
assuming, you have a modified vtk-8.0.1.ebuild file in a local repositoy at /usr/local/portage.