diff options
| author | Tom Rondeau <trondeau@vt.edu> | 2013-05-07 19:20:02 -0400 |
|---|---|---|
| committer | Tom Rondeau <trondeau@vt.edu> | 2013-05-07 19:26:15 -0400 |
| commit | e5612be51e40a02cf948786c51166a584b1ff8f6 (patch) | |
| tree | 396833613594e06554e578551094ecc67cce9c36 /docs/doxygen/other | |
| parent | cc12277f64207ff79a40094268c843e6b3e2d2d3 (diff) | |
build: fixed GnuradioConfig files for OOTs to use.
Diffstat (limited to 'docs/doxygen/other')
| -rw-r--r-- | docs/doxygen/other/main_page.dox | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/docs/doxygen/other/main_page.dox b/docs/doxygen/other/main_page.dox index 9353bfb315..916ac9bdd1 100644 --- a/docs/doxygen/other/main_page.dox +++ b/docs/doxygen/other/main_page.dox @@ -404,4 +404,63 @@ configuration variable and the section and option names are in uppercase. The value is the same format that would be used in the config file itself. + + +\section oot_config_page Out-of-Tree Configuration + +New as of 3.6.5. + +Using gr_modtool, each package comes with the ability to easily locate +the gnuradio-core library using the 'find_package(GnuradioCore)' cmake +command. This only locates that the library and include directories +exist, 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: + +\code + set(GR_REQUIRED_COMPONENTS RUNTIME BLOCKS FILTER) + find_package(Gnuradio 3.6.5) +\endcode + +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. + +\subsection oot_config_path_page Install Path + +Cmake has to know where to find these configuration files. They are +installed into $prefix/lib/cmake/gnuradio. If $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 two ways. 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. + +The other way to do it is to set the CMAKE_PREFIX_PATH environmental +variable to $prefix. You can then install your component anywhere +you'd like and it will be able to find and configure against the +installed GNU Radio. + */ |