ZFSOnLinux Development Guide

This page is a temporary home for documentation intended for ZFS developers on how ZFSOnLinux development is done. It is a WIP that is only meant for developers.

= Setting up a development environment =

You will likely find this to be easiest with a Linux environment. It is theoretically possible to use non-Linux environments, but no one does it in practice and anyone trying to use a non-Linux environment will be in new territory.

Once you have a Linux environment, you will want to install git and cscope. You will want to setup git. The "Git book" is a good resource for this, but the simplest setup is:

Then clone the repositories. For example:

You might want to create a bash alias to make using cscope easy.

After running that in your shell, you can run `cscope-init && cscope -d` inside directories to get a nice curses interface for browsing the code.

= Setting up a VM environment =

Virtual machines can save time when running regression tests reveal problems in new code by allowing inspection of the environment from the hypervisor. It is desireable to test module loading and unloading in the virtual environment, so it is best to use a non-ZFS rootfs in the environment running regression tests. The simplest one to use is 9p-virtio, which is a network filesystem whose server is integrated with QEMU and operates over a virtio transport. It also introduces a few quirks of its own, but those can be worked around by compiling in a chroot.

Gentoo with a 9p-virtio rootfs
We pick /guest as a place to store the virtual machines. /guest/gentoo will store the rootfs and we will make clever use of bind mounts to have a chroot at /guest/gentoo-chroot to alow us to operate on the rootfs even while the VM is running.

Now we install the current stage3:

Setup the bind mounts:

Also setup a bind mount to allow the chroot to access code from our development environment:

Copy resolv.conf so that DNS resolution inside our chroot works:

Now enter the chroot for additional setup:

Setup serial terminals

Disable the fstab entries. We do not need them with a 9p-virtio rootfs:

Now lets setup portage:

Lets also setup distfiles and packages:

Do some portage configuration.

Keyword the 9999 ebuilds.

Configure ZFS packaging

If you are not bind mounting a portage tree, install one:

Install a few tools we will need:

Configure make.conf:


 * 1) We compile quite a bit, so we therefore try to optimize GCC somewhat


 * 1) Lets rebuild everything and install the tools we need at the same time


 * 1) Lets cheat at kernel configuration

In menuconfig, make certain that you enable the following


 * CONFIG_MODULES=y
 * CONFIG_MODULE_UNLOAD=y
 * CONFIG_EXPERT=y
 * CONFIG_KALLSYMS=y
 * CONFIG_KPROBES=y
 * CONFIG_FTRACE=y
 * CONFIG_KPROBE_EVENT=y (probably already set)
 * CONFIG_UPROBE_EVENT=y
 * CONFIG_FUNCTION_TRACER=y
 * CONFIG_FUNCTION_GRAPH_TRACER=y (probably already set)
 * CONFIG_DEBUG_INFO=y
 * CONFIG_READABLE_ASM=y
 * CONFIG_LOCKUP_DETECTOR=y
 * CONFIG_DEBUG_LIST=y
 * CONFIG_KGDB=y
 * CONFIG_DEBUG_SET_MODULE_RONX=y
 * CONFIG_CC_STACKPROTECTOR_REGULAR=y (CONFIG_CC_STACKPROTECTOR_STRONG preferred, but we don't have GCC 4.9 yet)
 * CONFIG_VIRTIO_PCI=y
 * CONFIG_NET_9P=y
 * CONFIG_NET_9P_VIRTIO=y
 * CONFIG_9P_FS=y
 * CONFIG_9P_FS_POSIX_ACL=y
 * CONFIG_9P_FS_SECURITY=y

Then compile the kernel:

Now you should be able to start a VM: