How to Build Debian Packages for Open vSwitch
            =============================================

This document describes how to build Debian packages for Open vSwitch.
To install Open vSwitch on Debian without building Debian packages,
see INSTALL instead.

These instructions should also work on Ubuntu and other Debian
derivative distributions.


Before You Begin
----------------

Before you begin, consider whether you really need to build packages
yourself.  Debian "wheezy" and "sid", as well as recent versions of
Ubuntu, contain pre-built Debian packages for Open vSwitch.  It is
easier to install these than to build your own.  To use packages from
your distribution, skip ahead to "Installing .deb Packages", below.


Building Open vSwitch Debian packages
-------------------------------------

You may build from an Open vSwitch distribution tarball or from an
Open vSwitch Git tree with these instructions.

You do not need to be the superuser to build the Debian packages.

1. Install the "build-essential" and "fakeroot" packages, e.g. with
   "apt-get install build-essential fakeroot".

2. Obtain and unpack an Open vSwitch source distribution and "cd" into
   its top level directory.

3. Install the build dependencies listed under "Build-Depends:" near
   the top of debian/rules.  You can install these any way you like,
   e.g. with "apt-get install".

   Check your work by running "dpkg-checkbuilddeps".  If you've
   installed all the dependencies properly, dpkg-checkbuilddeps will
   exit without printing anything.  If you forgot to install some
   dependencies, it will tell you which ones.

4. Run:

       fakeroot debian/rules binary

   This will do a serial build that runs the unit tests.  If you
   prefer, you can run a faster parallel build, e.g.:

       DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary

   If you are in a big hurry, you can even skip the unit tests:

       DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary

5. The generated .deb files will be in the parent directory of the
   Open vSwitch source distribution.


Installing .deb Packages
------------------------

These instructions apply to installing from Debian packages that you
built yourself, as described in the previous section, or from packages
provided by Debian or a Debian derivative distribution such as Ubuntu.
In the former case, use a command such as "dpkg -i" to install the
.deb files that you build, and in the latter case use a program such
as "apt-get" or "aptitude" to download and install the provided
packages.

You must be superuser to install Debian packages.

1. Start by installing the "openvswitch-switch" and
   "openvswitch-common" packages.  These packages include the core
   userspace components of the switch.

2. Install an Open vSwitch kernel module.  There are multiple ways to
   do this.  In order of increasing manual effort, these are:

       * Use a Linux kernel 3.3 or later, which has an integrated Open
	 vSwitch kernel module.

	 The upstream Linux kernel module lacks a few features that
	 are in the third-party module.  For details, please see the
	 FAQ, "What features are not available in the Open vSwitch
	 kernel datapath that ships as part of the upstream Linux
	 kernel?".

       * Install the "openvswitch-datapath-dkms" Debian package that
	 you built earlier.  This should automatically build and
	 install the Open vSwitch kernel module for your running
	 kernel.

	 This option requires that you have a compiler and toolchain
	 installed on the machine where you run Open vSwitch, which
	 may be unacceptable in some production server environments.

       * Install the "openvswitch-datapath-source" Debian package, use
	 "module-assistant" to build a Debian package of the Open
	 vSwitch kernel module for your kernel, and then install that
	 Debian package.

	 You can install the kernel module Debian packages that you
	 build this way on the same machine where you built it or on
	 another machine or machines, which means that you don't
	 necessarily have to have any build infrastructure on the
	 machines where you use the kernel module.

	 /usr/share/doc/openvswitch-datapath-source/README.Debian has
	 details on the build process.

       * Build and install the kernel module by hand.

Open vSwitch .deb packages not mentioned above are rarely useful.
Please refer to their individual package descriptions to find out
whether any of them are useful to you.


Bug Reporting
-------------

Please report problems to bugs@openvswitch.org.