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