Out-of-Tree Configuration

New as of 3.6.5.

Using gr_modtool, each package comes with the ability to easily locate the gnuradio-runtime library using the 'find_package(GnuradioRuntime)' cmake command. This only locates the gnuradio-runtime library and include directory, which is enough for most simple projects.

As projects become more complicated and start needing to rely on other GNU Radio components like gnuradio-blocks or gnuradio-filter, for example, and when they become dependent on certain API compatibility versions of GNU Radio, we need something more. And so we have introduced the GnuradioConfig.cmake file.

When GNU Radio is installed, it also installs a GNU Radio-specific cmake config file that we can use for more advanced compatibility issues of our projects. This tool allows us to specific the API compatible version and a set of components that are required.

Taking the above example, say we have built against version 3.6.5 with features that were introduced in this version and we need the blocks and filter components as well as the main core library. We fist set a cmake variable GR_REQUIRED_COMPONENTS to the components we need. We then use the 'find_package' command and also set a minimum required API compatible version. Since we are on the 3.6 API version, the minimum required version is "3.6.5". The code in the CMakeLists.txt file would look like this:

set(GR_REQUIRED_COMPONENTS RUNTIME BLOCKS FILTER)
find_package(Gnuradio 3.6.5)

Note that the capitalization is important on both lines.

If the installed version of GNU Radio is 3.6.4 or some other API version like 3.5 or 3.7, the Cmake configuration will fail with the version error. Likewise, if libgnuradio-filter was not installed as part of GNU Radio, the configuration will also fail.

Install Path

Cmake has to know where to find either the package config files or the GnuradioConfig.cmake script. The package config files are located in $prefix/lib/pkgconfig while all of the Cmake scripts from GNU Radio are installed into $prefix/lib/cmake/gnuradio.

If the installed GNU Radio $prefix is '/usr' or '/usr/local', then everything should work fine. If the GNU Radio install $prefix is something else, then Cmake must be told where to find it. This can be done in a few ways:

1. If you are installing the out-of-tree module into the same $prefix, then you would be setting '-DCMAKE_INSTALL_PREFIX' on the configuration command line. This is enough to tell Cmake where to look for the configuration files.
2. Cmake will try to find the package config (*.pc) files. If it can, these files will instruct Cmake where to look for the rest of the configuration options. If this is not set, it can be set as:

export PKG_CONFIG_PATH=$prefix/lib/pkgconfg:$PKG_CONFIG_PATH

1. Set the CMAKE_PREFIX_PATH environmental variable to $prefix.

export CMAKE_PREFIX_PATH=$prefix:$CMAKE_PREFIX_PATH

With method 1, you will be installing your OOT project into the same $prefix as GNU Radio. With methods 2 and 3, you can install your component anywhere you like (using -DCMAKE_INSTALL_PREFIX).