GRC C++ Generation

Starting from GNU Radio 3.8, GRC allows you to generate C++ code (not just Python) from your flowgraph. This feature was a SOCIS (ESA Summer of Code in Space) project in 2017. The C++ generation mode is significantly less stable and feature-rich than the default Python mode, since Python is a far more flexible language (and since GRC was created to generate Python code). About 50% of the in-tree blocks support C++ generation. The C++ generation templates have to be written on a per-block basis, which is a considerable amount of work. This also means that it is a considerable amount of work to keep the C++ templates updated, which is why some blocks' templates may be outdated and produce errors. The good news is that these errors often have trivial fixes.

GRC generates C++ code by creating a new directory with three files:

• top_block.cpp
• top_block.hpp
• CMakeLists.txt

All of these files are generated from templates, and changes in your flowgraph will be reflected in them. Additionally, GRC creates a build directory which you can call CMake and Make from. Pressing the execute button in GRC will generate, compile and run your flowgraph. However, it is often convenient to compile and run your flowgraph in a separate terminal, in case you need to examine error messages or make some manual adjustments to the generated files.

Enabling C++ Output

C++ output for a flowgraph can be enabled by changing the Output Language parameter of the Options block from Python to C++ and pressing OK.

That's all, given that the blocks in your flowgraph support C++ output. If they don't, please see the next section about adding C++ templates. Note that two new parameters are visible, namely Generate CMakeLists.txt and CMake Options. The first one is useful if you've written your own CMakeLists.txt (and don't want GRC to overwrite it), while the second parameter is used to pass command line arguments to CMake. For example, if you want to compile your app with the debug flag set, write "-DCMAKE_BUILD_TYPE=Debug". This ends up as the following line in the resulting CMakeLists.txt:

set(CMAKE_BUILD_TYPE Debug)

Once you've generated your C++ flowgraph, you can navigate to the generated files, enter the build directory, run cmake .. and then make. If all goes well, your flowgraph will show up in executable form in your build directory.

Adding C++ Templates to a Block

Note: C++ generation requires that the block's implementation is written in C++, which most blocks are. However, some blocks are purely written in Python, and these can't produce C++ code. You might want to use a different block.

Some blocks don't have C++ templates yet. However, adding C++ templates is often quite simple. This guide builds on the C++ OOT guide. The steps listed here will fall between Modifying the YAML file and Compiling_and_Installing_the_Block.

In order to enable C++ generation for our multDivSelect block, we need to add some additional lines to the YAML file (comments have been removed for brevity):

id: customModule_multDivSelect
label: multDivSelect
category: '[customModule]'
flags: [cpp]

templates:
  imports: from gnuradio import customModule
  make: customModule.multDivSelect(${selector})

cpp_templates:
  includes: ['#include <gnuradio/customModule/multDivSelect.h>']
  declarations: 'customModule::multDivSelect::sptr ${id};'
  make: 'this->${id} = customModule::multDivSelect::make(${selector});'
  link: ['gnuradio::gnuradio-customModule']
  packages: ['gnuradio-customModule']
  translations:
    'True': 'true'
    'False': 'false'

parameters:
- id: selector
  label: Selector, Multiply (true) or Divide (false)
  dtype: bool
  default: true

inputs:
- label: in0
  domain: stream
  dtype: complex
- label: in1
  domain: stream
  dtype: complex
outputs:
- label: out0
  domain: stream
  dtype: complex

file_format: 1

The includes, declarations and make fields should intuitively map to the Python template fields (although declaration is not required in Python).

The link and packages fields drive the CMakeLists.txt generation for any flowgraph that uses this block. Specifically, the elements of the link field will be added to the target_link_libraries call for the target. This should be a (CMake) namespace-qualified target. Generally OOT blocks are in the gnuradio:: namespace. Failure to do so can cause link errors in some cases.

In order to make sure these targets are known, you should specify the CMake package name(s) in which they reside. Specifically, each element of the packages list will be added to the CMakeLists.txt file as find_package(gnuradio-customModule). Note that while the other portions of this template affect the code generated to instantiate this block, these fields influence the infrastructure to link against this block.

The translations field might not be necessary for your block, it is used here to convert boolean literals from Python syntax to C++ syntax.

Next, you can follow the C++ OOT guide (e.g. cmake, make, make install) to compile the module. Once this has been done, you can load the updated block information into GRC by pressing the Reload Blocks button or restarting GRC.

Troubleshooting

Generation Issues

Generate Error: (NameError("(...) is not defined")

This error is actually not C++-specific. It appears if you use a variable that is not defined, this is usually caused by typos. In the context of the multDivSelect block, the following line would cause a NameError:

cpp_templates:
(...)
  make: 'this->${id} = customModule::multDivSelect::make(${selllector});'
(...)

This block does not support C++ output

The block does not have the cpp flag set, which can be found near the start of the YAML file (line 4 in the example above). This usually means that the block does not have C++ templates either. You can try writing the templates yourself, or create an issue on Github and ask for someone else to do it.

Compilation Issues

‘True’ was not declared in this scope

Consolidate compiler generated dependencies of target cpptest
[ 50%] Building CXX object CMakeFiles/cpptest.dir/cpptest.cpp.o
/home/hkon/oot/gr-customModule/build/cpptest/cpptest.cpp: In constructor ‘cpptest::cpptest()’:
/home/hkon/oot/gr-customModule/build/cpptest/cpptest.cpp:37:80: error: ‘True’ was not declared in this scope
   37 |         this->customModule_multDivSelect_0 = customModule::multDivSelect::make(True);
      |                                                                                ^~~~
make[2]: *** [CMakeFiles/cpptest.dir/build.make:90: CMakeFiles/cpptest.dir/cpptest.cpp.o] Error 1

In C++, the boolean type is either true or false (lowercase), while the corresponding Python type is True or False. Try adding a translations field to the cpp_templates:

cpp_templates:
  (...)
  translations:
    'True': 'true'
    'False': 'false'

GRC will do a search and replace operation on your block's generated code, replacing all instances of True and False with true and false, respectively.

undefined reference to (...)

There is something missing in the target_link_libraries() call in your flowgraph's CMakeLists.txt, which means that there is a problem with your block YAML's link field. Try gnuradio::gnuradio-qtgui (in-tree blocks) or gnuradio-customModule (OOT blocks). Replace qtgui or customModule with the actual module's name.