# Copyright (C) 2017 Free Software Foundation, Inc.
#
# Permission is granted to copy, distribute and/or modify this document
# under the terms of the GNU Free Documentation License, Version 1.3
# or any later version published by the Free Software Foundation;
# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
# A copy of the license is included in the section entitled "GNU
# Free Documentation License".

/*! \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).

*/
