Merge commit '180c6d0b440961cbc873c4d045eb8b2daa1364e9'

[sliver-openvswitch.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index 671c4a4..18e8532 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -2,12 +2,13 @@
            ================================================
 
 This document describes how to build and install Open vSwitch on a
            ================================================
 
 This document describes how to build and install Open vSwitch on a

-generic Linux or FreeBSD host.  If you want to install Open vSwitch on
-a Citrix XenServer, see INSTALL.XenServer instead.
+generic Linux or FreeBSD host. For specifics around installation on a
+specific platform, please see one of these files:

 
 

-This version of Open vSwitch may be built manually with "configure"
-and "make", as described below.  You may also build Debian packages by
-running "dpkg-buildpackage".
+    - INSTALL.Debian
+    - INSTALL.Fedora
+    - INSTALL.RHEL
+    - INSTALL.XenServer

 
 Build Requirements
 ------------------
 
 Build Requirements
 ------------------


@@ -15,13 +16,11 @@ Build Requirements
 To compile the userspace programs in the Open vSwitch distribution,
 you will need the following software:
 
 To compile the userspace programs in the Open vSwitch distribution,
 you will need the following software:
 

-    - A make program, e.g. GNU make.  BSD make should also work.
+    - GNU make.

 
     - The GNU C compiler.  We generally test with version 4.1, 4.2, or
       4.3.
 
 
     - The GNU C compiler.  We generally test with version 4.1, 4.2, or
       4.3.
 

-    - pkg-config.  We test with version 0.22.
-

     - libssl, from OpenSSL, is optional but recommended if you plan to
       connect the Open vSwitch to an OpenFlow controller.  libssl is
       required to establish confidentiality and authenticity in the
     - libssl, from OpenSSL, is optional but recommended if you plan to
       connect the Open vSwitch to an OpenFlow controller.  libssl is
       required to establish confidentiality and authenticity in the


@@ -191,22 +190,26 @@ Prerequisites section, follow the procedure below to build.
    additional environment variables.  For a full list, invoke
    configure with the --help option.
 
    additional environment variables.  For a full list, invoke
    configure with the --help option.
 

-3. Run make in the top source directory:
+3. Run GNU make in the top source directory, e.g.:

 
       % make
 
 
       % make
 

-   On FreeBSD you may need to use GNU make (gmake) or NetBSD make
-   (bmake) instead of the native make.
+   or if GNU make is installed as "gmake":
+
+      % gmake

 
    For improved warnings if you installed "sparse" (see
 
    For improved warnings if you installed "sparse" (see

-   "Prerequisites"), add C=1 to the "make" command line.
+   "Prerequisites"), add C=1 to the command line.
+
+4. Consider running the testsuite.  Refer to "Running the Testsuite"
+   below, for instructions.

 
 

-4. Become root by running "su" or another program.
+5. Become root by running "su" or another program.

 
 

-5. Run "make install" to install the executables and manpages into the
+6. Run "make install" to install the executables and manpages into the

    running system, by default under /usr/local.
 
    running system, by default under /usr/local.
 

-6. If you built kernel modules, you may load them with "insmod", e.g.:
+7. If you built kernel modules, you may load them with "insmod", e.g.:

 
       % insmod datapath/linux/openvswitch.ko
 
 
       % insmod datapath/linux/openvswitch.ko
 


@@ -261,7 +264,12 @@ Prerequisites section, follow the procedure below to build.
    you do not understand what this means or do not know if your driver
    will work, do not set this.
 
    you do not understand what this means or do not know if your driver
    will work, do not set this.
 

-7. Initialize the configuration database using ovsdb-tool, e.g.:
+   Once you verify that the kernel modules load properly, you should
+   install them:
+
+      % make modules_install
+
+8. Initialize the configuration database using ovsdb-tool, e.g.:

 
       % mkdir -p /usr/local/etc/openvswitch
       % ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
 
       % mkdir -p /usr/local/etc/openvswitch
       % ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema


@@ -335,6 +343,59 @@ also upgrade the database schema:
 4. Start the Open vSwitch daemons as described under "Building and
    Installing Open vSwitch for Linux or FreeBSD" above.
 
 4. Start the Open vSwitch daemons as described under "Building and
    Installing Open vSwitch for Linux or FreeBSD" above.
 

+Running the Testsuite
+=====================
+
+Open vSwitch includes a testsuite.  Before you submit patches
+upstream, we advise that you run the tests and ensure that they pass.
+If you add new features to Open vSwitch, then adding tests for those
+features will ensure your features don't break as developers modify
+other areas of Open vSwitch.
+
+You must configure and build Open vSwitch (steps 1 through 3 in
+"Building and Installing Open vSwitch for Linux or FreeBSD" above)
+before you run the testsuite.  You do not need to install Open vSwitch
+or to build or load the kernel module to run the testsuite.  You do
+not need supervisor privilege to run the testsuite.
+
+To run all the unit tests in Open vSwitch, one at a time:
+      make check
+This takes under 5 minutes on a modern desktop system.
+
+To run all the unit tests in Open vSwitch, up to 8 in parallel:
+      make check TESTSUITEFLAGS=-j8
+This takes under a minute on a modern 4-core desktop system.
+
+To see a list of all the available tests, run:
+      make check TESTSUITEFLAGS=--list
+
+To run only a subset of tests, e.g. test 123 and tests 477 through 484:
+      make check TESTSUITEFLAGS='123 477-484'
+(Tests do not have inter-dependencies, so you may run any subset.)
+
+To run tests matching a keyword, e.g. "ovsdb":
+      make check TESTSUITEFLAGS='-k ovsdb'
+
+To see a complete list of test options:
+      make check TESTSUITEFLAGS=--help
+
+The results of a testing run are reported in tests/testsuite.log.
+Please report test failures as bugs and include the testsuite.log in
+your report.
+
+If you have "valgrind" installed, then you can also run the testsuite
+under valgrind by using "make check-valgrind" in place of "make
+check".  All the same options are available via TESTSUITEFLAGS.  When
+you do this, the "valgrind" results for test <N> are reported in files
+named tests/testsuite.dir/<N>/valgrind.*.  You may find that the
+valgrind results are easier to interpret if you put "-q" in
+~/.valgrindrc, since that reduces the amount of output.
+
+Sometimes a few tests may fail on some runs but not others.  This is
+usually a bug in the testsuite, not a bug in Open vSwitch itself.  If
+you find that a test fails intermittently, please report it, since the
+developers may not have noticed.
+

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