docs: Moved manual to Doxygen

1 files changed, 186 insertions, 0 deletions

diff --git a/host/docs/build.dox b/host/docs/build.dox
new file mode 100644
index 000000000..1584a7b58
--- /dev/null
+++ b/host/docs/build.dox
@@ -0,0 +1,186 @@
+/*! \page page_build_guide Building and Installing UHD
+
+\tableofcontents
+
+\section build_dependencies Build Dependencies
+
+<b>Linux Notes:</b>
+This is dependent on the distribution you are using, but most, if not all, of
+the dependencies should be available in the package repositories for your
+package manager.
+
+<b>Mac OS X Notes:</b>
+Install the Xcode app to get the build tools (GCC and Make).
+Use MacPorts to get the Boost and Cheetah dependencies.
+Other dependencies can be downloaded as DMG installers from the web
+or installed via MacPorts.
+See the UHD OS X page for more information: http://code.ettus.com/redmine/ettus/projects/uhd/wiki/UHD_OS_X 
+
+<b>Windows Notes:</b>
+The dependencies can be acquired through installable EXE files.
+Usually, the Windows installer can be found on the project's website.
+Some projects do not host Windows installers, and if this is the case,
+follow the auxiliary download URL for the Windows installer (below).
+
+\section git Git
+Required to check out the repository.
+On Windows, install Cygwin with Git support to checkout the repository
+or install msysGit from http://code.google.com/p/msysgit/downloads/list.
+
+\section cpp_compiler C++ Compiler
+
+The following compilers are known to work:
+
+- GCC
+- Clang
+- MSVC
+
+### CMake
+
+- **Purpose:** generates project build files
+- **Minimum Version:** 2.6
+- **Usage:** build time (required)
+- **Download URL:** http://www.cmake.org/cmake/resources/software.html
+
+### Boost
+
+- **Purpose:** C++ library
+- **Minimum Version:** 1.36 (Linux), 1.40 (Windows)
+- **Usage:** build time + runtime (required)
+- **Download URL:** http://www.boost.org/users/download/
+- **Download URL (Windows installer):** http://www.boostpro.com/download
+
+### LibUSB
+
+- **Purpose:** USB-based hardware support
+- **Minimum Version:** 1.0
+- **Usage:** build time + runtime (optional)
+- **Download URL:** http://sourceforge.net/projects/libusb/files/libusb-1.0/
+- **Download URL (Windows):** https://github.com/libusbx/libusbx
+
+### Python
+
+- **Purpose:** used by Cheetah and utility scripts
+- **Minimum Version:** 2.6
+- **Usage:** build time + runtime utility scripts (required)
+- **Download URL:** http://www.python.org/download/
+
+### Cheetah
+
+- **Purpose:** source code generation
+- **Minimum Version:** 2.0
+- **Usage:** build time (required)
+- **Download URL:** http://www.cheetahtemplate.org/download.html
+- **Download URL (Windows installer):** http://feisley.com/python/cheetah/
+
+**Alternative method:**
+Install **setuptools**, and use the **easy_install** command to install Cheetah.
+http://pypi.python.org/pypi/setuptools
+
+### Doxygen
+
+- **Purpose:** generates HTML API documentation
+- **Usage:** build time (optional)
+- **Download URL:** http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+
+**Alternate method:**
+Install **setuptools**, and use the **easy_install** command to install Docutils.
+http://pypi.python.org/pypi/setuptools
+
+\section build_instructions_unix Build Instructions (Unix)
+
+\subsection generate_unix Generate Makefiles with CMake
+
+    cd <uhd-repo-path>/host
+    mkdir build
+    cd build
+    cmake ../
+
+Additionally, configuration variables can be passed into CMake via the command line.
+The following common-use configuration variables are listed below:
+
+- For a custom install prefix: `-DCMAKE_INSTALL_PREFIX=<install-path>`
+- To install libs into lib64: `cmake -DLIB_SUFFIX=64`
+
+Example usage:
+
+    cmake -DCMAKE_INSTALL_PREFIX=/opt/uhd ../
+
+\subsection build_install_unix Build and install
+
+    make
+    make test
+    sudo make install
+
+\subsection libpath_linux Setup the library path (Linux)
+
+Make sure that `libuhd.so` is in your `LD_LIBRARY_PATH`,
+or add it to `/etc/ld.so.conf` and make sure to run:
+
+    sudo ldconfig
+
+\section build_instructions_windows Build Instructions (Windows)
+
+\subsection cmake_win Generate the project with CMake
+
+- 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`.
+- Make sure that the paths do not contain spaces.
+- Click "Configure" and select "Microsoft Visual Studio 10".
+- Set the build variables and click "Configure" again.
+- Click "Generate", and a project file will be created in the build directory.
+
+\subsection libusb_notes LibUSB 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 "Advanced View".
+- Set `LIBUSB_INCLUDE_DIRS` to the directory with `libusb.h`.
+- Set `LIBUSB_LIBRARIES` to the full path for `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, LibUSBx is required to use most USB3 controllers.
+
+\subsection build_in_msvc Build the project in MSVC
+- Open the generated project file in MSVC.
+- 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".
+
+<b>Note:</b>
+You may not have permission to build the install target.
+You need to be an administrator or to run MSVC as administrator.
+
+\section build_msvc_cmd_line Build the project in MSVC (command line)
+Open the Visual Studio Command Prompt Shorcut:
+
+    cd <uhd-repo-path>\host\build
+    DevEnv uhd.sln /build Release /project ALL_BUILD
+    DevEnv uhd.sln /build Release /project INSTALL
+
+\subsection path_env Setup the PATH environment variable
+* Add the UHD bin path to `%PATH%` (usually `C:\\Program Files\\UHD\\bin`)
+
+<b>Note:</b>
+The default interface for editing environment variable paths in Windows is very poor.
+We recommend using "Rapid Environment Editor" (http://www.rapidee.com) over the default editor.
+
+\section post_install_tasks Post-Install Tasks
+
+For USB-based devices,
+see the `USB Transport Application Notes <./transport.html#usb-transport-libusb>`_
+for platform-specific post-installation tasks.
+
+\section post_install_tasks_macosx Post-Install Tasks (Mac OS X)
+
+Make sure that the value of `CMAKE_INSTALL_PREFIX` is at or near the 
+front of the shell `PATH` environment variable.  Do \b NOT set 
+`DYLD_LIBRARY_PATH` or any related DYLD environment variable 
+permanently; these work differently than under Linux and should be 
+used for testing / temporary purposes only. 
+
+*/
+// vim:ft=doxygen: