diff options
Diffstat (limited to 'host/docs/build.dox')
| -rw-r--r-- | host/docs/build.dox | 186 |
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: |