Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



This Gentoo Wiki article describes how to install Philippe Gerum et al's hard real-time Xenomai nanokernel on Gentoo Linux. In particular, it describes Xenomai v2.1.x branch.

Starting at the 2.1.x branch, Xenomai authors have merged Xenomai's kernel modules with the Linux kernel tree. Previous versions used out-of-tree modules.

The changes alter the configuration and installation process, and consequently impact the Gentoo ebuilds. Previous ebuilds have ipipe-sources, incorporating the ADEOS-IPIPE patchset, while xenomai package incorporates out-of-tree modules and the libraries.

Now, the Xenomai modules along with the IPIPE patchset effectively make a new alternative Linux kernel source tree packaged as sys-kernel/xenomai-sources, one of possibly many others from which a system might choose to boot. This new kernel source includes both Xenomai modules and IPIPE. Xenomai shared libraries install as a separate package without kernel modules. In other words, good bye ipipe-sources, hello xenomai-sources!

Note About Version Numbers

The changes simplify installation. Tracking and matching version number between ADEOS-IPIPE and Xenomai now becomes unnecessary. Xenomai source tarballs include the appropriate kernel patches for IPIPE. As long as your kernel source version corresponds to the system library version, no mismatch problems will arise.

There is scope for installing the entire Xenomai system as one Gentoo package. However, this does not exactly fit the Gentoo paradigm where kernel sources have separate packages. Hence, version matching is not completely eliminated. The system libraries still need some level of version compatibility with the kernel modules. You might want to try running one Xenomai kernel with a different set of Xenomai libraries from another version, but why?

Summary of Installation Process

In short, branch v2.1.x Gentoo packages now become xenomai-sources and xenomai, or after prepending category names,

So in outline, the most basic installation procedure becomes

# emerge xenomai-sources
# genkernel --kerneldir=/usr/src/linux-2.6.17-xenomai-r1 all
# KERNEL_DIR=/usr/src/linux-2.6.17-xenomai-r1 emerge xenomai

where /usr/src/linux-2.6.17-xenomai-r1 corresponds to the directory tree where xenomai-sources installs its kernel. Gentoo installs package xenomai-sources-Version-Revision to a source tree at /usr/src/linux-Version-xenomai-Revision by convention.

Actually, the --kerneldir and KERNEL_DIR components of the above commands assume USE flag symlink is not set. If your USE flags include symlink, merging xenomai-sources switches the /usr/src/linux symbolic link to the new kernel which then becomes the default kernel source. You can omit kernel directory specifications if the default points at Xenomai.

You can follow this procedure while running the standard Gentoo kernel (gentoo-sources) or generally any other kernel. It does not depend on Xenomai running at any point. You can safely reboot the new kernel after completing the installation. Of course, booting the new kernel typically requires suitable GRUB or LILO configuration.

Details for each step follow.

Merge the Xenomai Kernel Source Tree

Merge using

# emerge xenomai-sources

just as any other kernel source tree. It performs no compilation, just sets up the source tree. Assuming the merged sources have package name-version-revision of xenomai-sources-2.6.17-r1, the source tree merges at /usr/src/linux-2.6.17-xenomai-r1.

Compile the Kernel Sources

Compile either manually or indirectly using genkernel as follows.

# genkernel --kerneldir=/usr/src/linux-2.6.17-xenomai-r1 all

Note, this does not automatically open the kernel configuration menu. Add the --menuconfig or --xconfig option in order to configure the real-time subsystem or any other configuration items. You will notice a new Real-time sub-system sub-menu.

Linux Kernel Configuration: Linux Kernel v2.6.17-xenomai-r1 Configuration
Linux Kernel v2.6.17-xenomai-r1 Configuration
 ┌────────────────────── Linux Kernel Configuration ───────────────────────┐
 │  Arrow keys navigate the menu.  <Enter> selects submenus --->.          │
 │  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, │
 │  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> │
 │  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       │
 │ ┌─────────────────────────────────────────────────────────────────────┐ │
 │ │    Code maturity level options  --->                                │ │
 │ │    General setup  --->                                              │ │
 │ │    Loadable module support  --->                                    │ │
 │ │    Block layer  --->                                                │ │
 │ │    Real-time sub-system  --->                                       │ │
 │ │    Processor type and features  --->                                │ │
 │ │    Power management options (ACPI, APM)  --->                       │ │
 │ │    Bus options (PCI, PCMCIA, EISA, MCA, ISA)  --->                  │ │
 │ │    Executable file formats  --->                                    │ │
 │ │    Networking  --->                                                 │ │
 │ └v(+)─────────────────────────────────────────────────────────────────┘ │
 │                    <Select>    < Exit >    < Help >                     │

You might wonder: why not just emerge xenomai-sources and xenomai at the same time? That is, why does installation need kernel compilation before merging xenomai? Simply because the xenomai package depends on the Xenomai kernel source including its configuration, i.e. the .config! Configuration does not happen until you compile the kernel.

Merge Xenomai's System Libraries

Finally merge system libraries using

# KERNEL_DIR=/usr/src/linux-2.6.17-xenomai-r1 emerge xenomai

Ebuild Scripts and Patches

There are two separate ebuild scripts, one for kernel sources, the other for Xenomai libraries. The xenomai-sources ebuild also uses a patch.

Xenomai Sources

Listing below gives the ebuild script for installing Xenomai kernel sources on Gentoo. Its package category is sys-kernel just like other kernel sources. Therefore it should appear under the Portage tree at sys-kernel/xenomai-sources.

File: xenomai-sources-2.6.17-r1.ebuild
# Copyright 1999-2006 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: /cvs/xenomm/xenomm/portage/sys-kernel/xenomai-sources/xenomai-sources-2.6.17-r1.ebuild,v 1.2 2006/10/04 14:04:35 royratcliffe Exp $

K_WANT_GENPATCHES="base extras"
# Note that the patch version number and the package revision do not
# necessarily coincide!  Compare gentoo-sources and other kernel
# ebuild scripts.  In our case, package revision numbers correspond
# to kernel version, Gentoo patch version, Xenomai version and
# patch number as follows.
#             | kernel | genpatches | xenomai
#   ----------+--------+------------+--------
#   2.6.17-r1 | 2.6.17 | 17-11      | 2.1.3
# See
K_GENPATCHES_VER="10" # used by gentoo-sources-2.6.17-r8
inherit kernel-2 eutils

# Xenomai 2.1.3

DESCRIPTION="Kernel sources including Gentoo patchset on top of Xenomai nanokernel"

src_unpack() {

	# Portage's ``unpack'' macro unpacks to the current directory.
	# Unpack to the work directory.  Afterwards, ``work'' contains:
	#	linux-2.6.17-xenomai-r1
	#	xenomai-2.1.3
	cd ${WORKDIR}
	unpack ${XENO_TAR} || die "unpack failed"
	epatch ${FILESDIR}/prepare-kernel.patch || die "patch failed"

	scripts/ --linux=${S} <<EOF || die "prepare kernel failed"


The kernel source ebuild script depends on a small patch. It fixes a tiny problem with symbolic links. Gentoo ebuilds compile and install packages within a protected sandbox. After successful compilation and installation, the Portage tool merges the installed binaries and other components into the main filesystem. Here install only refers to sandbox installation. After merging, the sandbox becomes redundant and therefore gets deleted. However, Xenomai installs symbolic links to the build tree within the sandbox. The patch converts these links to copies since the build tree disappears after merging.

File: prepare-kernel.patch
*** xenomai-2.1.2/scripts/	2006-04-13 19:27:24.000000000 +0100
--- xenomai-2.1.2/scripts/	2006-07-14 15:06:40.000000000 +0100
*** 107,113 ****
              if test "x$output_patch" = "x"; then
                  mkdir -p $linux_tree/$link_dir/$d
                  if test x$forcelink = x1 -o ! -h $linux_tree/$link_dir/$f; then
!                     ln -sf $xenomai_root/$target_dir/$f $linux_tree/$link_dir/$f
                  if test `check_filter $link_dir/$f` = "ok"; then
--- 107,113 ----
              if test "x$output_patch" = "x"; then
                  mkdir -p $linux_tree/$link_dir/$d
                  if test x$forcelink = x1 -o ! -h $linux_tree/$link_dir/$f; then
!                     cp $xenomai_root/$target_dir/$f $linux_tree/$link_dir/$f
                  if test `check_filter $link_dir/$f` = "ok"; then


This ebuild script installs system libraries so belongs in sys-libs category. Under the Portage tree it belongs in sys-libs/xenomai.

File: xenomai-2.1.3.ebuild
# Copyright 1999-2006 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: /cvs/xenomm/xenomm/portage/sys-libs/xenomai/xenomai-2.1.3.ebuild,v 1.3 2006/10/13 12:32:15 royratcliffe Exp $

inherit eutils linux-info

DESCRIPTION="Pervasive, interface-agnostic, hard real-time support"
IUSE="uvm debug smp x86-sep x86-tsc"


# On purpose, this ebuild does not use econf, emake or einstall.  The
# good reason: these specify --prefix=/usr without any way to
# override.  However, this ebuild allows Xenomai to apply its default
# prefix of /usr/xenomai.  Therefore it compiles and installs using the
# usual sequence of
#	./configure
#	make
#	make DESTDIR=image install

src_compile() {
	# Xenomai's configuration step uses the kernel sources to build
	# modules.  Configuration also uses kernel sources for extracting
	# GCC architecture-specific flags.  However, this latter usage
	# *sometimes* breaks out of the Gentoo Portage sandbox!  Use
	# addpredict to mask the violation.
	addpredict ${KERNEL_DIR}/display_archflags.gcda
	# Also add the ``canonical'' kernel directory in case the directory is
	# actually a symlink as is usually the case with /usr/src/linux!
	addpredict `readlink -f ${KERNEL_DIR}`/display_archflags.gcda

	# To override the default system UVM heap size (128Kb) add the
	# following line
	# to your /etc/make.conf adjusting the Kb size to suit your needs.
	local myconf=""
	if [ -n "${XENO_OPT_SYS_HEAPSZ}" ]
	then myconf="${myconf} --enable-uvm-heapsz=${XENO_OPT_SYS_HEAPSZ}"

	# Pass the Linux kernel directory.  Do not let the configure
	# script guess; it might guess incorrectly if, for example, the
	# build and target hosts do no run the same kernel.  Passing
	# KERNEL_DIR lets you override if necessary by setting
	# KERNEL_DIR=some-kernel-source-path in a prefix to emerge!
	./configure --with-linux-dir=${KERNEL_DIR} \
		$(use_enable uvm) \
		$(use_enable debug) \
		$(use_enable smp) \
		$(use_enable x86-sep) \
		$(use_enable x86-tsc) \
		${myconf} || die "configure failed"
	make || die "make failed"

src_install() {
	make DESTDIR=${D} install || die "make install failed"

	dodir /etc/env.d
	>>${D}/etc/env.d/00xenomai echo "ROOTPATH=/usr/xenomai/bin"
	>>${D}/etc/env.d/00xenomai echo "PATH=/usr/xenomai/bin"
	>>${D}/etc/env.d/00xenomai echo "LDPATH=/usr/xenomai/lib"
	>>${D}/etc/env.d/00xenomai echo "MANPATH=/usr/xenomai/man"

	xeno_cflags="`${D}/usr/xenomai/bin/xeno-config --xeno-cflags`"
	xeno_ldflags="`${D}/usr/xenomai/bin/xeno-config --xeno-ldflags`"
	insinto ${pkgconfigdir}
	doins ${FILESDIR}/${PN}-native.pc
	dosed "s:@PV@:${PV}:g" ${pkgconfigdir}/${PN}-native.pc
	dosed "s:@xeno_cflags@:${xeno_cflags}:g" ${pkgconfigdir}/${PN}-native.pc
	dosed "s:@xeno_ldflags@:${xeno_ldflags}:g" ${pkgconfigdir}/${PN}-native.pc


Concerns or Compliments? Please use the Discussion section.

Retrieved from ""

Last modified: Tue, 14 Nov 2006 02:41:00 +0000 Hits: 4,368