GNU Radio 3.8 OOT Module Porting Guide

Brace yourself! 3.8 is here. This document, hopefully, eases the transition of your OOT to our new major version. Furthermore, we think it is a good occasion to establish some standards on how an OOT module should be structured and maintained. More uniformity is an advantage for the users, for you as a OOT maintainer, for the GR devs, since it will be easier to integrate it into PyBOMBS, and for the packagers to ship your OOT module.

Development Model
GNU Radio recently changed the development model. The longstanding next branch was finally merged in to master. From now on, there will only be a maint-X.Y and a master branch. Releasing 3.8 basically means master will be spin off maint-3.8 with the 3.8.0.0 release commit. After that API-breaking changes for 3.9 will end up in master and 3.8 will be maintained in maint-3.8.

We suggest, you adapt a similar model in your OOT. That means your maint-3.8 branch is compatible with GNU Radio maint-3.8 and your master branch is compatible GNU Radio master. Trying to maintain a single branch that works with all future, present, and past versions of GNU Radio versions is mess and you’d have to differentiate between too many cases (API changes, XML vs YAML GRC bindings, Python 2 vs 3, QT4 vs QT5, log4cpp support or not, CPPUnit or Boost unit tests, etc.).

Starting your maint-3.7 branch and tagging the current state as the last one that’s compatible with GR 3.7 could be done with:

Install GNU Radio 3.8
Start by installing the most recent version of GNU Radio. At the moment, there are no pre-built packages, so checkout the most recent master branch and compile from source. This also updates gr_modtool, which we will use in the following.

CMake Updates
GNU Radio 3.8 comes with changes to the CMake build system. Going forward CMake syntax in GNU Radio core adheres to "Modern CMake". This means no functions setting global variables like  and   will be used. Instead only functions which operate on targets and are prefixed with  are used. A reference on "Modern CMake" can be found here.

Summary

 * is only required for dependencies you directly depend on. E.g. Boost, log4cpp will be handled by the GNU Radio Cmake configuration and linker flags and defines are provided transitively.
 * GNU Radio CMake adheres to all CMake policy changes up to CMake 3.11. Remove  function calls which set CMake policy to old.
 * variables won't pollute your environment, only the minimum necessary variables are defined by the GNU Radio CMake configuration
 * CppUnit in GNU Radio core has been removed and replaced by Boost UTF, same can be done for your OOT. If you like you can still keep CppUnit though.
 * Functions setting global include paths and link_directories should be removed
 * Custom CMake modules previously located in cmake/Modules in your tree, especially CMakeParseArgumentsCopy.cmake, FindCppUnit.cmake FindGnuradioRuntime.cmake GrPlatform.cmake GrTest.cmake
 * can use  instead of
 * Instead of  a special cased target_include_directories can specify include directories for build time and for install time

The easiest way to update CMake for your OOT might be to use gr_modtool and generate a module with the same name and then copy your source files over. If you have multiple GR versions installed, make sure that gr_modtool uses the correct module template, which is defined in the [modtool] section in ~/.gnuradio/config.conf.

Look at Examples
If you have doubts about any of the following steps, you might want to have a look at OOTs that were already ported. We know of: https://github.com/ghostop14/gr-grnet (master branch)

Updating, for example, gr-foo could be done with

To see how OOT blocks are handled, you can create a C++ and a Python block to see examples of how they are integrated into build system.

Then use a diff tool like meld to compare the differences and apply changes as needed.

CMake Modules
One thing you might notice is that there are now less FindXXX.cmake modules needed in your OOT (under cmake/Modules). If your module did not require any custom CMake changes (which is likely), you can just go ahead and delete these modules. They now installed as part of GNU Radio and are available in your CMAKE_MODULE_PATH once GNU Radio was loaded through find_package(Gnuradio [...]).

Note: In the unlikely case that you module requires custom cmake modules, there’s one tricky bit: At the top of your main CMakeLists.txt file the local cmake modules are put at the beginning of the search path and, therefore, take precedence over the ones installed on your system. However, once GNU Radio is loaded, it will put its cmake path at the front, potentially shadowing local modules. If that’s a problem, put your local path again to the front after GNU Radio is loaded like so:

GNU Radio Components
GNU Radio now uses CMake components. So if your OOT depends on GNU Radio modules other than runtime and pmt, you have to import these components through the find_package call. For example, change:

to:

Note: Currently the build system doesn’t resolve internal dependent components automatically. The filter component, for example, depends on fft, so it had to be added manually to the list of components above.

Python Blocks
In python/__init__.py each block must be changed to relative import by putting a period before the block name

Versioning
Version your OOT similar to GR?

API Changes
At this point, you should be able to recompile the module. Here you can test if you run into any issues with C++ API changes.

XML to YAML Conversion The GNU Radio Companion (GRC) bindings are no longer defined in XML but in YAML. To ease the transition, GNU Radio comes with a converter that should do 95% of the work. Make sure your grc bindings are in the grc folder and use the _ .xml naming scheme. Then, from the root directory of your module, do:

If there are any problems reported you’ll have to fix the by hand.

Todo: link to examples and documentation

Don’t forget to update the file names in the grc/CMakeLists.txt file to make sure that the YAML files are installed.

WX is Gone
GNU Radio 3.8 drops support for WX GUI widgets in favor of QT. If you are using WX widgets in your flow graph, you’d have to replace them with the corresponding QT widgets. For most flow graphs that should be a straight forward drop in replacement.

Update PyBombs Recipe
If your OOT module is listed in a receipt file for PyBombs, please update, if needed, your Manifest.md file and the receipt.

Shit’s not Working?
If you have any issues porting your OOT, please join our Slack channel or write to the GNU Radio mailing list. We are happy to help and to improve this guide. Notes