docs: Improved Windows-related build instructions

- In general, some comments to clarify the dependencies installation and building process for windows users.
- Add a comment to the required packages for MSCV.
- Provide instructions to install Python requirements.
- Add the instructions of NSIS installation.
- Add comments to the version match between different installers.
- Clarify the instructions of building process using Cmake
- Add a subsection to show how a binary UHD installer can be obtained.
- Correct the URL of Doxygen.

1 files changed, 65 insertions, 13 deletions

diff --git a/host/docs/build.dox b/host/docs/build.dox
index b5e9caaf5..d0734786e 100644
--- a/host/docs/build.dox
+++ b/host/docs/build.dox
@@ -28,7 +28,8 @@ The following compilers are known to work and officially supported:
 
 - GCC >= 4.8
 - Clang >= 3.3
-- MSVC >= 2015 (14.0); the free version works.
+- MSVC >= 2015 (14.0); the free version works. Users need to install the "Desktop Development with C++" Workload for Visual Studio. On Windows, it can be found in: Tools -> Get Tools and Features... -> Workloads -> Windows
+
 
 Other compilers (or lower versions) may work, but are unsupported.
 
@@ -39,6 +40,8 @@ Other compilers (or lower versions) may work, but are unsupported.
 - **Usage:** build time (required)
 - **Download URL:** http://www.cmake.org/cmake/resources/software.html
 
+For Windows users, copy the CMake file to Program Files, e.g. `C:\Program Files\cmake-3.13.4-win32-x86`. The CMake path, e.g. `C:\Program Files\cmake-3.13.4-win32-x86\bin` needs to be added to the environment variables.
+
 ### Boost
 
 - **Purpose:** C++ library
@@ -47,6 +50,8 @@ Other compilers (or lower versions) may work, but are unsupported.
 - **Download URL:** http://www.boost.org/users/download/
 - **Download URL (Windows installer):** http://sourceforge.net/projects/boost/files/boost-binaries/
 
+The Boost binary installer must be selected to match the architecture of Windows being run.
+
 ### LibUSB
 
 - **Purpose:** USB-based hardware support
@@ -55,12 +60,33 @@ Other compilers (or lower versions) may work, but are unsupported.
 - **Download URL:** http://sourceforge.net/projects/libusb/files/libusb-1.0/
 - **Download URL (Windows):** https://github.com/libusb/libusb
 
+The directory to which you extract libusb must not contain spaces. This is to say that `C:\local\lib usb-1.0.22` will cause compile issues moving forward.
+
 ### Python
 
 - **Purpose:** Used by mako build time,  and utility scripts and the Python API at runtime
 - **Minimum Version:** 2.7
 - **Usage:** build time + runtime utility scripts (required)
 - **Download URL:** http://www.python.org/download/
+- **Comments for Windows Users:**
+  - The Python binary installer must be selected to match the system processor. Although, the 32-bit Python version can be used with 32-bit or 64-bit Windows system, it is recommended to match between Python and Windows installers. If the system is occupied with 64-bit Windows and x64-based processor, the `Windows x86-64 MSI Installer -> python-version.amd64.msi` needs to be used.
+  - The Python path needs to be added to the environment variables.
+  - Install fundamental packages for Python: On Windows Terminal, navigate to Python scripts folder, e.g. `C:\local\Python37\Scripts`, and execute the following commands to install requests, numpy and six packages, respectively:
+
+    pip install requests
+    pip install numpy
+    pip install six
+
+  - For curses package installation:
+    - Download URL: https://www.lfd.uci.edu/~gohlke/pythonlibs/
+    - Download a package that is similar to the Python version, Windows System, and system processor and copy it to Python scripts folder. For example, for Python 3.7, 64-bit Windows, and x64-based processor, download the `curses-2.2-cp37-cp37m-win_amd64.whl`.
+    - Install the package dependency, wheel package:
+
+    pip install wheel
+
+    - Install the curses package and include it to Python scripts:
+
+    python -m pip install curses-2.2-cp37-cp37m-win_amd64.whl
 
 ### Mako
 
@@ -68,21 +94,31 @@ Other compilers (or lower versions) may work, but are unsupported.
 - **Minimum Version:** 0.5.0
 - **Usage:** build time (required)
 - **Download URL:** http://www.makotemplates.org/download.html
-- **Alternative method:** You can use `pip` or `easy_install` to install Mako from PyPi.
+- **Alternative method:** You can use `pip` or `easy_install` to install Mako from PyPi. To install it using 'pip' on Windows, navigate to Python scripts folder, e.g. ´C:\local\Python37\Scripts`, and run the following command:
+
+    pip install mako
 
 ### Doxygen
 
 - **Purpose:** generates HTML API documentation
 - **Minimum Recommended Version:** 1.8
 - **Usage:** build time (optional)
-- **Download URL:** http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+- **Download URL:** http://www.doxygen.nl/download.html
+
 - **Alternate method:** Install **setuptools**, and use the **easy_install** command to install Docutils. http://pypi.python.org/pypi/setuptools
 
+### NSIS
+
+- **Purpose:** create Windows installers. It is used to create binary packages of UHD enabling easy distribution and installation of UHD, associated utilities, and examples.
+- **Recommended Version:** 3.04
+- **Usage:** build time (optional)
+- **Download URL (Windows):** https://nsis.sourceforge.io/Download
+
 ### Git
 
 Required to check out the repository (not necessary if building from tarballs).
 
-On Windows, install Cygwin with Git support to checkout the repository
+On Windows, install Cygwin from https://www.cygwin.com/ with Git support to checkout the repository
 or install msysGit from http://code.google.com/p/msysgit/downloads/list.
 
 \subsection build_dependencies_ubuntu Setting up the dependencies on Ubuntu
@@ -185,16 +221,28 @@ extensions:
 
 \subsection cmake_win Generate the project with CMake
 
+- Enable Python3 option in the CMake list if the version of installed Python is >=3, otherwise go to the next step.
+  - Go to the source code: `<uhd-repo-path>/host`.
+  - Open 'CMakeLists.txt'.
+  - Find 'ENABLE_PYTHON3' option and set it to 'ON', e.g. 'option(ENABLE_PYTHON3 "Enable Python 3. Default is Python 2" ON)'.
 - Open the CMake GUI.
 - Set the path to the source code: `<uhd-repo-path>/host`.
-- Set the path to the build directory: `<uhd-repo-path>/host/build`.
+- Set the path to the build directory (this may require creating the folder \build\): `<uhd-repo-path>/host/build`.
 - Make sure that the paths do not contain spaces.
-- Click "Configure" and select "Microsoft Visual Studio 10".
-- Set the build variables
-  - `Boost_INCLUDE_DIR` should point to the `PATH` where the Boost .hpp files are, e.g. `C:\local\boost_version\boost`
+- Check the Advanced checkbox.
+- Click "Configure".
+  - Set "Microsoft Visual Studio 10" as the compiler. Select the recent MSVC that is available on the machine.
+  - Click “Finish” and allow CMake to Generate
+- Set or add the build variables with type PATH
+  - `Boost_INCLUDE_DIR` should point to the `PATH` where the Boost .hpp files are, e.g. `C:\local\boost_version\`
   - `Boost_LIBRARY_DIR` should point to the pre-built libraries, e.g. `C:\local\boost_version\lib64-msvc-14.0`)
-  .
-- Click "Generate", and a project file will be created in the build directory.
+- If a release UHD build is required:
+  - Click on "Generate", and a project file will be created in the build directory.
+- If a debug UHD build is required:
+  - Click on Grouped
+  - Click on `CMAKE`
+  - Look for the parameter `CMAKE_BUILD_TYPE: Release` and change it to `CMAKE_BUILD_TYPE: Debug`.
+  - Click on "Generate", and a project file will be created in the build directory.
 
 \subsection msvc_generate Compile and Install with Visual Studio
 - Open the `<uhd-repo-path>\\host\\build\\ALL_BUILD.vcxproj` in visual studio, generate the project. Watch the output console for errors.
@@ -207,15 +255,15 @@ 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 "Advanced View".
-- Set `LIBUSB_INCLUDE_DIRS` to the directory with `libusb.h`.
-- Set `LIBUSB_LIBRARIES` to the full path for `libusb-1.0.lib`.
+- Set or add the following entry with type PATH `LIBUSB_INCLUDE_DIRS` to the directory for `libusb.h`, e.g. `C:\local\libusb-1.0.22\include\libusb-1.0`.
+- Set or add the following entry with type FILEPATH `LIBUSB_LIBRARIES` to the full path for `libusb-1.0.lib`, e.g. `C:\local\libusb-1.0.22\MS64\dll\libusb-1.0.lib`.
 - Recommend the static `libusb-1.0.lib` to simplify runtime dependencies.
 - Check the box to enable USB support, click "Configure" and "Generate".
 
 <b>Note:</b> On Windows, LibUSB v1.0.19 is required to use most USB3 controllers.
 
 \subsection build_in_msvc Build the project in MSVC
-- Open the generated project file in MSVC.
+- Open the generated project file in MSVC, e.g. `C:\cygwin64\home\admin\uhd\host\build\UHD.sln`.
 - Change the build type from "Debug" to "Release".
 - Select the "Build All" target, right-click, and choose "Build".
 - Select the install target, right-click, and choose "Build".
@@ -231,6 +279,10 @@ Open the Visual Studio Command Prompt Shorcut:
     DevEnv uhd.sln /build Release /project ALL_BUILD
     DevEnv uhd.sln /build Release /project INSTALL
 
+\subsection compile_binary_installer_mscv Compiling a binary installer
+- Building the "PACKAGE" project will produce a binary installer if NSIS is installed. This installer will be for either 64 bit or 32 bit as chosen during the CMake step.
+- Select the "PACKAGE" project in the Solution Explorer, right-click, and choose "Build".
+
 \subsection path_env Setup the PATH environment variable
 * Add the UHD bin path to `%PATH%` (usually `C:\\Program Files\\UHD\\bin`)