diff options
| author | Martin Braun <martin.braun@ettus.com> | 2014-07-16 11:41:52 +0200 |
|---|---|---|
| committer | Martin Braun <martin.braun@ettus.com> | 2014-07-22 21:38:47 +0200 |
| commit | a9c3d8ff3bc31117309004c16860d18f26369311 (patch) | |
| tree | 4566e2c2cf868bb471a6cc81e3148a3aef1b061a /docs/doxygen/other/oot_config.dox | |
| parent | d09b971d01f4e65eff80065796d724d88168866d (diff) | |
docs: Restructured intro page, added some manual pages
Diffstat (limited to 'docs/doxygen/other/oot_config.dox')
| -rw-r--r-- | docs/doxygen/other/oot_config.dox | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/docs/doxygen/other/oot_config.dox b/docs/doxygen/other/oot_config.dox new file mode 100644 index 0000000000..bb441c5060 --- /dev/null +++ b/docs/doxygen/other/oot_config.dox @@ -0,0 +1,78 @@ +/*! \page page_oot_config 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: + +\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. + +\section oot_config_path_page 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: + +\code + export PKG_CONFIG_PATH=$prefix/lib/pkgconfg:$PKG_CONFIG_PATH +\endcode + +3. Set the CMAKE_PREFIX_PATH environmental variable to $prefix. + +\code + export CMAKE_PREFIX_PATH=$prefix:$CMAKE_PREFIX_PATH +\endcode + + +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). + +*/ |