Skip to content

Commit

Permalink
INSTALL.md: Split building steps to allow refs
Browse files Browse the repository at this point in the history 
There are other parts of the document that needs to
reference some building steps.  Instead of copying
and explaining again, this patch splits the building
section in three sections that can be referenced.

Signed-off-by: Flavio Leitner <[email protected]>
Signed-off-by: Thomas Graf <[email protected]>
  • Loading branch information
@fleitner
fleitner authored and Thomas Graf committed Jan 7, 2015
1 parent 0234d90 commit e9e8544
Showing 1 changed file with 78 additions and 60 deletions.
138 changes: 78 additions & 60 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -147,82 +147,96 @@ devices, you must also ensure that /dev/net/tun exists.
Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD
=================================================================

Once you have installed all the prerequisites listed above in the Base
Prerequisites section, follow the procedure below to build.
Once you have installed all the prerequisites listed above in the
Base Prerequisites section, follow the procedures below to bootstrap,
to configure and to build the code.

1. If you pulled the sources directly from an Open vSwitch Git tree,
run boot.sh in the top source directory:
Bootstrapping the Sources
-------------------------

This step is not needed if you have downloaded a released tarball.
If you pulled the sources directly from an Open vSwitch Git tree or
got a Git tree snapshot, then run boot.sh in the top source directory
to build the "configure" script.

`% ./boot.sh`

2. Configure the package by running the configure script. You can
usually invoke configure without any arguments. For example:

Configuring the Sources
-----------------------

Configure the package by running the configure script. You can
usually invoke configure without any arguments. For example:

`% ./configure`

By default all files are installed under /usr/local. If you want
to install into, e.g., /usr and /var instead of /usr/local and
/usr/local/var, add options as shown here:
By default all files are installed under /usr/local. If you want
to install into, e.g., /usr and /var instead of /usr/local and
/usr/local/var, add options as shown here:

`% ./configure --prefix=/usr --localstatedir=/var`

By default, static libraries are built and linked against. If you
want to use shared libraries instead:
By default, static libraries are built and linked against. If you
want to use shared libraries instead:

% ./configure --enable-shared

To use a specific C compiler for compiling Open vSwitch user
programs, also specify it on the configure command line, like so:
To use a specific C compiler for compiling Open vSwitch user
programs, also specify it on the configure command line, like so:

`% ./configure CC=gcc-4.2`

To use 'clang' compiler:
To use 'clang' compiler:

`% ./configure CC=clang`

To build the Linux kernel module, so that you can run the
kernel-based switch, pass the location of the kernel build
directory on --with-linux. For example, to build for a running
instance of Linux:
To build the Linux kernel module, so that you can run the
kernel-based switch, pass the location of the kernel build
directory on --with-linux. For example, to build for a running
instance of Linux:

`% ./configure --with-linux=/lib/modules/`uname -r`/build`

If --with-linux requests building for an unsupported version of
Linux, then "configure" will fail with an error message. Please
refer to the [FAQ.md] for advice in that case.
If --with-linux requests building for an unsupported version of
Linux, then "configure" will fail with an error message. Please
refer to the [FAQ.md] for advice in that case.

If you wish to build the kernel module for an architecture other
than the architecture of the machine used for the build, you may
specify the kernel architecture string using the KARCH variable
when invoking the configure script. For example, to build for MIPS
with Linux:
If you wish to build the kernel module for an architecture other
than the architecture of the machine used for the build, you may
specify the kernel architecture string using the KARCH variable
when invoking the configure script. For example, to build for MIPS
with Linux:

`% ./configure --with-linux=/path/to/linux KARCH=mips`

If you plan to do much Open vSwitch development, you might want to
add --enable-Werror, which adds the -Werror option to the compiler
command line, turning warnings into errors. That makes it
impossible to miss warnings generated by the build.
If you plan to do much Open vSwitch development, you might want to
add --enable-Werror, which adds the -Werror option to the compiler
command line, turning warnings into errors. That makes it
impossible to miss warnings generated by the build.

To build with gcov code coverage support, add --enable-coverage,
e.g.:
To build with gcov code coverage support, add --enable-coverage,
e.g.:

`% ./configure --enable-coverage`

The configure script accepts a number of other options and honors
additional environment variables. For a full list, invoke
configure with the --help option.
The configure script accepts a number of other options and honors
additional environment variables. For a full list, invoke
configure with the --help option.

You can also run configure from a separate build directory. This
is helpful if you want to build Open vSwitch in more than one way
from a single source directory, e.g. to try out both GCC and Clang
builds, or to build kernel modules for more than one Linux version.
Here is an example:
You can also run configure from a separate build directory. This
is helpful if you want to build Open vSwitch in more than one way
from a single source directory, e.g. to try out both GCC and Clang
builds, or to build kernel modules for more than one Linux version.
Here is an example:

`% mkdir _gcc && (cd _gcc && ../configure CC=gcc)`
`% mkdir _clang && (cd _clang && ../configure CC=clang)`

3. Run GNU make in the build directory, e.g.:

Building the Sources
--------------------

1. Run GNU make in the build directory, e.g.:

`% make`

Expand All @@ -236,18 +250,18 @@ Prerequisites section, follow the procedure below to build.
`% make -C _gcc`
`% make -C _clang`

For improved warnings if you installed "sparse" (see
"Prerequisites"), add C=1 to the command line.
For improved warnings if you installed "sparse" (see "Prerequisites"),
add C=1 to the command line.

4. Consider running the testsuite. Refer to "Running the Testsuite"
2. Consider running the testsuite. Refer to "Running the Testsuite"
below, for instructions.

5. Become root by running "su" or another program.
3. Become root by running "su" or another program.

6. Run "make install" to install the executables and manpages into the
4. Run "make install" to install the executables and manpages into the
running system, by default under /usr/local.

7. If you built kernel modules, you may install and load them, e.g.:
5. If you built kernel modules, you may install and load them, e.g.:

`% make modules_install`
`% /sbin/modprobe openvswitch`
Expand Down Expand Up @@ -292,19 +306,19 @@ Prerequisites section, follow the procedure below to build.
module loading, please include the output from the `dmesg` and
`modinfo` commands mentioned above.

There is an optional module parameter to openvswitch.ko called
vlan_tso that enables TCP segmentation offload over VLANs on NICs
that support it. Many drivers do not expose support for TSO on VLANs
in a way that Open vSwitch can use but there is no way to detect
whether this is the case. If you know that your particular driver can
handle it (for example by testing sending large TCP packets over VLANs)
then passing in a value of 1 may improve performance. Modules built for
Linux kernels 2.6.37 and later, as well as specially patched versions
of earlier kernels, do not need this and do not have this parameter. If
you do not understand what this means or do not know if your driver
will work, do not set this.
There is an optional module parameter to openvswitch.ko called
vlan_tso that enables TCP segmentation offload over VLANs on NICs
that support it. Many drivers do not expose support for TSO on VLANs
in a way that Open vSwitch can use but there is no way to detect
whether this is the case. If you know that your particular driver can
handle it (for example by testing sending large TCP packets over VLANs)
then passing in a value of 1 may improve performance. Modules built for
Linux kernels 2.6.37 and later, as well as specially patched versions
of earlier kernels, do not need this and do not have this parameter. If
you do not understand what this means or do not know if your driver
will work, do not set this.

8. Initialize the configuration database using ovsdb-tool, e.g.:
6. 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`
Expand Down Expand Up @@ -426,7 +440,7 @@ Testsuites
==========
This section describe Open vSwitch's built-in support for various test
suites. You must configure and build Open vSwitch (steps 1 through 3
suites. You must bootstrap, configure and build Open vSwitch (steps are
in "Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD"
above) before you run the tests described here. You do not need to
install Open vSwitch or to build or load the kernel module to run
Expand Down Expand Up @@ -567,6 +581,10 @@ Vagrant
Requires: Vagrant and a compatible hypervisor
You must bootstrap and configure the sources (steps are in "Building
and Installing Open vSwitch for Linux, FreeBSD or NetBSD" above) before
you run the steps described here.
A Vagrantfile is provided allowing to compile and provision the source
tree as found locally in a virtual machine using the following commands:
Expand Down

0 comments on commit e9e8544

Please sign in to comment.