History

« Previous - Version 14/31 (diff) - Next » - Current version
Martin Braun, 02/15/2012 09:59 am

Contributing to GNU Radio -- FAQ

GNU Radio is an Open Source project, and as such contributions from the community are welcome. If you have some code or other things such as documentation you would like to share with the rest, please have a look at this FAQ before submitting.

How can I help?

The easiest way to help is to simply use GNU Radio. The more you use it, the more likely you will perhaps find a bug, or miss a particular feature. Tell us about it on the mailing list, or, even better, fix it yourself and submit the code. The most rewarding way to go is probably to actually write a radio system, e.g. a receiver for a digital standard.

If you want to get involved in the development process, here's some suggestions where to start:
  • Documentation
  • Missing test cases
  • Bug fixes

Look at the results posted by our Jenkins continuous integration service: http://gnuradio.org/jenkins/job/GNURadio-master. It tracks warnings, TODO's, FIXME's, and unit tests. Any warnings or FIXME fixes are useful as well as any more unit tests to exercise the validity of the signal processing or runtime code.

Development Style

When writing new code, we have a few general rules for where and how things go in. We follow that standard Git workflows concept in our Git branch structure. We have two main branches used in development, the 'master' and the 'next.' Here are a few rules to go by when working on new code or fixing old code in GNU Radio.

  • Make sure any changes in 'master' do not break the API (even if there is an error)
    • Additions to the API are fine
    • Deprecating code by outputting a message is done here
  • Removing code or changing API names or calling conventions MUST be done in 'next'
  • Work in 'master' for as much as possible unless you are going to change the API

Following these simple rules will help get your code merged in faster and with less hassle.

When working in code, there may be additions or things you might not know how to do just yet. It is appropriate in these instances to make a comment about it. The convention for this is to use the following keywords to indicate where you have left something for later:
  • Use TODO comments for low-priority fixes
  • Use FIXME comments for high-priority fixes
For all kinds of modifications and changes, try and make sure the following points are observed:
  • For patches, the diff contains the minimal but related incremental changes, for all the files needing modification to implement the change. In other words, the diff should take a working GNU Radio source tree and modify it to become a working GNU Radio source tree with the feature implemented.
  • Diffs are made from the GNU Radio tree root, and are based on an recent master branch.
    • use git format-patch to create your patches.
    • Minor bug fixes should be applied to the maint branch
    • Addon's and features should be applied to the master branch
    • Changes to the structure, API, or other surgery to the code should be applied to the next branch
  • After applying your changes or building your branch, the tests 'make check' and 'make distcheck' must both pass.
  • There should be no additional compiler warnings to what already occurs.
  • No gratuitous whitespace changes.

Quality Assurance (QA) Code

Every block should have a QA file to test the validity of the code. Most current blocks have QA code that tests that the code runs and produces repeatable, testable results on all platforms. If this code fails, it is an indication of a problem, error, or unexpected change in the code. It is an easy way to verify the validity of the code. This can be a difficult concept in some signal processing codes (such as a phase lock loop that has to settle), but the current QA tests that are there can offer guidance and hints as to how to test a new block.

Any block that is currently without a QA testing program should be fixed to have one.

Top-level Directory Structure

We split GNU Radio into different components, or top-level directories. These include gnuradio-core, gr-audio, gr-uhd, etc. They can each be configured into or out of the build system using the --enable-component and --disable-component, respectively. All components are enabled by default and will gracefully fail if the machine is not capable of building it due to a lack of one or more dependencies. If configure is told to enable the component explicitly, then a failure to meet the dependency will stop the configuration process.

All components will create a Python module under gnuradio such that they are imported using:
from gnuradio import component. Note: this is not currently done this way for all components, but will be made standard in GNU Radio 3.5. All new code should follow this procedure.

The directory structure for each top-level directory looks like the following. More information can be found in the gr-howto-write-a-block/README.hacking document.

  • lib: GNU Radio blocks C++ API (.cc), shared lib and headers (.h) and QA code
  • python: Pure Python (.py) and the init.py files for hierarchical blocks and Python-domain QA codes
  • swig: Swig interface (.i) files that generate Python (and Guile) API from C++ blocks
  • grc: GNU Radio Companion block wrappers (.xml)
  • apps: GRC applications, scripts, or other executables that are useful applications
    • these are installed installed into path ($prefix/bin)
  • examples: Example programs and code that are not full applications but are useful to show functionality.
    • these get installed into $prefix/share/gnuradio/examples
  • docs: Documentation code for this component

I've found a bug, but I don't have the skill/time/whatever to fix it... now what?

No problem. If it's really an unfixed bug, you're perhaps the first to stumble upon it. Write an email to the mailing list explaining what's wrong and, ideally, providing a test case so the developers can reproduce the error.

If it's a confirmed bug, you should add a ticket to the bug tracker (http://gnuradio.org/redmine/projects/gnuradio/issues). Remember to add your test case here.

How do I submit patches?

This depends on the size of the patch. If it is a small patch, e.g. a bug fix which only consists of a few lines, the best way is to create a diff and send a patch file to the mailing list. Please include a description of the bug and how your patch fixes this bug. Be sure to send the patch as a mime text attachment, or pasted directly into the mail.

For larger patches, it is probably better to upload a modified version of the git repository, e.g. to github.
If you want to extend GNU Radio and add new features, please read 'How can I add new features to GNU Radio?'.

For bug fixes, the least friction is caused if you branch of the 'maint' branch. Anything that goes into 'maint' is automatically rolled up-stream into 'master' and 'next'.

How can I add new features to GNU Radio?

First of all, you should ask yourself if your code really belongs into the GNU Radio core. If you are developing a GNU Radio module which can exist completely separate of the GNU Radio code, it might be worth uploading it to CGRAN, where you can maintain the code yourself and don't have to go through the process of re-submitting patches.

Of course some features (say, new modulators) belong into the core GNU Radio repository. In this case, sending a patch to the mailing list is a bit too bulky. Instead, upload your code to a world-readable git repository, and then send an email explaining what your code does to the mailing list, or directly to Tom Rondeau, the GNU Radio maintainer. This is explained greater detail here .

Before submitting, go through the following check list:
  • Does the code include documentation? GNU Radio uses Doxygen for automatic doc generation, so be aware of this when documenting classes.
  • Are there unit tests? Are they sensible unit tests, i.e. do they cover the most common errors?
  • Does the patch maintain compatibility with the existing code base?
  • Does the code follow the GNU Radio coding conventions?
  • Is the code based on the latest GNU Radio revision?
  • Is the code nicely portable?
  • Do you have a copyright assignment on file with the FSF?

If you're having any trouble with this, don't hesitate to ask on the mailing list.

Which kind of patches are accepted into GNU Radio?

There is no definitive answer to this. Bug fixes are of course always welcome.

Ultimately, the decision lies with the maintainers. If in doubt, consult the mailing list.

How long does it take for my patch to become part of GNU Radio?

Again, there is no definitive answer to this. It depends on many things: the complexity and size of the patch, the current situation of development and the relevance of the patch.

However, the following things are guaranteed to delay acceptance:
  • Lack of documentation and/or test cases
  • Not complying with the coding conventions
  • Non-portable code

What's this CGRAN?

The Comprehensive GNU Radio Archive Network (CGRAN) ``is a free open source repository for 3rd party GNU Radio applications that are not officially supported by the GNU Radio project''. In other words, it is a place for anybody to upload and publish extensions and modifications of and for GNU Radio.

If you are developing a GNU Radio project which works separately from the GNU Radio core, you might want to submit it to CGRAN rather than to the GNU Radio core. This way, you keep the write access to your published code and can maintain it independently from the core.

Which coding conventions apply?

All contributions should conform to the GNU Coding Standards as modified for C++ in README.hacking

Also, you should check out The GNU Radio Coding Style Guide.

How is the code documented?

GNU Radio uses "Doxygen:http://www.stack.nl/~dimitri/doxygen" to document the source code. Any new block should use Doxygen markup structure to add to the Doxygen manual. Also, we use a list of groups to categorize all of the blocks, so when a new block is created, add this block to one or more of the available groups, a list of which can be found in docs/doxygen/other/group_defs.dox. Below is an example of a marked-up header file.

/*! 
 * \brief A new block that does something.
 * \ingroup some_group
 * \ingroup another_group
 *
 * Detailed description of what this block does.
 */
class gr_new_block : public gr_block
{
private:
  friend gr_new_block_sptr
  gr_make_new_block();

  gr_new_block();

public:
  /*!
   * \brief A function that does something.
   * 
   * A detailed description of this function.
   * \param What input parameter \p p0 does.
   * \param What input parameter \p p1 does.
   * \return Describe what is returned.
   */
   int some_function(int p0, float p1);

   int work(int noutput_items,
        gr_vector_const_void_star &input_items,
        gr_vector_void_star &output_items);
};

Starting in GNU Radio 3.5, we have been moving to new top level blocks, like gr-vocoder, gr-audio, gr-digital, etc. Each of these is getting its own group along with any specific group the block should be included in. These groups each have their own page to describe the group as a main description of the blocks and how to use the package. These pages are all linked from the Doxygen manual's front page, which is found in docs/doxygen/other/main_page.dox.

The top level blocks are all described inside that blocks doc directory in a .dox files named or the component. For example, in the component gr-digital, the manual page describing this component is in gr-digital/doc/digital.dox. This page should provide any detail that can help users add and use these packages and their blocks. As these components are developed, used, and added to, any more details that can go into this Doxygen page should be added for the benefit of anyone else.

The component's doc directory will also contain a README.package that gives a brief description of the package. This file should contain the most basic necessary information and point to the Doxygen files for more detail.

Doxygen Markup for Formulas

When inserting formulas into the header to be part of the documentation, we want to have the best representation possible, which means making Latex style formulas. This is done in Doxygen using the "\f{" to begin and "\f}" to end the formula section. However, these do not properly show up in the XML documents used in the Python help files. So we have to make the formula twice, once formatted for the HTML manual and another for the XML. It will look like this:

This is some text in the header...
\f{html}{
enter Latex formula here -> will only show up in the HTML document.
}

\xmlonly
Same Latex formula, but this will not be processed; will only be the raw Latex formula.
\endxmlonly

And here's some following text to the formulas.

Note that the spacing between sections is important to get the best output format. Furthermore, there are certain Doxygen markups that will cause a problem in the XML representation, like use the of \frac in Latex to create a fraction will not parse properly. There is likely a better way to handle this (PLEASE UPDATE IF YOU KNOW IT), but for now, we just add a space between them as "\ f".

What's this Copyright Assignment?

Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the FSF. A description of the process is available here. Basically, this guarantees the FSF (who is copyright holder of GNU Radio) does not run into any legal trouble somewhere down the road.

This boils down to the following instructions:

Who maintains GNU Radio?

GNU Radio is currently maintained by:

All major patches and changes go through him.

GNU Radio was founded and initially maintained by: