ModtoolArchitecture

 THIS PORTION HAS NOT BEEN MERGED WITH THE PYTHON3 BRANCH YET.

This article explains the current architecture of gr_modtool in the python3 branch.

For this tutorial, one must have the dependencies,   installed.

= What is gr_modtool? =

While developing an Out Of Tree module, there's a lot of boring, monotonous work involved: boilerplate code, makefile editing, etc. gr_modtool is a script which aims to help with all these things by automatically editing makefiles, using templates, and doing as much work as possible for the developer such that one can jump straight into the DSP coding.

Note that gr_modtool makes a lot of assumptions on how the code looks like. The more the module is custom and has specific changes, the less useful gr_modtool will be, but it is probably the best place to start with any new module or block. One can go through the block coding guide for getting an insight of coding the block.

gr_modtool is available in the GNU Radio source tree and is installed by default.

= Plug-in Architecture =

gr-modtool uses the Click Python package for its command line interface. Some of the advantages of using Click for CLI are:-
 * Click is fully nestable and composable.
 * Click supports prompting of custom values.
 * Click works the same in Python 2 as well as in Pythonn3.
 * Click comes with useful helpers like ANSI colors.
 * Click is very simple to code and visualize.

Click is based on decorators and therefore enables simple syntax for calling high order internal functions. gr_modtool uses the class  as the parent class for its base module's   class. The parent class functions  and   have been overridden in the child class to enable a plug-in architecture for gr_modtool.

The function  lists all the commands for the gr_modtool. It first searches for the in-tree commands, the commands in its own directory, and then searches for other registered  through external plug-ins or otherwise (in case of the modtool, they are only registered through external plug-ins). The function  returns a command object by the user input command. It first tries to import the module for the command by searching the in-tree modules, then checks for the registration of command via other sources. If the module is found in-tree, then the  function of the respective module is called.

CLI functions in Modtool
Initially all commands with  in the command-line interface entered by the user pass through the   function of. If no further command is provided in the command-line, the help page is displayed with all the in-tree plug-ins commands as well as the commands from the external plug-ins, if any.

If a command (after gr_modtool) is provided in the interface which has a corresponding module, where the command is the user input command, the   function of the corresponding module is invoked with the context of the group instance in the base module.

The function is decorated by the decorator,, which adds the functionalities of the class   and automatically attaches the decorated   and   to it. The user input values of all these parameters are then passed to the  function of the respective module defined in its core class.

Note: The basic difference between arguments and options is that arguments are positional and mandatory by default unlike options, although arguments can also be made optional as in the case with the modtool scripts. Moreover,  of the argument is not generated by click and it has to be done manually.

Key Notes
The help page of gr_modtool looks like:- % gr_modtool Usage: gr_modtool [OPTIONS] COMMAND [ARGS]...
 * A decorator function  is present in the base module to remove the redundancy of adding the same options in every module. These options are not provided as the options to the base command group intentionally because they actually make sense with the command itself, otherwise the command   will look like   which is not user-friendly. Therefore, these parameters will show up in the help page of the respective command rather than the command group.
 * A decorator  is present in the base module which adds an argument (non-mandatory) block_name to the particular command that uses it.
 * The help page for a particular command can be shown with  in the CLI. For eg:-.
 * For commands, a short help snippet is generated. By default, it is the first sentence of the help message of the command, unless it is too long. This can also be overridden by  provided with command. For example,   shows the help of the command   generated in the help page (  or simply  ) as the description variable of the class  . The main help-text ,when you request the command's help page with commands like , is the document string of the function attached to the decorator.
 * For options, the help documentation can be added by  parameter in the decorator  . For example,.

A tool for editing GNU Radio out-of-tree modules.

Options: --help Show this message and exit.

Commands: add     Adds a block to the out-of-tree module. disable Disable selected block in module. info    Return information about a given module makexml Generate XML files for GRC block bindings. newmod  Create new empty module, use add to add blocks. rename  Rename a block inside a module. rm      Remove a block from a module.

Manipulate with GNU Radio modules source code tree. Call it without options to run specified command interactively

The help page of the command add of gr_modtool looks like:- % gr_modtool add --help Usage: gr_modtool add [OPTIONS] BLOCK_NAME

Adds a block to the out-of-tree module.

Options: -t, --block-type [sink|source|sync|decimator|interpolator|general|tagged_stream|hier|noblock] One of sink, source, sync, decimator, interpolator, general, tagged_stream, hier, noblock. --license-file TEXT            File containing the license header for every source code file. --copyright TEXT               Name of the copyright holder (you or your                                  company) MUST be a quoted string. --argument-list TEXT           The argument list for the constructor and make functions. --add-python-qa                If given, Python QA code is automatically added if possible. --add-cpp-qa                   If given, C++ QA code is automatically added if possible. --skip-cmakefiles              If given, only source files are written, but CMakeLists.txt files are left unchanged. -l, --lang [cpp|c++|python]    Programming Language -d, --directory TEXT           Base directory of the module. Defaults to                                 the cwd. --skip-lib                     Don't do anything in the lib/ subdirectory. --skip-swig                    Don't do anything in the swig/ subdirectory. --skip-python                  Don't do anything in the python/ subdirectory. --skip-grc                     Don't do anything in the grc/ subdirectory. --scm-mode [yes|no|auto]       Use source control management [ yes | no | auto ]). -y, --yes                       Answer all questions with 'yes'. This can                                  overwrite and delete your files, so be                                  careful.  --help                          Show this message and exit.

Note:- For more information regarding help-texts : click-documentation.

Adding a module in-tree
Here is an example of coding a click command:- @click.command('newmod', short_help=ModToolNewModule.description) @click.option('--srcdir',             help="Source directory for the module template.") @ModTool.common_params @click.argument('module_name', metavar="MODULE-NAME", nargs=1, required=False) def cli(**kwargs): """   \b    Create a new out-of-tree module

The argument MODULE-NAME overrides the current module's name (normally is autodetected). """   args = DictToObject(kwargs)    try:        ModToolNewModule.run(args)    except ModToolException as err:        print(err, file=sys.stderr)        exit(1) Here, the available options with the command are   and all the options that the function of the class ,  , adds to it.

So, to add a module in-tree, all that one has to do is to create module as  with a function   in the modtool directory, add options and arguments to it with   and   decorators and specify the functional details with the obtained value of parameters. Note: Instead of, one can specify the particular options.

= External Plug-ins =

supports the addition of external plug-ins, if required by the user. To achieve this functionality, it uses  to load an external plug-in and a python package   to register commands to the base group and show   if the plug-in is not be loaded properly.

Adding a plug-in
To add an external plug-in to the modtool, all that one has to do is to create a package directory with a file  and specify the   as   through the functional definition of our choice. For example:- If package directory  looks like ext_plug ....setup.py ....core.py the  should look like:- from setuptools import setup

setup(   py_modules=['core'],    entry_points=        [gnuradio.modtool.plugins]        cmd=core:cmd     ) Here  is the module name and   is the function inside   that is executed. Note: Any other specifications to  can be added like name, version, etc.

Writing a plug-in
Writing an external plug-in is quite simple. All that one has to do is create a function with the name specified in the  and decorate it with , if just an external command is to be added, or   , if a command group is to be added. For eg:- For the previous package,  can be like import click

@click.command def cmd: """   The external command functionality    """ pass Now, one just needs to install this package by running  and the external plugin is ready to use. Now, on running, we get % gr_modtool --help Usage: gr_modtool [OPTIONS] COMMAND [ARGS]...

A tool for editing GNU Radio out-of-tree modules.

Options: --help Show this message and exit.

Commands: add     Adds a block to the out-of-tree module. cmd     The external command functionality disable Disable selected block in module. info    Return information about a given module makexml Generate XML files for GRC block bindings. newmod  Create new empty module, use add to add blocks. rename  Rename a block inside a module. rm      Remove a block from a module.

Manipulate with GNU Radio modules source code tree. Call it without options to run specified command interactively If the plug-in is not loaded due to reasons like an incorrect entry_point setup, the help page will duly indicate that. For example:- If the  file for the above-mentioned package looks like from setuptools import setup

setup(   py_modules=['core'],    entry_points=        [gnuradio.modtool.plugins]        cmd=core:cmdddd     ) the plug-in will not load to incorrect functional definition in the. Now, on running, we get % gr_modtool --help Usage: gr_modtool [OPTIONS] COMMAND [ARGS]...

A tool for editing GNU Radio out-of-tree modules.

Options: --help Show this message and exit.

Commands: add     Adds a block to the out-of-tree module. cmd     † Warning: could not load plugin. See `gr_modtool cmd --help`. disable Disable selected block in module. info    Return information about a given module makexml Generate XML files for GRC block bindings. newmod  Create new empty module, use add to add blocks. rename  Rename a block inside a module. rm      Remove a block from a module.

Manipulate with GNU Radio modules source code tree. Call it without options to run specified command interactively So,  makes even the adding an external plug-in highly interactive.

Information regarding creating an out of tree module and in-tree commands is available here.