Merge branch 'usrp_e' of ettus.sourcerepo.com:ettus/uhdpriv into usrp_e

1 files changed, 46 insertions, 16 deletions

diff --git a/host/docs/build.rst b/host/docs/build.rst
index d7dfd05e5..a41ce8331 100644
--- a/host/docs/build.rst
+++ b/host/docs/build.rst
@@ -40,32 +40,33 @@ CMake
 ^^^^^^^^^^^^^^^^
 * **Purpose:** generates project build files
 * **Version:** at least 2.8
-* **Required for:** build time
+* **Usage:** build time (required)
 * **Download URL:** http://www.cmake.org/cmake/resources/software.html
 
 ^^^^^^^^^^^^^^^^
 Boost
 ^^^^^^^^^^^^^^^^
 * **Purpose:** C++ library
-* **Version:** at least 3.6 unix, at least 4.0 windows
-* **Required for:** build time + run time
+* **Version:** at least 1.36 unix, at least 1.40 windows
+* **Usage:** build time + run time (required)
 * **Download URL:** http://www.boost.org/users/download/
 * **Download URL (windows installer):** http://www.boostpro.com/download
 
 ^^^^^^^^^^^^^^^^
 LibUSB
 ^^^^^^^^^^^^^^^^
-* **Purpose:** USB userspace library
+* **Purpose:** USB-based hardware support
 * **Version:** at least 1.0
-* **Required for:** build time + run time (optional)
-* **Download URL:** http://www.libusb.org/
+* **Usage:** build time + run time (optional)
+* **Download URL:** http://sourceforge.net/projects/libusb/files/libusb-1.0/
+* **Download URL (windows binaries):** http://www.libusb.org/wiki/windows_backend#LatestBinarySnapshots
 
 ^^^^^^^^^^^^^^^^
 Python
 ^^^^^^^^^^^^^^^^
 * **Purpose:** used by Cheetah and utility scripts
 * **Version:** at least 2.6
-* **Required for:** build time + run time utility scripts
+* **Usage:** build time + run time utility scripts (required)
 * **Download URL:** http://www.python.org/download/
 
 ^^^^^^^^^^^^^^^^
@@ -73,7 +74,7 @@ Cheetah
 ^^^^^^^^^^^^^^^^
 * **Purpose:** source code generation
 * **Version:** at least 2.0
-* **Required for:** build time
+* **Usage:** build time (required)
 * **Download URL:** http://www.cheetahtemplate.org/download.html
 * **Download URL (windows installer):** http://feisley.com/python/cheetah/
 
@@ -81,14 +82,14 @@ Cheetah
 Doxygen
 ^^^^^^^^^^^^^^^^
 * **Purpose:** generates html api documentation
-* **Required for:** build time (optional)
+* **Usage:** build time (optional)
 * **Download URL:** http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
 
 ^^^^^^^^^^^^^^^^
 Docutils
 ^^^^^^^^^^^^^^^^
 * **Purpose:** generates html user manual
-* **Required for:** build time (optional)
+* **Usage:** build time (optional)
 * **Download URL:** http://docutils.sourceforge.net/
 
 ------------------------------------------------------------------------
@@ -105,9 +106,16 @@ Generate Makefiles with cmake
     cd build
     cmake ../
 
-**Notes:**
+Additionally, configuration variables can be passed into cmake via the command line.
+The following common-use configuration variables are listed below:
 
-* For a custom prefix, use: cmake -DCMAKE_INSTALL_PREFIX=<prefix> ../
+* For a custom install prefix: -DCMAKE_INSTALL_PREFIX=<prefix>
+* To install libs into lib64: cmake -DLIB_SUFFIX=64
+
+Example usage:
+::
+
+    cmake -DCMAKE_INSTALL_PREFIX=/opt/uhd ../
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Build and install
@@ -145,6 +153,19 @@ Generate the project with cmake
 * Click generate and a project file will be created in the build directory.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+LibUSB cmake notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+On Windows, cmake does not have the advantage of pkg-config,
+so we must manually tell cmake how to locate the LibUSB header and lib.
+
+From the cmake gui, select "Advanded View":
+
+* Set LIBUSB_INCLUDE_DIR to the directory with "libusb.h".
+* Set LIBUSB_LIBRARIES to the full path for "libusb-1.0.lib".
+
+Then check the boxes to enable USRP1 support, click configure and generate.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Build the project in MSVC
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Open the generated project file in MSVC.
@@ -155,14 +176,23 @@ Build the project in MSVC
 **Note:** you may not have permission to build the install target.
 You need to be an administrator or to run MSVC as administrator.
 
-** alternative command line instructions **
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Build the project in MSVC (command line)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Open the Visual Studio Command Prompt Shorcut:
+::
 
-* Open the Visual Studio Command Prompt Shorcut
-* DevEnv <uhd-repo-path>\host\build\ALL_BUILD.vcproj /Build Release
-* DevEnv <uhd-repo-path>\host\build\INSTALL.vcproj /Build Release
+    cd <uhd-repo-path>\host\build
+    DevEnv ALL_BUILD.vcproj /Build Release
+    DevEnv INSTALL.vcproj /Build Release
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Setup the PATH environment variable
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Add the boost library path to %PATH% (usually c:\\program files\\boost\\<version>\\lib)
 * Add the uhd library path to %PATH% (usually c:\\program files\\uhd\\lib)
+* Add the libusb library to %PATH% (if using usb support)
+
+**Note:**
+The interface for editing environment variable paths in Windows is very poor.
+I recommend using "Rapid Environment Editor" (http://www.rapidee.com) over the default editor.