Linux Notes: 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.
Mac OS X Notes: Install the Xcode app to get the build tools (GCC and Make). Use MacPorts to get the Boost and Mako dependencies. Other dependencies can be downloaded as DMG installers from the web or installed via MacPorts. See the UHD OS X build instructions for more information: Build Instructions (Mac OS X)
Windows Notes: 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).
The following compilers are known to work and officially supported:
Other compilers (or lower versions) may work, but are unsupported.
easy_installto install Mako from PyPi.
Required to check out the repository (not necessary if building from tarballs).
On Windows, install Cygwin with Git support to checkout the repository or install msysGit from http://code.google.com/p/msysgit/downloads/list.
You can install all the dependencies through the package manager:
sudo apt-get install libboost-all-dev libusb-1.0-0-dev python-mako doxygen python-docutils cmake build-essential
Your actual command may differ.
You can install all the dependencies through the package manager:
sudo yum -y install boost-devel libusb1-devel python-mako doxygen python-docutils cmake make gcc gcc-c++
sudo dnf -y install boost-devel libusb1-devel python-mako doxygen python-docutils cmake make gcc gcc-c++
Your actual command may differ.
The UHD source is stored in a Git repository. To download it, follow these instructions:
git clone git://github.com/EttusResearch/uhd.git
If you also want the FPGA code (which is not necessary for building UHD and applications which depend on it), run:
git clone --recursive git://github.com/EttusResearch/uhd.git
This will populate the
fpga-src submodule inside the repository. You can also do this after cloning the repository by running these commands from the top level source directory:
git submodule init git submodule update
Our source code repository contains of two main branches:
We might also be publishing experimental feature branches which can then be found in the same repository. All of our versioned releases are associated with tags in the repository.
PyBOMBS is a command-line tool for Linuxes (and some Unixes) from the GNU Radio ecosystem and will do a source build of UHD, including setting up prerequisites/dependencies (regardless of the distribution). Assuming you have PyBOMBS set up, you can install UHD with the following command:
$ pybombs install uhd
Head to the PyBOMBS Homepage for more instructions. PyBOMBS can install UHD (as well as GNU Radio or similar projects) both into system directories as well as into user's home directories, omitting the requirement for superuser access.
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:
cmake -DCMAKE_INSTALL_PREFIX=/opt/uhd ../
make make test sudo make install
Make sure that
libuhd.so is in your
LD_LIBRARY_PATH, or add it to
/etc/ld.so.conf and make sure to run:
Boost_INCLUDE_DIRshould point to the
PATHwhere the Boost .hpp files are, e.g.
Boost_LIBRARY_DIRshould point to the pre-built libraries, e.g.
<uhd-repo-path>\\host\\build\\ALL_BUILD.vcxprojin visual studio, generate the project. Watch the output console for errors.
CMAKE_INSTALL_PREFIXwhere your user has write privileges, you must close Visual Studio, run it again with Administrator Privileges, and open
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.
LIBUSB_INCLUDE_DIRSto the directory with
LIBUSB_LIBRARIESto the full path for
libusb-1.0.libto simplify runtime dependencies.
Note: On Windows, LibUSB v1.0.19 is required to use most USB3 controllers.
Note: You may not have permission to build the install target. You need to be an administrator or to run MSVC as administrator.
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
Add the UHD bin path to
Note: 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.
For the purposes of building and using UHD, you can use Apple's Terminal.app if you so choose, no matter how you install UHD.
That said, running almost any graphical interface (GUI) will require downloading and installing X11/XQuartz first. Through OSX 10.8, Apple provided a means to install X11.app, but XQuartz has always been more up to date. Staring in 10.9, Apple no longer provides a full working version of X11.app. Hence, just use XQuartz from the get-go. Note that unless you experiment with using the Quartz interface to various graphical toolkits (e.g., GTK), you must use X11 as the terminal interface for any GUI applications.
Apple provides a fully integrated development environment via their Xcode toolkit, which can be downloaded either via the App store or directly from Apple's Developer area depending on the version of OSX in use. Xcode provides the compilers and related development tools needed to build or execute UHD and its dependencies.
Once Xcode is installed, you must still install the Command Line Tools, which can be accomplished by running Xcode.app, then going to Preferences... -> Downloads and making sure Command Line Tools is selected/enabled [feel free to select other downloads too]. You might be able to install the Command Line Tools in a terminal using
but this command will not work with every OSX / Xcode combination (e.g., does not work with OSX 10.8 and Xcode 5, but does work with OSX 10.9 and Xcode 5).
Once the Command Line Tools are installed, UHD and other projects can be installed either from source or, preferably, via MacPorts.
There are a number of background libraries and applications that must be installed from source or binary in order to compile or execute UHD; for a full list, see Build Dependencies. These can be obtained by using MacPorts, Fink, HomeBrew, and/or from source / scratch. MacPorts tends to be more up-to-date with respect to new releases, which can be both a blessing and a curse since sometimes new released are untested and result in build or runtime errors. MacPorts, HomeBrew, and Fink offer thousands of ready-to-install libraries and applications, and hence they are highly recommended to use instead of installing from source / scratch.
Many UHD developers first install UHD using MacPorts in order to get all of the necessary background dependencies installed, then remove just UHD via
sudo port install uhd sudo port uninstall uhd
NOTE: We highly recommended that all dependencies be installed via the same package manager! When issues arise, they are much easier to track down, and updating to newer versions of UHD as well as dependencies is much easier.
NOTE: Other package managers (e.g., Fink, HomeBrew) will require diffrent commands than the above to install all dependencies and then remove the UHD install. Please consult the specific package manager in use for how to do these commands properly; they will not be covered here.
Installing UHD from source follows the standard cmake method as found in many places, with a few arguments to make sure cmake always finds the correct version of Python, and uses the desired compiler. First, download the source code either via a release or via GIT.
For example, on OSX 10.8+ and using Xcode's legacy Apple GCC (via llvm), MacPorts installed into /opt/local (the default), and for Python 2.7 as installed by MacPorts, issue the following commands from within the UHD source directory:
$ mkdir build $ cd build $ CC=/usr/bin/llvm-gcc CXX=/usr/bin/llvm-g++ cmake -DCMAKE_INSTALL_PREFIX=/opt/local -DPYTHON_EXECUTABLE=/opt/local/bin/python2.7 -DPYTHON_INCLUDE_DIR=/opt/local/Library/Frameworks/Python.framework/Versions/2.7/Headers -DPYTHON_LIBRARY=/opt/local/Library/Frameworks/Python.framework/Versions/2.7/Python ../host $ make
If make succeeds, then you can test the build for errors via
$ make test
To install the build, issue
$ sudo make install
Selecting another compiler is as simple as changing the CC and CXX pre-arguments to the cmake command. Similarly, one can change the install prefix by changing the setting of the variable CMAKE_INSTALL_PREFIX.
NOTE: All of the PYTHON defines must point to the same install of Python, otherwise runtime errors are likely to occur.
NOTE: When using some other package manager (e.g., Fink, HomeBrew), the actual variable settings (-D...=...) will be different than those above. Please consult the specific package manager in use for how to do these settings properly; they will not be covered here.
uhd_images_downloaderon the command line, or one of these executables (the actual path may differ based on your installation):
If your application uses CMake as a build system, the following command will setup up your build environment to link against UHD:
This will set the CMake variable
See the example in
examples/init_usrp for more details, as well as the UHDConfig.cmake file that gets installed along with the UHD libraries.
Using CMake, UHD can be built as a static library by switching on
cmake -DENABLE_STATIC_LIBS=ON <path to UHD source>
When linking the static library, you must ensure that the library is loaded in its entirety, otherwise global objects aren't initialized at load-time and it will always fail to detect any devices. Also, all UHD dependencies for UHD must be provided unless your linker has other ways of resolving library dependencies.
With the GNU ld linker (e.g. on Linux platforms), this is done using the
--whole-archive switch. Using the GNU C++ compiler, the correct command line is:
g++ your_uhd_app.cpp -Wl,-whole-archive <path to UHD libs>/libuhd.a -Wl,-no-whole-archive -ldl -lpthread -l<all other libraries>
--whole-archive is disabled after including
libuhd.a. The exact list of libraries depends on your UHD build. When using
UHDConfig.cmake (see Building applications that require UHD using CMake), the path to
libuhd.a is saved into
UHD_STATIC_LIB_DEPS lists the required dependencies. See
UHDConfig.cmake for details.