[ovs-dev] [PATCH] INSTALL.md: Split building steps to allow refs

Wed Jan 7 14:13:34 UTC 2015

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 <fbl at redhat.com>
---
 INSTALL.md | 138 ++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 78 insertions(+), 60 deletions(-)

diff --git a/INSTALL.md b/INSTALL.md
index 122c362..8fae214 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -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`
 
@@ -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`
@@ -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`
@@ -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
@@ -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:
 
-- 
2.1.0


