INSTALL.Debian.rst

   1 ..
   2       Licensed under the Apache License, Version 2.0 (the "License"); you may
   3       not use this file except in compliance with the License. You may obtain
   4       a copy of the License at
   5
   6           http://www.apache.org/licenses/LICENSE-2.0
   7
   8       Unless required by applicable law or agreed to in writing, software
   9       distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  10       WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  11       License for the specific language governing permissions and limitations
  12       under the License.
  13
  14       Convention for heading levels in Open vSwitch documentation:
  15
  16       =======  Heading 0 (reserved for the title in a document)
  17       -------  Heading 1
  18       ~~~~~~~  Heading 2
  19       +++++++  Heading 3
  20       '''''''  Heading 4
  21
  22       Avoid deeper levels because they do not render well.
  23
  24 =========================================
  25 Building Debian Packages for Open vSwitch
  26 =========================================
  27
  28 This document describes how to build Debian packages for Open vSwitch. To
  29 install Open vSwitch on Debian without building Debian packages, see the
  30 `installation guide <INSTALL.rst>`__ instead.
  31
  32 .. note::
  33   These instructions should also work on Ubuntu and other Debian derivative
  34   distributions.
  35
  36 Before You Begin
  37 ----------------
  38
  39 Before you begin, consider whether you really need to build packages yourself.
  40 Debian "wheezy" and "sid", as well as recent versions of Ubuntu, contain
  41 pre-built Debian packages for Open vSwitch. It is easier to install these than
  42 to build your own. To use packages from your distribution, skip ahead to
  43 "Installing .deb Packages", below.
  44
  45 Building Open vSwitch Debian packages
  46 -------------------------------------
  47
  48 You may build from an Open vSwitch distribution tarball or from an Open vSwitch
  49 Git tree with these instructions.
  50
  51 You do not need to be the superuser to build the Debian packages.
  52
  53 1. Install the "build-essential" and "fakeroot" packages. For example::
  54
  55        $ apt-get install build-essential fakeroot
  56
  57 2. Obtain and unpack an Open vSwitch source distribution and ``cd`` into its
  58    top level directory.
  59
  60 3. Install the build dependencies listed under "Build-Depends:" near the top of
  61    ``debian/control``. You can install these any way you like, e.g.  with
  62    ``apt-get install``.
  63
  64 Check your work by running ``dpkg-checkbuilddeps`` in the top level of your ovs
  65 directory. If you've installed all the dependencies properly,
  66 ``dpkg-checkbuilddeps`` will exit without printing anything. If you forgot to
  67 install some dependencies, it will tell you which ones.
  68
  69 4. Build the package::
  70
  71        $ fakeroot debian/rules binary
  72
  73    This will do a serial build that runs the unit tests. This will take
  74    approximately 8 to 10 minutes. If you prefer, you can run a faster parallel
  75    build::
  76
  77        $ DEB_BUILD_OPTIONS='parallel=8' fakeroot debian/rules binary
  78
  79    If you are in a big hurry, you can even skip the unit tests::
  80
  81        $ DEB_BUILD_OPTIONS='parallel=8 nocheck' fakeroot debian/rules binary
  82
  83 .. note::
  84
  85   There are a few pitfalls in the Debian packaging building system so that,
  86   occasionally, you may find that in a tree that you have using for a while,
  87   the build command above exits immediately without actually building anything.
  88   To fix the problem, run::
  89
  90       $ fakeroot debian/rules clean
  91
  92   or start over from a fresh copy of the source tree.
  93
  94 5. The generated .deb files will be in the parent directory of the Open vSwitch
  95    source distribution.
  96
  97 Installing .deb Packages
  98 ------------------------
  99
 100 These instructions apply to installing from Debian packages that you built
 101 yourself, as described in the previous section, or from packages provided by
 102 Debian or a Debian derivative distribution such as Ubuntu.  In the former case,
 103 use a command such as ``dpkg -i`` to install the .deb files that you build, and
 104 in the latter case use a program such as ``apt-get`` or ``aptitude`` to
 105 download and install the provided packages.
 106
 107 .. important::
 108   You must be superuser to install Debian packages.
 109
 110 1. Start by installing an Open vSwitch kernel module. See
 111    ``debian/openvswitch-switch.README.Debian`` for the available options.
 112
 113 2. Install the ``openvswitch-switch`` and ``openvswitch-common`` packages.
 114    These packages include the core userspace components of the switch.
 115
 116 Open vSwitch ``.deb`` packages not mentioned above are rarely useful. Refer to
 117 their individual package descriptions to find out whether any of them are
 118 useful to you.
 119
 120 Bug Reporting
 121 -------------
 122
 123 Please report problems to bugs@openvswitch.org.