https://wiki.gnuradio.org/api.php?action=feedcontributions&user=Bastibl&feedformat=atomGNU Radio - User contributions [en]2024-03-29T13:34:38ZUser contributionsMediaWiki 1.39.5https://wiki.gnuradio.org/index.php?title=UbuntuVM&diff=7590UbuntuVM2020-10-09T16:13:39Z<p>Bastibl: </p>
<hr />
<div>An Ubuntu 20.04 virtual machine image with GNU Radio 3.8.2.0, Fosphor, GQRX, and several other useful pieces of software.<br />
<br />
The most recent image is instant-gnuradio-3.8.2.0-1.0.0.ova and is a 3.4 GB download and 11 GB once installed and launched.<br />
<br />
There is a torrent available: https://gnuradio.inpha.se/instant-gnuradio-3.8.2.0-1.0.0.ova.torrent<br />
<br />
If you can't use the torrent (which would be load balancing, including using GNU Radio's server), you can also download from https://www.gnuradio.org/releases/ , but that might be slower.<br />
<br />
The VM is built with [https://github.com/bastibl/instant-gnuradio Instant GNU Radio]. If there are any issues, please report them [https://github.com/bastibl/instant-gnuradio/issues here]. You can also use the VM as a base for your own builds. See the VM, created for the GRCon workshop on satellite communications [https://github.com/bastibl/instant-gnuradio/commit/a0ffd8af73a0b2ed3db3262699c08cfb015147b4 as an example].<br />
<br />
<br />
== Using VirtualBox ==<br />
<br />
<br />
https://www.virtualbox.org/wiki/Downloads<br />
<br />
=== Installing the VirtualBox Extension Pack ===<br />
<br />
This is needed for USB 3 and is a requirement for running the VM, even if you are not actually going to use USB 3.<br />
<br />
Assuming your host is running Ubuntu,<br />
<br />
sudo apt install virtualbox-ext-pack<br />
<br />
Or available via https://www.virtualbox.org/wiki/Downloads. If downloading manually, make sure the extension pack version number matches the VirtualBox version number. Distributions do not always use the latest version. Installation is under File/Preferences/Extensions.<br />
<br />
=== Importing the Image ===<br />
<br />
OVA files are loaded into VirtualBox under File/Import Appliance. Use default answers to any dialogs. Once the OVA is loaded it will show up in the list of available images in VirtualBox.<br />
<br />
=== Running the Image ===<br />
<br />
Select the image and hit the "Start" button. Log in when prompted. The screen will start off at low resolution. Select a more useful resolution under View/Virtual Screen 1. For High DPI monitors, you may want to select a scaling factor under the same menu.<br />
<br />
If the image fails to boot, and the error dialog "Details" mention xHCI, then the extension pack was most likely not installed correctly.<br />
<br />
The VM uses a persistent disk image, (1) your preferences and work will be saved, and (2) it is best to shut down the VM as if it were a real computer to avoid loss of work.<br />
<br />
== GNU Radio Companion ==<br />
<br />
The first icon in the app menu (the GNU Radio logo) will start GRC.<br />
<br />
== USB Devices ==<br />
<br />
=== Passing Through USB Devices ===<br />
<br />
Host USB devices (e.g., a RTL dongle, USRP B2xx) can be taken from the host and given to the VM. Select any devices you would like to use in the VM under Devices/USB.<br />
<br />
=== Testing With a RTL Dongle ===<br />
<br />
Plug a RTL dongle into the host. Select USB forwarding for "Realtek RTL ..." under Devices/USB.<br />
<br />
Open a terminal (Terminator is the icon with 4 red boxes). Run<br />
<br />
dmesg<br />
<br />
and make sure that the log shows the Realtek device being discovered. Now run<br />
<br />
rtl_test<br />
<br />
which should print out status, and then appear to hang. CTRL-C to stop.<br />
<br />
== Tools ==<br />
<br />
=== GQRX ===<br />
<br />
The fastest way to see something interesting using a real SDR device is to run GQRX (icon that looks like a pulse). Select the RTL device from the initial dialog, or from I/O devices (second icon on the menu bar). GQRX remembers the last device and settings used. If the available devices have changed (or even appear that way in the VM), it may not start up cleanly. In this case, try it a couple of times and you should be able to select the device/setting you want.<br />
<br />
More information on GQRX is available here: https://gqrx.dk/<br />
<br />
=== Inspectrum ===<br />
<br />
Inspectrum is an easy-to-use FFT viewer for multiple file formats (determined by the file suffix). See: https://github.com/miek/inspectrum.<br />
<br />
=== URH ===<br />
<br />
Universal Radio Hacker is an end-to-end RF reverse engineering tool. It can capture, demodulate, analyze and generate bursts representing digital communication. There is a bit of a learning curve due to the amount of ground it covers, but it's worth the effort. See: https://github.com/jopohl/urh.</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=GSoCIdeas&diff=6682GSoCIdeas2020-01-30T16:44:23Z<p>Bastibl: /* Android */</p>
<hr />
<div>== Summer of Code 2020: Project ideas list ==<br />
<br />
This is the list of project ideas for the summer of code 2020 within GNU Radio.<br /><br />
Remember that these are '''ideas''' and are merely meant as an inspiration for you to write your own proposal.<br />
<br />
Students who do not find a fit among these projects are encouraged to engage with us and suggest new ones. The [[MailingLists|GNU Radio discussion mailing list]] is the best place to contact all of us. Please do not contact us off-list for the sake of discussing the summer of code, unless you're contacting a mentor listed here to get feedback on a proposal.<br />
<br />
Reviewing the [https://developers.google.com/open-source/gsoc/faq Google GSoC FAQ] page for a broader understanding of project, mentor, and student responsibilities is recommended.<br />
<br />
If you need a USRP or other radio hardware to complete the project, we will be able to arrange something.<br />
<br />
Please add ideas to this list (you may cannibalize old ideas, of course!).<br />
<br />
Guidelines for good projects (when suggesting projects, please consider these):<br />
<br />
* Clearly defined scope, with a main target that can be done in 3 months<br />
* Clear benefits for the GNU Radio project<br />
* Not specific to a certain hardware. No specific embedded devices, either, please.<br />
* Both OOTs and in-tree improvements are welcome<br />
<br />
<br />
<br />
=== GRC: Build-in sub flowgraphs ===<br />
<br />
GNU Radio has the hierarchical blocks to build reuseable sub flowgraphs. These hier_blocks can be designed in GRC, however, they have to be compiled to code and GRC bindings, before they can be used in other GRC files. While this is great for reuseablity across flowgraphs, it is quite cumbersome when the main use is to structure a single (larger) flowgraph. The goal of this project is to ease this use-case by embedding sub flowgraphs directly in the main GRC file. Instead of creating bindings and code and then parsing them back again, this process shall be done in-place to allow quickly editing sub flowgraphs on-the-fly. <br />
<br />
'''Prerequisites'''<br />
<br />
* GRC is written in Python which is (almost) all you need to know for this project.<br />
<br />
'''Outcome'''<br />
<br />
* A vastly improved workflow for structuring flowgraphs<br />
<br />
'''Mentor(s)'''<br />
<br />
* Sebastian Koslowski<br />
<br />
<br />
<br />
=== Qt5 GUI Integrations ===<br />
<br />
Idea: Wrap the Qt GUI sinks to appear in QtCreator, including the GUI aspects of their parameterization<br />
<br />
'''Prerequisites'''<br />
<br />
* C++, Python proficiency<br />
* Qt experienced<br />
<br />
'''Outcome'''<br />
<br />
* Qt GUI Sinks usable as widgets in QtCreator (not necessarily already showing an "empty" GUI, just placeholders)<br />
* Possible to import generate Qt GUI description file (UIC) into GRC<br />
* Interface to map placeholders from GUI design to Qt GUI sinks in Flow graph<br />
* Integration of that into GRC-generated Python code<br />
<br />
'''Mentor(s)'''<br />
<br />
* Marcus Müller & Sebastian "GRC-Man" Koslowski<br />
<br />
<br />
<br />
=== GRC: View-Only Mode (Secure) ===<br />
<br />
When a flowgraph from an untrusted source is opened if GRC, arbitrary Python code can be executed. This poses a potential security risk. Storing the all evaluated values of all parameters within a flow graph (.grc) file would allow us to open such flow graphs without compromising security. No code would be have to executed to draw the flow graph and block parameters can be viewed safely. Only if the flow graph is modified the user would have to choose to trust the flow graph thus enabling normal eval operations.<br />
<br />
'''Prerequisites'''<br />
<br />
* GRC is implemented using Python. So, Python should be known pretty well.<br />
<br />
'''Outcome'''<br />
<br />
* Safely view other people's flowgraphs without putting your PC at risk.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Sebastian Koslowski<br />
<br />
<br />
<br />
=== Extending and Updating gr-radar ===<br />
<br />
gr-radar (https://github.com/kit-cel/gr-radar/) was a great and successful GSoC project that provided a few methods of radar in GNU Radio. This module is heavily used by academics, researchers, cybersecurity folks, and hobbyists. This project would work to improve upon the concepts already in there as well as add more radar techniques.<br />
<br />
There are uncountable methods and techniques that could be added to this project, such as:<br />
<br />
* SAR / InSAR methods<br />
* Better passive radar support<br />
* Speed camera applications<br />
* Multi-antenna radar techniques<br />
<br />
'''Prerequisites'''<br />
<br />
* Signal processing and some radar basics are required.<br />
* Code is written in C++ with some Python on the side, so the student must be able to handle these languages at the least.<br />
<br />
'''Outcome'''<br />
<br />
* Based on the student's interest, a subset of the radar techniques listed above (or others) are chosen as milestones for this project. <br />
* All code must be merged back into gr-radar by the end of the summer.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Stefan Wunsch, Martin Braun<br />
<br />
<br />
<br />
=== QT Widgets Improvements ===<br />
<br />
The gr-qtgui in-tree component provides some QT widgets for signal visualization. This component needs some improvement to become more useful.<br /><br />
This project is cleanly divided into several sub-projects:<br />
<br />
* Add new widgets<br />
** Compass display (e.g. for direction-finding applications)<br />
** MPEG display (e.g. for video demod output)<br />
** Matrix sink (e.g. for radar Doppler/range plane visualization, or 2D-equalizer taps visualization)<br />
<br />
* Improve current widgets<br />
** Better code structure to make the current widgets more manageable, extensible and remove code duplication between widgets<br />
** More Control Panels on other widgets (follow lead on the frequency sink)<br />
** Improve UI, make more intuitive, more power to mouse users<br />
** Set trigger point with mouse<br />
<br />
* Integration / Support for QT Creator<br />
** QML design<br />
** Allow to build full GUI applications from, say, GRC<br />
<br />
'''Prerequisites'''<br />
<br />
* Familiarity with QT is essential.<br />
* Widgets are written in C+'', so some C''+ knowledge is also required.<br />
* Python skills are highly useful.<br />
<br />
'''Mentor(s)'''<br />
<br />
Tim O'Shea<br />
<br />
<br />
<br />
=== Standardized High Throughput FEC Codes ===<br />
<br />
Channel coding is essential to modern communications. Also, it is computationally very heavy. As of now, there exist implementations in GNU Radio which are too slow to be integrated into high throughput applications. GNU Radio would benefit from integration of standardized decoders for Turbo and LDPC codes. These codes would only support a certain subset of the whole code class but would be well optimized. <br />
<br />
'''Prerequisites'''<br />
<br />
* Understanding of ''gr-fec'' API. Knowledge on channel coding. Understanding of C++.<br />
<br />
'''Outcome'''<br />
<br />
* Standardized Codes, e.g. LTE Turbo Codes, 5G Polar Codes, 5G LDPC Codes, CCITT Convolutional Codes etc. are available in ''gr-fec''.<br />
* The preferred goal is to find a highly optimized implementation and integrate these into GNU Radio.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Johannes Demel<br />
<br />
<br />
<br />
=== Android ===<br />
<br />
One effort of the past years was to improve Android support for GNU Radio. We're getting to a point where we've figured out '''how''' to do it, so the next step is to make it more accessible to users and developers.<br />
<br />
The Android ecosystem is an entirely different beast from the rest of GNU Radio. To make writing Android/GR apps easy, the following needs to happen (and shall be part of this project):<br />
<br />
* Improve support for development environment<br />
** Create Dockers for easy start of development<br />
* Visualization classes for PSD, spectrogram and oscilloscope<br />
** Easy reuse in other apps, like the gr-qtgui widgets, but for Android SDKs<br />
* Interactivity concepts<br />
** Gestures and config for radio parameters (e.g., freq, gain, bandwidth)<br />
** Create an example FM receiver app that allows easy channel selection etc. through motions and gestures<br />
<br />
You can find a summary of the work that has been done on this (years ago) here: [[Android]]<br />
<br />
'''Prerequisites'''<br />
<br />
* Some Android experience<br />
* Enjoy writing GUI widgets<br />
* C++/Java experience<br />
<br />
'''Mentor(s)'''<br />
<br />
* Bastian Bloessl<br />
<br />
=== Runtime Benchmarks ===<br />
<br />
To facilitate development of a more modern GNU Radio runtime and scheduler, we need a tool to measure its performance (in terms of delay and throughput).<br />
This data is required to compare alternate approaches and to become aware of performance regressions early in the process.<br />
<br />
The goal of the project is to provide a tool to benchmark the GNU Radio runtime. Since we are interested in the performance on many platforms and architectures, it should provide an option to submit performance data to our sever, allowing us to crowdsource data. (Similar to our [http://stats.gnuradio.org/ online stats] for SIMD performance.)<br />
<br />
* Come up with interesting metrics and, if needed, implement blocks to extract them.<br />
* Come up with interesting flowgraph topologies that should be benchmarked.<br />
* Setup automated experiments that iterate over a given parameter space (repetitions, number of samples, size of the flowgraph).<br />
* Parse, evaluate, and visualize the data.<br />
* Add an option to upload the performance data to our web sever.<br />
<br />
'''Prerequisites'''<br />
<br />
* C++ programming<br />
* Data evaluation and visualization<br />
* Automation tools (like GNU Make to run benchmarks)<br />
<br />
'''Mentor(s)'''<br />
<br />
* Bastian Bloessl, Marcus Mueller<br />
<br />
=== Filter Design Tool Enhancements ===<br />
<br />
GNU Radio provides many tools to design and use digital filters. Using these tools requires both some expertise in these areas as well as an understanding of the performance on the given platform. One example is the selection between FIR (convolution-based) and FFT (fast convolution-based) filters for different resampling rates. Another example is doing stages of filter decomposition when doing large down-sampling. Included in this is the polyphase filterbanks, which again are provided as primitive blocks that need tweaking to work.<br />
<br />
This project is to improve our uses of these tools and blocks to make it more obvious to the users as well as automate some of the decisions for optimally using them. Some pointers:<br />
<br />
* When used in GRC, we want to save the results of the tool in a local file or for use in actual blocks.<br />
* It still currently runs on PyQWT, which is obsolete and needs to be updated to Qt5<br />
** See https://github.com/trondeau/gnuradio/tree/filter/design_tool_newgui<br />
* Add more support for filter design concepts and other filters.<br />
** Cascaded filters<br />
** Better support for creating PFB filters<br />
<br />
'''Prerequisites'''<br />
<br />
* Strong DSP background required.<br />
* Python and QT knowledge highly useful (at least one of those is a must).<br />
<br />
'''Mentor(s)'''<br />
<br />
* Marcus Leech<br />
<br />
<br />
<br />
=== Implement SigMF functionality for GNU Radio ===<br />
<br />
SigMF is the "Signal Metadata Format" that was defined during the 2017 DARPA Hackfest in Brussels. Its purpose is to annotate raw binary dumps of signals with metadata, thus giving meaning to a raw mass of samples.<br /><br />
SigMF is specified and has a minimal reference implementation here: https://github.com/gnuradio/sigmf<br />
<br />
GNU Radio needs its own implementation of SigMF that ties into the block structure. The following things need to be written:<br />
<br />
* Source and Sink blocks for SigMF (similar to the current metadata blocks)<br />
* Converters for files generated with the current metadata file formats<br />
* Static analysis tools using SigMF<br />
<br />
'''Prerequisites'''<br />
<br />
* Basic understanding of how to write GNU Radio blocks is required.<br />
* Also, the student needs to explain that she or he has understood the concepts of SigMF, although SigMF is a very simple, JSON-based file format.<br />
* Depending on the precise path that the student and the mentor define, experience in GUI development would also be useful.<br />
<br />
'''Outcome'''<br />
<br />
* The source and sink blocks are by the far the most important outcomes of this project. We estimate it would take about a third of the active coding time to implement those, and have them merged around the midterms.<br />
This leaves plenty of time for further development.<br />
* The next most important task are the converters, so existing metadata files will continue to be useful. After that, the student should define own tasks based on their interests. A very relevant problem is the ability to effectively visualize metadata in combination with signals.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Bastian Bloessl, Sebastian Müller<br />
<br />
<br />
<br />
=== Statistical Toolbox for GRC ===<br />
<br />
A statistical toolbox for GRC would enable GUI-based statistical analysis. Currently, such analysis can be done by writing an independent program (e.g., with SciPy), but there is no actual integration with GNU Radio. By developing the statistical toolbox, we provide blocks for probability distribution fitting, hypothesis testing, extracting statistical parameters for one-dimensional as well as multi-dimensional data. This would significantly expand GNU Radio users' ability to perform data-science analysis and modeling on signal data.<br />
<br />
'''Prerequisites'''<br />
<br />
* Understanding of existing GNU Radio tools (e.g., GRC), GNU Radio Out-of-Tree Modules, and statistics / data-science modeling.<br />
<br />
'''Outcome'''<br />
<br />
* An OOT module that provides statistical analysis capabilities for GNU Radio.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Ben Hilburn<br />
<br />
<br />
<br />
=== Digital Pre-Distortion ===<br />
<br />
Digital Pre-Distortion (DPD) is a technique allowing transmitters to compensate for non-linear responses in their hardware, most notably the power amplifier. This improves SNR and can allow more spectral and power efficient operation of a given set of hardware.<br />
<br />
DPD is widely used and is increasingly necessary as many multicarrier signals such as what are seen in DVB and LTE exhibit high peak to average power ratios (PAPRs). DPD implementations are not widely available in the open source community. This is a deficit that this project hopes to correct. Over the course of the project the student would implement standard DPD algorithms in to a GNU Radio out of tree module so that they can be available for use directly or as reference designs.<br />
<br />
'''Prerequisites'''<br />
<br />
* Workable C++ proficiency, basic knowledge of radio systems, ideally familiarity with GNU Radio and/or Digital Pre-Distortion<br />
<br />
'''Outcome'''<br />
<br />
* Implement standard memory-less and memory based DPD algorithms<br />
* Implement the training algorithms for such DPD application algorithms.<br />
* Implement a GUI tool or testbench for viewing the AM-AM and AM-PM responses of an amplifier<br />
<br />
'''Mentor(s)'''<br />
<br />
* Derek Kozel<br />
<br />
<br />
<br />
== Application process ==<br />
<br />
Students interested in participating, read the [[GSoCStudentInfo|student instructions]] and the [[GSoCManifest|rules of conduct]].<br />
* Please introduce yourself on the [https://lists.gnu.org/mailman/listinfo/discuss-gnuradio GNU Radio mailing list]<br />
* Fill in the formal application for GNU Radio<br />
* Pick some items from the list above or feel free to suggest another piece of work relevant to this theme. Give us a detailed, week-by-week plan for completing the task over the summer.</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=GSoCIdeas&diff=6679GSoCIdeas2020-01-30T16:05:21Z<p>Bastibl: /* Android */</p>
<hr />
<div>== Summer of Code 2020: Project ideas list ==<br />
<br />
This is the list of project ideas for the summer of code 2020 within GNU Radio.<br /><br />
Remember that these are '''ideas''' and are merely meant as an inspiration for you to write your own proposal.<br />
<br />
Students who do not find a fit among these projects are encouraged to engage with us and suggest new ones. The [[MailingLists|GNU Radio discussion mailing list]] is the best place to contact all of us. Please do not contact us off-list for the sake of discussing the summer of code, unless you're contacting a mentor listed here to get feedback on a proposal.<br />
<br />
Reviewing the [https://developers.google.com/open-source/gsoc/faq Google GSoC FAQ] page for a broader understanding of project, mentor, and student responsibilities is recommended.<br />
<br />
If you need a USRP or other radio hardware to complete the project, we will be able to arrange something.<br />
<br />
Please add ideas to this list (you may cannibalize old ideas, of course!).<br />
<br />
Guidelines for good projects (when suggesting projects, please consider these):<br />
<br />
* Clearly defined scope, with a main target that can be done in 3 months<br />
* Clear benefits for the GNU Radio project<br />
* Not specific to a certain hardware. No specific embedded devices, either, please.<br />
* Both OOTs and in-tree improvements are welcome<br />
<br />
<br />
<br />
=== GRC: Build-in sub flowgraphs ===<br />
<br />
GNU Radio has the hierarchical blocks to build reuseable sub flowgraphs. These hier_blocks can be designed in GRC, however, they have to be compiled to code and GRC bindings, before they can be used in other GRC files. While this is great for reuseablity across flowgraphs, it is quite cumbersome when the main use is to structure a single (larger) flowgraph. The goal of this project is to ease this use-case by embedding sub flowgraphs directly in the main GRC file. Instead of creating bindings and code and then parsing them back again, this process shall be done in-place to allow quickly editing sub flowgraphs on-the-fly. <br />
<br />
'''Prerequisites'''<br />
<br />
* GRC is written in Python which is (almost) all you need to know for this project.<br />
<br />
'''Outcome'''<br />
<br />
* A vastly improved workflow for structuring flowgraphs<br />
<br />
'''Mentor(s)'''<br />
<br />
* Sebastian Koslowski<br />
<br />
<br />
<br />
=== Qt5 GUI Integrations ===<br />
<br />
Idea: Wrap the Qt GUI sinks to appear in QtCreator, including the GUI aspects of their parameterization<br />
<br />
'''Prerequisites'''<br />
<br />
* C++, Python proficiency<br />
* Qt experienced<br />
<br />
'''Outcome'''<br />
<br />
* Qt GUI Sinks usable as widgets in QtCreator (not necessarily already showing an "empty" GUI, just placeholders)<br />
* Possible to import generate Qt GUI description file (UIC) into GRC<br />
* Interface to map placeholders from GUI design to Qt GUI sinks in Flow graph<br />
* Integration of that into GRC-generated Python code<br />
<br />
'''Mentor(s)'''<br />
<br />
* Marcus Müller & Sebastian "GRC-Man" Koslowski<br />
<br />
<br />
<br />
=== GRC: View-Only Mode (Secure) ===<br />
<br />
When a flowgraph from an untrusted source is opened if GRC, arbitrary Python code can be executed. This poses a potential security risk. Storing the all evaluated values of all parameters within a flow graph (.grc) file would allow us to open such flow graphs without compromising security. No code would be have to executed to draw the flow graph and block parameters can be viewed safely. Only if the flow graph is modified the user would have to choose to trust the flow graph thus enabling normal eval operations.<br />
<br />
'''Prerequisites'''<br />
<br />
* GRC is implemented using Python. So, Python should be known pretty well.<br />
<br />
'''Outcome'''<br />
<br />
* Safely view other people's flowgraphs without putting your PC at risk.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Sebastian Koslowski<br />
<br />
<br />
<br />
=== Extending and Updating gr-radar ===<br />
<br />
gr-radar (https://github.com/kit-cel/gr-radar/) was a great and successful GSoC project that provided a few methods of radar in GNU Radio. This module is heavily used by academics, researchers, cybersecurity folks, and hobbyists. This project would work to improve upon the concepts already in there as well as add more radar techniques.<br />
<br />
There are uncountable methods and techniques that could be added to this project, such as:<br />
<br />
* SAR / InSAR methods<br />
* Better passive radar support<br />
* Speed camera applications<br />
* Multi-antenna radar techniques<br />
<br />
'''Prerequisites'''<br />
<br />
* Signal processing and some radar basics are required.<br />
* Code is written in C++ with some Python on the side, so the student must be able to handle these languages at the least.<br />
<br />
'''Outcome'''<br />
<br />
* Based on the student's interest, a subset of the radar techniques listed above (or others) are chosen as milestones for this project. <br />
* All code must be merged back into gr-radar by the end of the summer.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Stefan Wunsch, Martin Braun<br />
<br />
<br />
<br />
=== QT Widgets Improvements ===<br />
<br />
The gr-qtgui in-tree component provides some QT widgets for signal visualization. This component needs some improvement to become more useful.<br /><br />
This project is cleanly divided into several sub-projects:<br />
<br />
* Add new widgets<br />
** Compass display (e.g. for direction-finding applications)<br />
** MPEG display (e.g. for video demod output)<br />
** Matrix sink (e.g. for radar Doppler/range plane visualization, or 2D-equalizer taps visualization)<br />
<br />
* Improve current widgets<br />
** Better code structure to make the current widgets more manageable, extensible and remove code duplication between widgets<br />
** More Control Panels on other widgets (follow lead on the frequency sink)<br />
** Improve UI, make more intuitive, more power to mouse users<br />
** Set trigger point with mouse<br />
<br />
* Integration / Support for QT Creator<br />
** QML design<br />
** Allow to build full GUI applications from, say, GRC<br />
<br />
'''Prerequisites'''<br />
<br />
* Familiarity with QT is essential.<br />
* Widgets are written in C+'', so some C''+ knowledge is also required.<br />
* Python skills are highly useful.<br />
<br />
'''Mentor(s)'''<br />
<br />
Tim O'Shea<br />
<br />
<br />
<br />
=== Standardized High Throughput FEC Codes ===<br />
<br />
Channel coding is essential to modern communications. Also, it is computationally very heavy. As of now, there exist implementations in GNU Radio which are too slow to be integrated into high throughput applications. GNU Radio would benefit from integration of standardized decoders for Turbo and LDPC codes. These codes would only support a certain subset of the whole code class but would be well optimized. <br />
<br />
'''Prerequisites'''<br />
<br />
* Understanding of ''gr-fec'' API. Knowledge on channel coding. Understanding of C++.<br />
<br />
'''Outcome'''<br />
<br />
* Standardized Codes, e.g. LTE Turbo Codes, 5G Polar Codes, 5G LDPC Codes, CCITT Convolutional Codes etc. are available in ''gr-fec''.<br />
* The preferred goal is to find a highly optimized implementation and integrate these into GNU Radio.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Johannes Demel<br />
<br />
<br />
<br />
=== Android ===<br />
<br />
One effort of the past years was to improve Android support for GNU Radio. We're getting to a point where we've figured out '''how''' to do it, so the next step is to make it more accessible to users and developers.<br />
<br />
The Android ecosystem is an entirely different beast from the rest of GNU Radio. To make writing Android/GR apps easy, the following needs to happen (and shall be part of this project):<br />
<br />
* Improve support for development environment<br />
** Create Dockers for easy start of development<br />
* Visualization classes for PSD, spectrogram and oscilloscope<br />
** Easy reuse in other apps, like the gr-qtgui widgets, but for Android SDKs<br />
* Interactivity concepts<br />
** Gestures and config for radio parameters (e.g., freq, gain, bandwidth)<br />
** Create an example FM receiver app that allows easy channel selection etc. through motions and gestures<br />
<br />
You can find a summary of the work that has been done on this (years ago) here: [[Android]]<br />
<br />
'''Prerequisites'''<br />
<br />
* Some Android experience<br />
* Enjoy writing GUI widgets<br />
* C++/Java experience<br />
<br />
'''Mentor(s)'''<br />
<br />
* Bastian Bloessl<br />
<br />
=== Filter Design Tool Enhancements ===<br />
<br />
GNU Radio provides many tools to design and use digital filters. Using these tools requires both some expertise in these areas as well as an understanding of the performance on the given platform. One example is the selection between FIR (convolution-based) and FFT (fast convolution-based) filters for different resampling rates. Another example is doing stages of filter decomposition when doing large down-sampling. Included in this is the polyphase filterbanks, which again are provided as primitive blocks that need tweaking to work.<br />
<br />
This project is to improve our uses of these tools and blocks to make it more obvious to the users as well as automate some of the decisions for optimally using them. Some pointers:<br />
<br />
* When used in GRC, we want to save the results of the tool in a local file or for use in actual blocks.<br />
* It still currently runs on PyQWT, which is obsolete and needs to be updated to Qt5<br />
** See https://github.com/trondeau/gnuradio/tree/filter/design_tool_newgui<br />
* Add more support for filter design concepts and other filters.<br />
** Cascaded filters<br />
** Better support for creating PFB filters<br />
<br />
'''Prerequisites'''<br />
<br />
* Strong DSP background required.<br />
* Python and QT knowledge highly useful (at least one of those is a must).<br />
<br />
'''Mentor(s)'''<br />
<br />
* Marcus Leech<br />
<br />
<br />
<br />
=== Implement SigMF functionality for GNU Radio ===<br />
<br />
SigMF is the "Signal Metadata Format" that was defined during the 2017 DARPA Hackfest in Brussels. Its purpose is to annotate raw binary dumps of signals with metadata, thus giving meaning to a raw mass of samples.<br /><br />
SigMF is specified and has a minimal reference implementation here: https://github.com/gnuradio/sigmf<br />
<br />
GNU Radio needs its own implementation of SigMF that ties into the block structure. The following things need to be written:<br />
<br />
* Source and Sink blocks for SigMF (similar to the current metadata blocks)<br />
* Converters for files generated with the current metadata file formats<br />
* Static analysis tools using SigMF<br />
<br />
'''Prerequisites'''<br />
<br />
* Basic understanding of how to write GNU Radio blocks is required.<br />
* Also, the student needs to explain that she or he has understood the concepts of SigMF, although SigMF is a very simple, JSON-based file format.<br />
* Depending on the precise path that the student and the mentor define, experience in GUI development would also be useful.<br />
<br />
'''Outcome'''<br />
<br />
* The source and sink blocks are by the far the most important outcomes of this project. We estimate it would take about a third of the active coding time to implement those, and have them merged around the midterms.<br />
This leaves plenty of time for further development.<br />
* The next most important task are the converters, so existing metadata files will continue to be useful. After that, the student should define own tasks based on their interests. A very relevant problem is the ability to effectively visualize metadata in combination with signals.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Bastian Bloessl, Sebastian Müller<br />
<br />
<br />
<br />
=== Statistical Toolbox for GRC ===<br />
<br />
A statistical toolbox for GRC would enable GUI-based statistical analysis. Currently, such analysis can be done by writing an independent program (e.g., with SciPy), but there is no actual integration with GNU Radio. By developing the statistical toolbox, we provide blocks for probability distribution fitting, hypothesis testing, extracting statistical parameters for one-dimensional as well as multi-dimensional data. This would significantly expand GNU Radio users' ability to perform data-science analysis and modeling on signal data.<br />
<br />
'''Prerequisites'''<br />
<br />
* Understanding of existing GNU Radio tools (e.g., GRC), GNU Radio Out-of-Tree Modules, and statistics / data-science modeling.<br />
<br />
'''Outcome'''<br />
<br />
* An OOT module that provides statistical analysis capabilities for GNU Radio.<br />
<br />
'''Mentor(s)'''<br />
<br />
* Ben Hilburn<br />
<br />
<br />
<br />
=== Digital Pre-Distortion ===<br />
<br />
Digital Pre-Distortion (DPD) is a technique allowing transmitters to compensate for non-linear responses in their hardware, most notably the power amplifier. This improves SNR and can allow more spectral and power efficient operation of a given set of hardware.<br />
<br />
DPD is widely used and is increasingly necessary as many multicarrier signals such as what are seen in DVB and LTE exhibit high peak to average power ratios (PAPRs). DPD implementations are not widely available in the open source community. This is a deficit that this project hopes to correct. Over the course of the project the student would implement standard DPD algorithms in to a GNU Radio out of tree module so that they can be available for use directly or as reference designs.<br />
<br />
'''Prerequisites'''<br />
<br />
* Workable C++ proficiency, basic knowledge of radio systems, ideally familiarity with GNU Radio and/or Digital Pre-Distortion<br />
<br />
'''Outcome'''<br />
<br />
* Implement standard memory-less and memory based DPD algorithms<br />
* Implement the training algorithms for such DPD application algorithms.<br />
* Implement a GUI tool or testbench for viewing the AM-AM and AM-PM responses of an amplifier<br />
<br />
'''Mentor(s)'''<br />
<br />
* Derek Kozel<br />
<br />
<br />
<br />
== Application process ==<br />
<br />
Students interested in participating, read the [[GSoCStudentInfo|student instructions]] and the [[GSoCManifest|rules of conduct]].<br />
* Please introduce yourself on the [https://lists.gnu.org/mailman/listinfo/discuss-gnuradio GNU Radio mailing list]<br />
* Fill in the formal application for GNU Radio<br />
* Pick some items from the list above or feel free to suggest another piece of work relevant to this theme. Give us a detailed, week-by-week plan for completing the task over the summer.</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=Hackfest2001&diff=6209Hackfest20012019-10-10T16:12:21Z<p>Bastibl: /* Participants */</p>
<hr />
<div>= Pre-FOSDEM GNU Radio Hackfest 2020 at <> = <br />
<br />
Date: January 28th - January 30th<br />
<br />
<br />
== Topics == <br />
<br />
Ideally topics are worked on in breakout groups of 3 or 4.<br />
<br />
* FPGA Accelerators (FPGA people would be useful)<br />
* VRT & SigMF tools<br />
*<br />
<br />
== Sessions ==<br />
<br />
=== Tuesday ===<br />
<br />
=== Wednesday ===<br />
<br />
=== Thursday ===<br />
<br />
== Participants == <br />
<br />
# Andrej Rode (noc0lour) (full event)<br />
# Philip Balister (Crofton)<br />
# Nathan West (nwest)<br />
# Bastian Bloessl (bastibl)<br />
<br />
<br />
[[Category:Hackfests]]</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=Hackfest1902&diff=4540Hackfest19022018-12-05T12:16:32Z<p>Bastibl: </p>
<hr />
<div>= Pre-FOSDEM GNU Radio Hackfest 2019 at HSBXL = <br />
<br />
Date: January 31st - February 1st 2019<br />
<br />
This Hackfest takes places during the pre-FOSDEM Byteweek 2019 at the Hackspace Brussels [[https://hsbxl.be/events/byteweek/2019/]].<br />
<br />
== Topics == <br />
<br />
* After 3.8 release bug crunching<br />
* PMT with msgpack replacement<br />
<br />
== Participants == <br />
<br />
# Andrej Rode (noc0lour) (both days)<br />
# Philip Balister (Crofton) (both days)<br />
# Marcus Müller (funkylab) (late Thu, full Fri)<br />
# Brennan Ashton (btashton) (afternoon Fri)<br />
# Bastian Bloessl (bastibl) (late Thu, full Fri)<br />
<br />
[[Category:Hackfests]]</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=UsingVim&diff=667UsingVim2017-03-20T12:14:27Z<p>Bastibl: /* Other useful 3rd-party plugins */</p>
<hr />
<div>= Using VIM for GNU Radio development =<br />
<br />
The VIM text editor is a popular choice among coders. If you're using VIM, this page might have some advice on how to optimize your workflow.<br /><br />
This is no introduction to Vim!<br />
<br />
== The grproject plugin ==<br />
<br />
Available from [https://github.com/mbant/grproject.vim github] .<br />
<br />
This plugin is a small extension that gives Vim some idea about the code structure. Say you're editing a GNU Radio block and call :make -- in most cases nothing will happen, because you have to be in the build-directory of your module. grproject.vim tweaks paths around such that in most cases, the right thing happens. Using this plugin will allow to :cn, gf, :make and other things and Vim will more often than not actually find the relevant files.<br />
<br />
== Other useful 3rd-party plugins ==<br />
<br />
Of course, there are hundreds of nice and useful Vim plugins. Here are a few which help specifically when writing C++ and Python code:<br />
<br />
* [https://github.com/tpope/vim-pathogen Pathogen] - If you're not using this already, you should. It organizes plugins.<br />
<br />
* [https://github.com/davidhalter/jedi-vim Jedi-vim] - This plugin provides smart autocompletion for Python scripts. E.g., you can type<br />
<br />
<pre>src = gr.vector_so</pre><br />
<br />
then hit Ctrl-Space and it will autocomplete that for you, give a function definition while you're typing etc.<br />
<br />
* [https://github.com/scrooloose/syntastic Syntastic] - Static syntax checker<br />
* [https://github.com/tpope/vim-fugitive Fugitive] - Git integration</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=Development&diff=640Development2017-03-20T06:42:12Z<p>Bastibl: /* What's this Copyright Assignment? */</p>
<hr />
<div>= Contributing to GNU Radio -- FAQ =<br />
<br />
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.<br />
<br />
== Cheat Sheet ==<br />
<br />
See the information throughout this page for details about these steps. But when making looking to contribute, we encourage you to either make a new Issue in the Issue Tracker or identify a current Issue already up and waiting for attention. We also assume you have a public Github repo you can use for the pull requests and that you have cloned the GNU Radio git repo.<br />
<br />
* Identify which branch of the GNU Radio base code to work from.<br />
* Create a new branch from here to work from.<br />
* Work on the bug fix or feature under the new branch.<br />
* Determine the QA code necessary to test and check the fix or feature.<br />
* Provide an appropriate Git commit with log messages.<br />
* Push the branch to a public repo on Github.<br />
* Issue a pull request against the starting branch (i.e., maint or master).<br />
* Update the Issue on [https://gnuradio.org gnuradio.org] with information about the fix, including a link to the pull request on Github.<br />
* Wait for the pull request to be merged -- often after some back and forth and testing by other parties.<br />
* Mark the Issue resolved and note the commit where it was resolved.<br />
<br />
The GNU Radio project maintainers will mark issues as Closed at the appropriate time.<br />
<br />
== How can I help? ==<br />
<br />
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.<br />
<br />
If you want to get involved in the development process, here's some suggestions where to start:<br />
<br />
* Documentation<br />
* Missing test cases<br />
* Bug fixes<br />
* GUIs<br />
<br />
The main place to look is the issue tracker. Also, look at the results posted by our Jenkins continuous integration service: http://jenkins.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.<br />
<br />
We also use Coverity for static code analysis. You can find our project at https://scan.coverity.com/projects. Here, you can find small things to change and fix (a lot of these are so small you don't even need an FSF copyright assignment).<br />
<br />
There's also the possibility to [https://crm.fsf.org/civicrm/contribute/transact?reset=1&id=16 donate] to our project. The Free Software Foundation provides the infrastructure to do so, and can provide a receipt for US tax payers, who can deduct a donation.<br />
<br />
== Development Style ==<br />
<br />
When writing new code, we have a few general rules for where and how things go in. We follow that standard [http://schacon.github.com/git/gitworkflows.html 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.<br />
<br />
* Make sure any changes in 'master' do not break the API (even if there is an error)<br />
** Additions to the API are fine<br />
** Deprecating code by outputting a message is done here<br />
* Removing code or changing API names or calling conventions MUST be done in 'next'<br />
* Work in 'master' for as much as possible unless you are going to change the API<br />
<br />
Following these simple rules will help get your code merged in faster and with less hassle.<br />
<br />
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:<br />
<br />
* Use TODO comments for low-priority fixes<br />
* Use FIXME comments for high-priority fixes<br />
<br />
For all kinds of modifications and changes, try and make sure the following points are observed:<br />
<br />
* 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.<br />
* Diffs are made from the GNU Radio tree root, and are based on an recent master branch.<br />
** use [http://schacon.github.com/git/git-format-patch.html git format-patch] to create your patches.<br />
** Minor bug fixes should be applied to the maint branch<br />
** Addon's and features should be applied to the master branch<br />
** Changes to the structure, API, or other surgery to the code should be applied to the next branch<br />
* After applying your changes or building your branch, the command 'make test' must pass.<br />
* There should be no additional compiler warnings to what already occurs.<br />
* No gratuitous whitespace changes.<br />
<br />
=== Quality Assurance (QA) Code ===<br />
<br />
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.<br />
<br />
Any block that is currently without a QA testing program should be fixed to have one.<br />
<br />
== I've found a bug, but I don't have the skill/time/whatever to fix it... now what? ==<br />
<br />
No problem. If it's really an unfixed bug, you're perhaps the first to stumble upon it. Write an email to the discuss-gnuradio@gnu.org mailing list explaining what's wrong and, ideally, providing a test case so the developers can reproduce the error.<br />
<br />
If it's a confirmed bug, you should add a ticket to the bug tracker (http://gnuradio.org/redmine/projects/gnuradio/issues) by following these steps:<br />
<br />
1. You'll need to login to the website, first, and then click New Issue.<br /><br />
2. Set if this Issue is a bug or perhaps a new feature.<br /><br />
3. Provide an appropriate subject to explain the Issue.<br /><br />
4. Provide a comprehensive description of the Issue. Provide links, code, and any examples here. It's much easier for us to understand a bug if we have a simple test case that demonstrates the issue such as a GRC file or Python program. Feel free to upload attachments using the Files button.<br /><br />
5. The rest of the attributes of the Issue should be left alone. The GNU Radio development team will handle assignment of the bug and any other relevant attributes.<br />
<br />
=== I've fixed and Issue! What do I do now? ===<br />
<br />
That's fantastic! Thanks! To help us provide a consistent experience resolving and fixing issues, please follow these steps.<br />
<br />
1. Create a patch. See the next set of instructions on &quot;How do I submit patches?&quot;. If you have a patch file, you can attach it to the Issue directly or use a pull request through github.com.<br /><br />
2. Update the Issue that you're addressing by setting the Issue status to Feedback and a description of the update, such as the github branch or pull request number.<br /><br />
3. Set the Resolution field to Fixed.<br />
<br />
The GNU Radio development team will take the issue from here. We will handle applying or merging the fix and updating the issue from there. We will set the Status to Resolved and set the target version it belongs to. After a week or so without incident, we will close the Issue.<br />
<br />
See the next section for how to work with our Issue Tracker.<br />
<br />
== Dealing with the GNU Radio Issue Tracker ==<br />
<br />
If you are filing a new bug or feature request, here's what you need to know. First, you'll need an account on gnuradio.org. Sign up for that and make sure you can log in; if you have trouble logging in, contact Tom Rondeau for help with your account.<br />
<br />
Once logged in, you will see the New Issue option right next to Issues. Clicking that will take you to the page to enter the issue you wish to file. First select if this is a bug or a feature and provide a subject line describing it. Fill out the description as clearly as possible to describe the bug or feature. If it's a bug, it is most helpful to us if you would also attached an example application that exercises the bug so that we can easily test it. Add a file by looking below to the Files item and select the button &quot;Choose Files&quot;.<br />
<br />
The rest of the fields are mostly left alone by the initial filer. The GNU Radio team will take a look at the issue and fill in the appropriate fields from there. If the Category of the bug is obvious, please fill that in as appropriate.<br />
<br />
You may select a priority, though we ask you to be reasonable in your assessment of the priority with respect to the project and not your personal requirements. If this is a feature that you are willing to work on or a bug that you feel you can handle yourself, you may also assign yourself to the task. We, of course, will then expect you to actually complete any issues assigned to you in that case.<br />
<br />
=== What do the different Status levels mean? ===<br />
<br />
* New: the default assignment when an issue is added and nothing has been done.<br />
* Feedback: the bug is unclear, we don't know what to do, or it needs more discussion.<br />
* Assigned: we know what to do and have given it to some someone to do it.<br />
* Resolved: patch submitted and merged into maint/master/next. We then wait a few weeks to see if it causes any problems or any other feedback.<br />
* Closed: after a few weeks of either positive or no farther issue with the resolution, we officially close it.<br />
<br />
It is the task of the developer assigned to a task to update the issue for ever level except closed. The GNU Radio management team will decide when to officially close an issue.<br />
<br />
=== Assignment ===<br />
<br />
Assignment to an Issue means that an individual has taken on the task of handling that particular issue of either fixing a bug or adding a feature. When assigned, that issue is claimed by the assignee, and so we expect that person to handle the task. Assigned issues that are not kept up on will be either removed or the assignee will be taken off. Removing the issue will generally occur with a feature request where that feature is not being managed properly. If it is a bug, inaction on it means that others may be discouraged from working on this because it is already assigned.<br />
<br />
There are a few categories that have default assignments to someone on the GNU Radio development team. The default assignment should be looked at as a triage operation. When assigned, the default assignee should look at the issue and decide how to handle it. It might be that someone else should be assigned to that task, or if it falls outside of the abilities, availability of time, or other such reasons, the default assignee can remove themselves from the issue thus freeing it up for others to take.<br />
<br />
=== Target Version ===<br />
<br />
Please leave the Target Version field blank until the issue is resolved. We handle this differently in our project than most as we do not build up a list of issues to tackle on a per-release basis.<br />
<br />
== How do I submit patches? ==<br />
<br />
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, you can just create a diff and attach that to the entry to the issue tracker. Please include a description of the bug and how your patch fixes this bug (see above on obtaining permissions to create bug tracker entries.)<br />
<br />
Another easy, very useful (for both you and us) way is to go through github and send us a pull request (See: How can I use github? below).<br />
<br />
In most cases, these are the commands you will enter:<br />
<br />
<pre># You've just finished editing the patch<br />
$ git add FILE1 FILE2... # Put all the patch-relevant files here<br />
$ git commit -m 'filter: re-snazzled the frombobulator (was zingamawonking)'<br />
$ git format-patch HEAD~ # This will turn the latest commit into a patch file</pre><br />
Note that the commit message should be prefixed with the component you changed (core, filter, audio, ...). Read the previous commit logs for examples (you can get them with 'git log').<br />
<br />
The last command creates a file, usually starting with '0001', which contains the patch. Simply upload this to the issue tracker.<br />
<br />
For larger patches (e.g. several commits), it is probably better to upload a modified version of the git repository, e.g. to github (see below).<br /><br />
If you want to extend GNU Radio and add new features, please read 'How can I add new features to GNU Radio?'.<br />
<br />
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'.<br />
<br />
== How can I add new features to GNU Radio? ==<br />
<br />
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.<br />
<br />
Of course some features (say, new modulators or filters) 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 post a 'Feature' on our issue tracker. This is explained greater detail [http://gnuradio.squarespace.com/blog/2010/10/29/using-git-with-github-for-developing.html here] .<br />
<br />
Before submitting, go through the following check list:<br />
<br />
* Does the code include documentation? GNU Radio uses Doxygen for automatic doc generation, so be aware of this when documenting classes.<br />
* Are there unit tests? Are they ''sensible'' unit tests, i.e. do they cover the most common errors?<br />
* Does the patch maintain compatibility with the existing code base?<br />
* Does the code follow the [[coding_guide_impl|GNU Radio coding conventions]]?<br />
* Is the code based on the latest GNU Radio revision?<br />
* Is the code nicely portable?<br />
* Do you have a copyright assignment on file with the FSF?<br />
<br />
If you're having any trouble with this, don't hesitate to ask on the mailing list.<br />
<br />
== How can I use github to submit patches/features/changes? ==<br />
<br />
'''Note:''' This is the recommended way to provide changes to the GNU Radio code.<br />
<br />
Here's the easiest way:<br />
<br />
* [https://help.github.com/articles/fork-a-repo/ Fork] a repository from https://github.com/gnuradio/gnuradio<br />
* Clone your repository or add it as a remote to a previously cloned gnuradio repo:<br />
** $ git remote add <name for your repo> <SSH link to your forked repo><br />
** $ git remote update <name of your repo><br />
* Make a new feature branch -- please make this distinct from maint/master/next<br />
** $ git branch <feature branch name><br />
** $ git checkout <feature branch name><br />
* Commit your changes on your new branch<br />
** $ git commit <files or -a for all changes><br />
* Make sure it compiles, works, and passes QA<br />
** $ make<br />
** $ make test (or ctest)<br />
* [https://help.github.com/articles/using-pull-requests/ Submit a Pull Request] to merge your branch back into the gnuradio/gnuradio repository<br />
* Wait for us to process that<br />
<br />
You need to figure out what the base branch is for you to work off of. Most likely, this will be either maint or master, but it could be next:<br />
<br />
* '''maint:''' our bug patch branch; this will become a bug release against the current version. These are for bugs only; no new features. Any patches made to this branch will also be applied to the master and next branch. This branch becomes the patch version of a release, the p of an X.Y.Z.p (omitted if p=0).<br />
* '''master:''' this will become our next minor version release, the Z of an X.Y.Z version. This is where new code codes that’s more than just a bug patch.<br />
* '''next:''' in the X.Y.Z model, this is the staging area for the Y version increments, also called the API version. All code within a release version has the same compatible API. If you use code in the X.Y API release starting with minor release Z0, then all releases after Z0 in that API version are guaranteed to have the same backwards-compatible API. We put stuff on the next branch when we have to break the API. We try to avoid this whenever possible since API releases are rare and so any code submitted here will not be released for a while.<br />
<br />
Keep in mind that a pull request is not a guaranteed merge on our part. We will vet the code for both correctness, usefulness, and style, and we might push back requesting some changes. There will likely be a bit of back and forth on this, so don't be discouraged; we're just trying to make sure that the code always gets better.<br />
<br />
== Which kind of patches are accepted into GNU Radio? ==<br />
<br />
There is no definitive answer to this. Bug fixes and missing QA codes are of course always welcome.<br />
<br />
Ultimately, the decision lies with the maintainers. If in doubt, consult the mailing list.<br />
<br />
== How long does it take for my patch to become part of GNU Radio? ==<br />
<br />
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.<br />
<br />
However, the following things are guaranteed to delay acceptance:<br />
<br />
* Lack of documentation and/or test cases<br />
* Not complying with the [[coding_guide_impl|coding conventions]]<br />
* Non-portable code<br />
* QA failures<br />
* Breaking of next (if it was in master)<br />
* Lack of [[Development#Whats-this-Copyright-Assignment|copyright assignment]]<br />
<br />
== What if my patch works for master, but not for next? ==<br />
<br />
Ideally, you do this:<br />
<br />
# Create a branch off master, say foo-master<br />
# Implement feature or fix on foo-master<br />
# Create a branch off next called foo-next<br />
# Merge foo-master into foo-next, fix up breakage<br />
# Implement feature or fix on foo-next (this might have been done or partially done as a result of getting through #4)<br />
# Tell us about foo-master and foo-next<br />
<br />
Then we:<br />
<br />
# Merge foo-master into master. No problems since foo-master is branched from master.<br />
# Merge foo-next into next. No problems since #4 above already dealt with merge breakage<br />
# Merge master into next. This should end up being a null merge, but it maintains the master-&gt;next linkage<br />
<br />
== What's this CGRAN? ==<br />
<br />
The Comprehensive GNU Radio Archive Network ([http://cgran.org/ 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.<br />
<br />
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.<br />
<br />
== Which coding conventions apply? ==<br />
<br />
All contributions should conform to the [http://www.gnu.org/prep/standards_toc.html GNU Coding Standards] as modified for C++ in README.hacking<br />
<br />
Also, you should check out [[Coding_guide_impl|The GNU Radio Coding Style Guide]].<br />
<br />
== How is the code documented? ==<br />
<br />
GNU Radio uses [http://www.stack.nl/~dimitri/doxygen 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 <code>docs/doxygen/other/group_defs.dox</code>. Below is an example of a marked-up header file.<br />
<br />
<pre>/*!<br />
* \brief A new block that does something.<br />
* \ingroup some_group<br />
* \ingroup another_group<br />
*<br />
* Detailed description of what this block does.<br />
* Quoting papers or textbooks is a good idea, too.<br />
*/<br />
class MODNAME_API new_block : public gr::block<br />
{<br />
private:<br />
new_block(int param1, double param2);<br />
<br />
public:<br />
typedef boost::shared_ptr sptr;<br />
<br />
/*!<br />
* \brief Description of public_function()<br />
* \param foo Describe foo<br />
* \param bar Describe bar<br />
*/<br />
virtual int public_function(int foo, float bar) = 0;<br />
<br />
/*!<br />
* \param param1 Describe param1<br />
* \param param2 Describe param2<br />
*/<br />
static sptr make(int param1, double param2);<br />
<br />
};</pre><br />
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 <code>docs/doxygen/other/main_page.dox</code>.<br />
<br />
The top level blocks are all described inside that blocks <code>doc</code> directory in a <code>.dox</code> files named or the component. For example, in the component <code>gr-digital</code>, the manual page describing this component is in <code>gr-digital/doc/digital.dox</code>. 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.<br />
<br />
The component's <code>doc</code> directory will also contain a <code>README.package</code> 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.<br />
<br />
=== Doxygen Markup for Formulas ===<br />
<br />
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 &quot;\f{&quot; to begin and &quot;\f}&quot; 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:<br />
<br />
<pre>This is some text in the header...<br />
\f{html}{<br />
enter Latex formula here -&gt; will only show up in the HTML document.<br />
}<br />
<br />
\xmlonly<br />
Same Latex formula, but this will not be processed; will only be the raw Latex formula.<br />
\endxmlonly<br />
<br />
And here's some following text to the formulas.</pre><br />
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 &quot;\ f&quot;.<br />
<br />
== What's this Copyright Assignment? ==<br />
<br />
Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the [http://www.fsf.org/ FSF]. A description of the process is available [http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html here]. Basically, this guarantees the FSF (who is copyright holder of GNU Radio) does not run into any legal trouble somewhere down the road.<br />
<br />
This boils down to the following instructions:<br />
<br />
* If you've developed some addition or patch to GNU Radio that you would like to contribute, you should send an email to the mailing list, or to one of the GNU Radio maintainers asking for an appropriate form. We might ask you for some more information at this point.<br />
* You will be sent a short form by email which you should fill in and email back to the FSF.<br />
* Once the FSF have received this email, they will send you a paper copy of the full copyright assignment papers for you to sign and post back to them.<br />
* As soon as the signed paperwork is filed at the FSF we can accept your changes into the source tree.<br />
* Individual small changes (fewer than 10 lines of code) can, however, be accepted without a copyright assignment form on file.<br />
<br />
In order to get the process rolling, please email &quot;tom AT trondeau&quot; for a form to start the copyright process.<br />
<br />
== Who maintains GNU Radio? ==<br />
<br />
GNU Radio is currently maintained by:<br />
<br />
* [https://github.com/bhilburn Ben Hilburn] (Project Lead) and<br />
* [http://corganlabs.com Johnathan Corgan] (Chief Architect) and<br />
* Nathan West (Release Manager) and<br />
* Martin Braun (Community Manager)<br />
<br />
See also the [[Organization|full list of GNU Radio staff]].<br />
<br />
GNU Radio was founded and initially maintained by:<br />
<br />
* [http://www.comsec.com Eric Blossom]</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=Development&diff=639Development2017-03-20T06:40:49Z<p>Bastibl: /* How long does it take for my patch to become part of GNU Radio? */</p>
<hr />
<div>= Contributing to GNU Radio -- FAQ =<br />
<br />
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.<br />
<br />
== Cheat Sheet ==<br />
<br />
See the information throughout this page for details about these steps. But when making looking to contribute, we encourage you to either make a new Issue in the Issue Tracker or identify a current Issue already up and waiting for attention. We also assume you have a public Github repo you can use for the pull requests and that you have cloned the GNU Radio git repo.<br />
<br />
* Identify which branch of the GNU Radio base code to work from.<br />
* Create a new branch from here to work from.<br />
* Work on the bug fix or feature under the new branch.<br />
* Determine the QA code necessary to test and check the fix or feature.<br />
* Provide an appropriate Git commit with log messages.<br />
* Push the branch to a public repo on Github.<br />
* Issue a pull request against the starting branch (i.e., maint or master).<br />
* Update the Issue on [https://gnuradio.org gnuradio.org] with information about the fix, including a link to the pull request on Github.<br />
* Wait for the pull request to be merged -- often after some back and forth and testing by other parties.<br />
* Mark the Issue resolved and note the commit where it was resolved.<br />
<br />
The GNU Radio project maintainers will mark issues as Closed at the appropriate time.<br />
<br />
== How can I help? ==<br />
<br />
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.<br />
<br />
If you want to get involved in the development process, here's some suggestions where to start:<br />
<br />
* Documentation<br />
* Missing test cases<br />
* Bug fixes<br />
* GUIs<br />
<br />
The main place to look is the issue tracker. Also, look at the results posted by our Jenkins continuous integration service: http://jenkins.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.<br />
<br />
We also use Coverity for static code analysis. You can find our project at https://scan.coverity.com/projects. Here, you can find small things to change and fix (a lot of these are so small you don't even need an FSF copyright assignment).<br />
<br />
There's also the possibility to [https://crm.fsf.org/civicrm/contribute/transact?reset=1&id=16 donate] to our project. The Free Software Foundation provides the infrastructure to do so, and can provide a receipt for US tax payers, who can deduct a donation.<br />
<br />
== Development Style ==<br />
<br />
When writing new code, we have a few general rules for where and how things go in. We follow that standard [http://schacon.github.com/git/gitworkflows.html 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.<br />
<br />
* Make sure any changes in 'master' do not break the API (even if there is an error)<br />
** Additions to the API are fine<br />
** Deprecating code by outputting a message is done here<br />
* Removing code or changing API names or calling conventions MUST be done in 'next'<br />
* Work in 'master' for as much as possible unless you are going to change the API<br />
<br />
Following these simple rules will help get your code merged in faster and with less hassle.<br />
<br />
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:<br />
<br />
* Use TODO comments for low-priority fixes<br />
* Use FIXME comments for high-priority fixes<br />
<br />
For all kinds of modifications and changes, try and make sure the following points are observed:<br />
<br />
* 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.<br />
* Diffs are made from the GNU Radio tree root, and are based on an recent master branch.<br />
** use [http://schacon.github.com/git/git-format-patch.html git format-patch] to create your patches.<br />
** Minor bug fixes should be applied to the maint branch<br />
** Addon's and features should be applied to the master branch<br />
** Changes to the structure, API, or other surgery to the code should be applied to the next branch<br />
* After applying your changes or building your branch, the command 'make test' must pass.<br />
* There should be no additional compiler warnings to what already occurs.<br />
* No gratuitous whitespace changes.<br />
<br />
=== Quality Assurance (QA) Code ===<br />
<br />
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.<br />
<br />
Any block that is currently without a QA testing program should be fixed to have one.<br />
<br />
== I've found a bug, but I don't have the skill/time/whatever to fix it... now what? ==<br />
<br />
No problem. If it's really an unfixed bug, you're perhaps the first to stumble upon it. Write an email to the discuss-gnuradio@gnu.org mailing list explaining what's wrong and, ideally, providing a test case so the developers can reproduce the error.<br />
<br />
If it's a confirmed bug, you should add a ticket to the bug tracker (http://gnuradio.org/redmine/projects/gnuradio/issues) by following these steps:<br />
<br />
1. You'll need to login to the website, first, and then click New Issue.<br /><br />
2. Set if this Issue is a bug or perhaps a new feature.<br /><br />
3. Provide an appropriate subject to explain the Issue.<br /><br />
4. Provide a comprehensive description of the Issue. Provide links, code, and any examples here. It's much easier for us to understand a bug if we have a simple test case that demonstrates the issue such as a GRC file or Python program. Feel free to upload attachments using the Files button.<br /><br />
5. The rest of the attributes of the Issue should be left alone. The GNU Radio development team will handle assignment of the bug and any other relevant attributes.<br />
<br />
=== I've fixed and Issue! What do I do now? ===<br />
<br />
That's fantastic! Thanks! To help us provide a consistent experience resolving and fixing issues, please follow these steps.<br />
<br />
1. Create a patch. See the next set of instructions on &quot;How do I submit patches?&quot;. If you have a patch file, you can attach it to the Issue directly or use a pull request through github.com.<br /><br />
2. Update the Issue that you're addressing by setting the Issue status to Feedback and a description of the update, such as the github branch or pull request number.<br /><br />
3. Set the Resolution field to Fixed.<br />
<br />
The GNU Radio development team will take the issue from here. We will handle applying or merging the fix and updating the issue from there. We will set the Status to Resolved and set the target version it belongs to. After a week or so without incident, we will close the Issue.<br />
<br />
See the next section for how to work with our Issue Tracker.<br />
<br />
== Dealing with the GNU Radio Issue Tracker ==<br />
<br />
If you are filing a new bug or feature request, here's what you need to know. First, you'll need an account on gnuradio.org. Sign up for that and make sure you can log in; if you have trouble logging in, contact Tom Rondeau for help with your account.<br />
<br />
Once logged in, you will see the New Issue option right next to Issues. Clicking that will take you to the page to enter the issue you wish to file. First select if this is a bug or a feature and provide a subject line describing it. Fill out the description as clearly as possible to describe the bug or feature. If it's a bug, it is most helpful to us if you would also attached an example application that exercises the bug so that we can easily test it. Add a file by looking below to the Files item and select the button &quot;Choose Files&quot;.<br />
<br />
The rest of the fields are mostly left alone by the initial filer. The GNU Radio team will take a look at the issue and fill in the appropriate fields from there. If the Category of the bug is obvious, please fill that in as appropriate.<br />
<br />
You may select a priority, though we ask you to be reasonable in your assessment of the priority with respect to the project and not your personal requirements. If this is a feature that you are willing to work on or a bug that you feel you can handle yourself, you may also assign yourself to the task. We, of course, will then expect you to actually complete any issues assigned to you in that case.<br />
<br />
=== What do the different Status levels mean? ===<br />
<br />
* New: the default assignment when an issue is added and nothing has been done.<br />
* Feedback: the bug is unclear, we don't know what to do, or it needs more discussion.<br />
* Assigned: we know what to do and have given it to some someone to do it.<br />
* Resolved: patch submitted and merged into maint/master/next. We then wait a few weeks to see if it causes any problems or any other feedback.<br />
* Closed: after a few weeks of either positive or no farther issue with the resolution, we officially close it.<br />
<br />
It is the task of the developer assigned to a task to update the issue for ever level except closed. The GNU Radio management team will decide when to officially close an issue.<br />
<br />
=== Assignment ===<br />
<br />
Assignment to an Issue means that an individual has taken on the task of handling that particular issue of either fixing a bug or adding a feature. When assigned, that issue is claimed by the assignee, and so we expect that person to handle the task. Assigned issues that are not kept up on will be either removed or the assignee will be taken off. Removing the issue will generally occur with a feature request where that feature is not being managed properly. If it is a bug, inaction on it means that others may be discouraged from working on this because it is already assigned.<br />
<br />
There are a few categories that have default assignments to someone on the GNU Radio development team. The default assignment should be looked at as a triage operation. When assigned, the default assignee should look at the issue and decide how to handle it. It might be that someone else should be assigned to that task, or if it falls outside of the abilities, availability of time, or other such reasons, the default assignee can remove themselves from the issue thus freeing it up for others to take.<br />
<br />
=== Target Version ===<br />
<br />
Please leave the Target Version field blank until the issue is resolved. We handle this differently in our project than most as we do not build up a list of issues to tackle on a per-release basis.<br />
<br />
== How do I submit patches? ==<br />
<br />
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, you can just create a diff and attach that to the entry to the issue tracker. Please include a description of the bug and how your patch fixes this bug (see above on obtaining permissions to create bug tracker entries.)<br />
<br />
Another easy, very useful (for both you and us) way is to go through github and send us a pull request (See: How can I use github? below).<br />
<br />
In most cases, these are the commands you will enter:<br />
<br />
<pre># You've just finished editing the patch<br />
$ git add FILE1 FILE2... # Put all the patch-relevant files here<br />
$ git commit -m 'filter: re-snazzled the frombobulator (was zingamawonking)'<br />
$ git format-patch HEAD~ # This will turn the latest commit into a patch file</pre><br />
Note that the commit message should be prefixed with the component you changed (core, filter, audio, ...). Read the previous commit logs for examples (you can get them with 'git log').<br />
<br />
The last command creates a file, usually starting with '0001', which contains the patch. Simply upload this to the issue tracker.<br />
<br />
For larger patches (e.g. several commits), it is probably better to upload a modified version of the git repository, e.g. to github (see below).<br /><br />
If you want to extend GNU Radio and add new features, please read 'How can I add new features to GNU Radio?'.<br />
<br />
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'.<br />
<br />
== How can I add new features to GNU Radio? ==<br />
<br />
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.<br />
<br />
Of course some features (say, new modulators or filters) 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 post a 'Feature' on our issue tracker. This is explained greater detail [http://gnuradio.squarespace.com/blog/2010/10/29/using-git-with-github-for-developing.html here] .<br />
<br />
Before submitting, go through the following check list:<br />
<br />
* Does the code include documentation? GNU Radio uses Doxygen for automatic doc generation, so be aware of this when documenting classes.<br />
* Are there unit tests? Are they ''sensible'' unit tests, i.e. do they cover the most common errors?<br />
* Does the patch maintain compatibility with the existing code base?<br />
* Does the code follow the [[coding_guide_impl|GNU Radio coding conventions]]?<br />
* Is the code based on the latest GNU Radio revision?<br />
* Is the code nicely portable?<br />
* Do you have a copyright assignment on file with the FSF?<br />
<br />
If you're having any trouble with this, don't hesitate to ask on the mailing list.<br />
<br />
== How can I use github to submit patches/features/changes? ==<br />
<br />
'''Note:''' This is the recommended way to provide changes to the GNU Radio code.<br />
<br />
Here's the easiest way:<br />
<br />
* [https://help.github.com/articles/fork-a-repo/ Fork] a repository from https://github.com/gnuradio/gnuradio<br />
* Clone your repository or add it as a remote to a previously cloned gnuradio repo:<br />
** $ git remote add <name for your repo> <SSH link to your forked repo><br />
** $ git remote update <name of your repo><br />
* Make a new feature branch -- please make this distinct from maint/master/next<br />
** $ git branch <feature branch name><br />
** $ git checkout <feature branch name><br />
* Commit your changes on your new branch<br />
** $ git commit <files or -a for all changes><br />
* Make sure it compiles, works, and passes QA<br />
** $ make<br />
** $ make test (or ctest)<br />
* [https://help.github.com/articles/using-pull-requests/ Submit a Pull Request] to merge your branch back into the gnuradio/gnuradio repository<br />
* Wait for us to process that<br />
<br />
You need to figure out what the base branch is for you to work off of. Most likely, this will be either maint or master, but it could be next:<br />
<br />
* '''maint:''' our bug patch branch; this will become a bug release against the current version. These are for bugs only; no new features. Any patches made to this branch will also be applied to the master and next branch. This branch becomes the patch version of a release, the p of an X.Y.Z.p (omitted if p=0).<br />
* '''master:''' this will become our next minor version release, the Z of an X.Y.Z version. This is where new code codes that’s more than just a bug patch.<br />
* '''next:''' in the X.Y.Z model, this is the staging area for the Y version increments, also called the API version. All code within a release version has the same compatible API. If you use code in the X.Y API release starting with minor release Z0, then all releases after Z0 in that API version are guaranteed to have the same backwards-compatible API. We put stuff on the next branch when we have to break the API. We try to avoid this whenever possible since API releases are rare and so any code submitted here will not be released for a while.<br />
<br />
Keep in mind that a pull request is not a guaranteed merge on our part. We will vet the code for both correctness, usefulness, and style, and we might push back requesting some changes. There will likely be a bit of back and forth on this, so don't be discouraged; we're just trying to make sure that the code always gets better.<br />
<br />
== Which kind of patches are accepted into GNU Radio? ==<br />
<br />
There is no definitive answer to this. Bug fixes and missing QA codes are of course always welcome.<br />
<br />
Ultimately, the decision lies with the maintainers. If in doubt, consult the mailing list.<br />
<br />
== How long does it take for my patch to become part of GNU Radio? ==<br />
<br />
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.<br />
<br />
However, the following things are guaranteed to delay acceptance:<br />
<br />
* Lack of documentation and/or test cases<br />
* Not complying with the [[coding_guide_impl|coding conventions]]<br />
* Non-portable code<br />
* QA failures<br />
* Breaking of next (if it was in master)<br />
* Lack of [[Development#Whats-this-Copyright-Assignment|copyright assignment]]<br />
<br />
== What if my patch works for master, but not for next? ==<br />
<br />
Ideally, you do this:<br />
<br />
# Create a branch off master, say foo-master<br />
# Implement feature or fix on foo-master<br />
# Create a branch off next called foo-next<br />
# Merge foo-master into foo-next, fix up breakage<br />
# Implement feature or fix on foo-next (this might have been done or partially done as a result of getting through #4)<br />
# Tell us about foo-master and foo-next<br />
<br />
Then we:<br />
<br />
# Merge foo-master into master. No problems since foo-master is branched from master.<br />
# Merge foo-next into next. No problems since #4 above already dealt with merge breakage<br />
# Merge master into next. This should end up being a null merge, but it maintains the master-&gt;next linkage<br />
<br />
== What's this CGRAN? ==<br />
<br />
The Comprehensive GNU Radio Archive Network ([http://cgran.org/ 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.<br />
<br />
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.<br />
<br />
== Which coding conventions apply? ==<br />
<br />
All contributions should conform to the [http://www.gnu.org/prep/standards_toc.html GNU Coding Standards] as modified for C++ in README.hacking<br />
<br />
Also, you should check out [[Coding_guide_impl|The GNU Radio Coding Style Guide]].<br />
<br />
== How is the code documented? ==<br />
<br />
GNU Radio uses [http://www.stack.nl/~dimitri/doxygen 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 <code>docs/doxygen/other/group_defs.dox</code>. Below is an example of a marked-up header file.<br />
<br />
<pre>/*!<br />
* \brief A new block that does something.<br />
* \ingroup some_group<br />
* \ingroup another_group<br />
*<br />
* Detailed description of what this block does.<br />
* Quoting papers or textbooks is a good idea, too.<br />
*/<br />
class MODNAME_API new_block : public gr::block<br />
{<br />
private:<br />
new_block(int param1, double param2);<br />
<br />
public:<br />
typedef boost::shared_ptr sptr;<br />
<br />
/*!<br />
* \brief Description of public_function()<br />
* \param foo Describe foo<br />
* \param bar Describe bar<br />
*/<br />
virtual int public_function(int foo, float bar) = 0;<br />
<br />
/*!<br />
* \param param1 Describe param1<br />
* \param param2 Describe param2<br />
*/<br />
static sptr make(int param1, double param2);<br />
<br />
};</pre><br />
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 <code>docs/doxygen/other/main_page.dox</code>.<br />
<br />
The top level blocks are all described inside that blocks <code>doc</code> directory in a <code>.dox</code> files named or the component. For example, in the component <code>gr-digital</code>, the manual page describing this component is in <code>gr-digital/doc/digital.dox</code>. 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.<br />
<br />
The component's <code>doc</code> directory will also contain a <code>README.package</code> 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.<br />
<br />
=== Doxygen Markup for Formulas ===<br />
<br />
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 &quot;\f{&quot; to begin and &quot;\f}&quot; 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:<br />
<br />
<pre>This is some text in the header...<br />
\f{html}{<br />
enter Latex formula here -&gt; will only show up in the HTML document.<br />
}<br />
<br />
\xmlonly<br />
Same Latex formula, but this will not be processed; will only be the raw Latex formula.<br />
\endxmlonly<br />
<br />
And here's some following text to the formulas.</pre><br />
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 &quot;\ f&quot;.<br />
<br />
== What's this Copyright Assignment? ==<br />
<br />
Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the [http://www.fsf.org/ FSF]. A description of the process is available [http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html here]. Basically, this guarantees the FSF (who is copyright holder of GNU Radio) does not run into any legal trouble somewhere down the road.<br />
<br />
This boils down to the following instructions:<br />
<br />
'''''' If you've developed some addition or patch to GNU Radio that you would like to contribute, you should send an email to the mailing list, or to one of the GNU Radio maintainers asking for an appropriate form. We might ask you for some more information at this point.<br />
<br />
'''''' You will be sent a short form by email which you should fill in and email back to the FSF.<br />
<br />
'''''' Once the FSF have received this email, they will send you a paper copy of the full copyright assignment papers for you to sign and post back to them.<br />
<br />
'''''' As soon as the signed paperwork is filed at the FSF we can accept your changes into the source tree.<br />
<br />
'''''' Individual small changes (fewer than 10 lines of code) can, however, be accepted without a copyright assignment form on file.<br />
<br />
In order to get the process rolling, please email &quot;tom AT trondeau&quot; for a form to start the copyright process.<br />
<br />
== Who maintains GNU Radio? ==<br />
<br />
GNU Radio is currently maintained by:<br />
<br />
* [https://github.com/bhilburn Ben Hilburn] (Project Lead) and<br />
* [http://corganlabs.com Johnathan Corgan] (Chief Architect) and<br />
* Nathan West (Release Manager) and<br />
* Martin Braun (Community Manager)<br />
<br />
See also the [[Organization|full list of GNU Radio staff]].<br />
<br />
GNU Radio was founded and initially maintained by:<br />
<br />
* [http://www.comsec.com Eric Blossom]</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=Development&diff=638Development2017-03-20T06:39:50Z<p>Bastibl: /* How can I add new features to GNU Radio? */</p>
<hr />
<div>= Contributing to GNU Radio -- FAQ =<br />
<br />
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.<br />
<br />
== Cheat Sheet ==<br />
<br />
See the information throughout this page for details about these steps. But when making looking to contribute, we encourage you to either make a new Issue in the Issue Tracker or identify a current Issue already up and waiting for attention. We also assume you have a public Github repo you can use for the pull requests and that you have cloned the GNU Radio git repo.<br />
<br />
* Identify which branch of the GNU Radio base code to work from.<br />
* Create a new branch from here to work from.<br />
* Work on the bug fix or feature under the new branch.<br />
* Determine the QA code necessary to test and check the fix or feature.<br />
* Provide an appropriate Git commit with log messages.<br />
* Push the branch to a public repo on Github.<br />
* Issue a pull request against the starting branch (i.e., maint or master).<br />
* Update the Issue on [https://gnuradio.org gnuradio.org] with information about the fix, including a link to the pull request on Github.<br />
* Wait for the pull request to be merged -- often after some back and forth and testing by other parties.<br />
* Mark the Issue resolved and note the commit where it was resolved.<br />
<br />
The GNU Radio project maintainers will mark issues as Closed at the appropriate time.<br />
<br />
== How can I help? ==<br />
<br />
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.<br />
<br />
If you want to get involved in the development process, here's some suggestions where to start:<br />
<br />
* Documentation<br />
* Missing test cases<br />
* Bug fixes<br />
* GUIs<br />
<br />
The main place to look is the issue tracker. Also, look at the results posted by our Jenkins continuous integration service: http://jenkins.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.<br />
<br />
We also use Coverity for static code analysis. You can find our project at https://scan.coverity.com/projects. Here, you can find small things to change and fix (a lot of these are so small you don't even need an FSF copyright assignment).<br />
<br />
There's also the possibility to [https://crm.fsf.org/civicrm/contribute/transact?reset=1&id=16 donate] to our project. The Free Software Foundation provides the infrastructure to do so, and can provide a receipt for US tax payers, who can deduct a donation.<br />
<br />
== Development Style ==<br />
<br />
When writing new code, we have a few general rules for where and how things go in. We follow that standard [http://schacon.github.com/git/gitworkflows.html 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.<br />
<br />
* Make sure any changes in 'master' do not break the API (even if there is an error)<br />
** Additions to the API are fine<br />
** Deprecating code by outputting a message is done here<br />
* Removing code or changing API names or calling conventions MUST be done in 'next'<br />
* Work in 'master' for as much as possible unless you are going to change the API<br />
<br />
Following these simple rules will help get your code merged in faster and with less hassle.<br />
<br />
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:<br />
<br />
* Use TODO comments for low-priority fixes<br />
* Use FIXME comments for high-priority fixes<br />
<br />
For all kinds of modifications and changes, try and make sure the following points are observed:<br />
<br />
* 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.<br />
* Diffs are made from the GNU Radio tree root, and are based on an recent master branch.<br />
** use [http://schacon.github.com/git/git-format-patch.html git format-patch] to create your patches.<br />
** Minor bug fixes should be applied to the maint branch<br />
** Addon's and features should be applied to the master branch<br />
** Changes to the structure, API, or other surgery to the code should be applied to the next branch<br />
* After applying your changes or building your branch, the command 'make test' must pass.<br />
* There should be no additional compiler warnings to what already occurs.<br />
* No gratuitous whitespace changes.<br />
<br />
=== Quality Assurance (QA) Code ===<br />
<br />
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.<br />
<br />
Any block that is currently without a QA testing program should be fixed to have one.<br />
<br />
== I've found a bug, but I don't have the skill/time/whatever to fix it... now what? ==<br />
<br />
No problem. If it's really an unfixed bug, you're perhaps the first to stumble upon it. Write an email to the discuss-gnuradio@gnu.org mailing list explaining what's wrong and, ideally, providing a test case so the developers can reproduce the error.<br />
<br />
If it's a confirmed bug, you should add a ticket to the bug tracker (http://gnuradio.org/redmine/projects/gnuradio/issues) by following these steps:<br />
<br />
1. You'll need to login to the website, first, and then click New Issue.<br /><br />
2. Set if this Issue is a bug or perhaps a new feature.<br /><br />
3. Provide an appropriate subject to explain the Issue.<br /><br />
4. Provide a comprehensive description of the Issue. Provide links, code, and any examples here. It's much easier for us to understand a bug if we have a simple test case that demonstrates the issue such as a GRC file or Python program. Feel free to upload attachments using the Files button.<br /><br />
5. The rest of the attributes of the Issue should be left alone. The GNU Radio development team will handle assignment of the bug and any other relevant attributes.<br />
<br />
=== I've fixed and Issue! What do I do now? ===<br />
<br />
That's fantastic! Thanks! To help us provide a consistent experience resolving and fixing issues, please follow these steps.<br />
<br />
1. Create a patch. See the next set of instructions on &quot;How do I submit patches?&quot;. If you have a patch file, you can attach it to the Issue directly or use a pull request through github.com.<br /><br />
2. Update the Issue that you're addressing by setting the Issue status to Feedback and a description of the update, such as the github branch or pull request number.<br /><br />
3. Set the Resolution field to Fixed.<br />
<br />
The GNU Radio development team will take the issue from here. We will handle applying or merging the fix and updating the issue from there. We will set the Status to Resolved and set the target version it belongs to. After a week or so without incident, we will close the Issue.<br />
<br />
See the next section for how to work with our Issue Tracker.<br />
<br />
== Dealing with the GNU Radio Issue Tracker ==<br />
<br />
If you are filing a new bug or feature request, here's what you need to know. First, you'll need an account on gnuradio.org. Sign up for that and make sure you can log in; if you have trouble logging in, contact Tom Rondeau for help with your account.<br />
<br />
Once logged in, you will see the New Issue option right next to Issues. Clicking that will take you to the page to enter the issue you wish to file. First select if this is a bug or a feature and provide a subject line describing it. Fill out the description as clearly as possible to describe the bug or feature. If it's a bug, it is most helpful to us if you would also attached an example application that exercises the bug so that we can easily test it. Add a file by looking below to the Files item and select the button &quot;Choose Files&quot;.<br />
<br />
The rest of the fields are mostly left alone by the initial filer. The GNU Radio team will take a look at the issue and fill in the appropriate fields from there. If the Category of the bug is obvious, please fill that in as appropriate.<br />
<br />
You may select a priority, though we ask you to be reasonable in your assessment of the priority with respect to the project and not your personal requirements. If this is a feature that you are willing to work on or a bug that you feel you can handle yourself, you may also assign yourself to the task. We, of course, will then expect you to actually complete any issues assigned to you in that case.<br />
<br />
=== What do the different Status levels mean? ===<br />
<br />
* New: the default assignment when an issue is added and nothing has been done.<br />
* Feedback: the bug is unclear, we don't know what to do, or it needs more discussion.<br />
* Assigned: we know what to do and have given it to some someone to do it.<br />
* Resolved: patch submitted and merged into maint/master/next. We then wait a few weeks to see if it causes any problems or any other feedback.<br />
* Closed: after a few weeks of either positive or no farther issue with the resolution, we officially close it.<br />
<br />
It is the task of the developer assigned to a task to update the issue for ever level except closed. The GNU Radio management team will decide when to officially close an issue.<br />
<br />
=== Assignment ===<br />
<br />
Assignment to an Issue means that an individual has taken on the task of handling that particular issue of either fixing a bug or adding a feature. When assigned, that issue is claimed by the assignee, and so we expect that person to handle the task. Assigned issues that are not kept up on will be either removed or the assignee will be taken off. Removing the issue will generally occur with a feature request where that feature is not being managed properly. If it is a bug, inaction on it means that others may be discouraged from working on this because it is already assigned.<br />
<br />
There are a few categories that have default assignments to someone on the GNU Radio development team. The default assignment should be looked at as a triage operation. When assigned, the default assignee should look at the issue and decide how to handle it. It might be that someone else should be assigned to that task, or if it falls outside of the abilities, availability of time, or other such reasons, the default assignee can remove themselves from the issue thus freeing it up for others to take.<br />
<br />
=== Target Version ===<br />
<br />
Please leave the Target Version field blank until the issue is resolved. We handle this differently in our project than most as we do not build up a list of issues to tackle on a per-release basis.<br />
<br />
== How do I submit patches? ==<br />
<br />
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, you can just create a diff and attach that to the entry to the issue tracker. Please include a description of the bug and how your patch fixes this bug (see above on obtaining permissions to create bug tracker entries.)<br />
<br />
Another easy, very useful (for both you and us) way is to go through github and send us a pull request (See: How can I use github? below).<br />
<br />
In most cases, these are the commands you will enter:<br />
<br />
<pre># You've just finished editing the patch<br />
$ git add FILE1 FILE2... # Put all the patch-relevant files here<br />
$ git commit -m 'filter: re-snazzled the frombobulator (was zingamawonking)'<br />
$ git format-patch HEAD~ # This will turn the latest commit into a patch file</pre><br />
Note that the commit message should be prefixed with the component you changed (core, filter, audio, ...). Read the previous commit logs for examples (you can get them with 'git log').<br />
<br />
The last command creates a file, usually starting with '0001', which contains the patch. Simply upload this to the issue tracker.<br />
<br />
For larger patches (e.g. several commits), it is probably better to upload a modified version of the git repository, e.g. to github (see below).<br /><br />
If you want to extend GNU Radio and add new features, please read 'How can I add new features to GNU Radio?'.<br />
<br />
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'.<br />
<br />
== How can I add new features to GNU Radio? ==<br />
<br />
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.<br />
<br />
Of course some features (say, new modulators or filters) 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 post a 'Feature' on our issue tracker. This is explained greater detail [http://gnuradio.squarespace.com/blog/2010/10/29/using-git-with-github-for-developing.html here] .<br />
<br />
Before submitting, go through the following check list:<br />
<br />
* Does the code include documentation? GNU Radio uses Doxygen for automatic doc generation, so be aware of this when documenting classes.<br />
* Are there unit tests? Are they ''sensible'' unit tests, i.e. do they cover the most common errors?<br />
* Does the patch maintain compatibility with the existing code base?<br />
* Does the code follow the [[coding_guide_impl|GNU Radio coding conventions]]?<br />
* Is the code based on the latest GNU Radio revision?<br />
* Is the code nicely portable?<br />
* Do you have a copyright assignment on file with the FSF?<br />
<br />
If you're having any trouble with this, don't hesitate to ask on the mailing list.<br />
<br />
== How can I use github to submit patches/features/changes? ==<br />
<br />
'''Note:''' This is the recommended way to provide changes to the GNU Radio code.<br />
<br />
Here's the easiest way:<br />
<br />
* [https://help.github.com/articles/fork-a-repo/ Fork] a repository from https://github.com/gnuradio/gnuradio<br />
* Clone your repository or add it as a remote to a previously cloned gnuradio repo:<br />
** $ git remote add <name for your repo> <SSH link to your forked repo><br />
** $ git remote update <name of your repo><br />
* Make a new feature branch -- please make this distinct from maint/master/next<br />
** $ git branch <feature branch name><br />
** $ git checkout <feature branch name><br />
* Commit your changes on your new branch<br />
** $ git commit <files or -a for all changes><br />
* Make sure it compiles, works, and passes QA<br />
** $ make<br />
** $ make test (or ctest)<br />
* [https://help.github.com/articles/using-pull-requests/ Submit a Pull Request] to merge your branch back into the gnuradio/gnuradio repository<br />
* Wait for us to process that<br />
<br />
You need to figure out what the base branch is for you to work off of. Most likely, this will be either maint or master, but it could be next:<br />
<br />
* '''maint:''' our bug patch branch; this will become a bug release against the current version. These are for bugs only; no new features. Any patches made to this branch will also be applied to the master and next branch. This branch becomes the patch version of a release, the p of an X.Y.Z.p (omitted if p=0).<br />
* '''master:''' this will become our next minor version release, the Z of an X.Y.Z version. This is where new code codes that’s more than just a bug patch.<br />
* '''next:''' in the X.Y.Z model, this is the staging area for the Y version increments, also called the API version. All code within a release version has the same compatible API. If you use code in the X.Y API release starting with minor release Z0, then all releases after Z0 in that API version are guaranteed to have the same backwards-compatible API. We put stuff on the next branch when we have to break the API. We try to avoid this whenever possible since API releases are rare and so any code submitted here will not be released for a while.<br />
<br />
Keep in mind that a pull request is not a guaranteed merge on our part. We will vet the code for both correctness, usefulness, and style, and we might push back requesting some changes. There will likely be a bit of back and forth on this, so don't be discouraged; we're just trying to make sure that the code always gets better.<br />
<br />
== Which kind of patches are accepted into GNU Radio? ==<br />
<br />
There is no definitive answer to this. Bug fixes and missing QA codes are of course always welcome.<br />
<br />
Ultimately, the decision lies with the maintainers. If in doubt, consult the mailing list.<br />
<br />
== How long does it take for my patch to become part of GNU Radio? ==<br />
<br />
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.<br />
<br />
However, the following things are guaranteed to delay acceptance:<br />
<br />
'''''' Lack of documentation and/or test cases<br />
<br />
'''''' Not complying with the [[coding_guide_impl|coding conventions]]<br />
<br />
'''''' Non-portable code<br />
<br />
'''''' QA failures<br />
<br />
'''''' Breaking of next (if it was in master)<br />
<br />
'''''' Lack of [[Development#Whats-this-Copyright-Assignment|copyright assignment]]<br />
<br />
== What if my patch works for master, but not for next? ==<br />
<br />
Ideally, you do this:<br />
<br />
# Create a branch off master, say foo-master<br />
# Implement feature or fix on foo-master<br />
# Create a branch off next called foo-next<br />
# Merge foo-master into foo-next, fix up breakage<br />
# Implement feature or fix on foo-next (this might have been done or partially done as a result of getting through #4)<br />
# Tell us about foo-master and foo-next<br />
<br />
Then we:<br />
<br />
# Merge foo-master into master. No problems since foo-master is branched from master.<br />
# Merge foo-next into next. No problems since #4 above already dealt with merge breakage<br />
# Merge master into next. This should end up being a null merge, but it maintains the master-&gt;next linkage<br />
<br />
== What's this CGRAN? ==<br />
<br />
The Comprehensive GNU Radio Archive Network ([http://cgran.org/ 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.<br />
<br />
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.<br />
<br />
== Which coding conventions apply? ==<br />
<br />
All contributions should conform to the [http://www.gnu.org/prep/standards_toc.html GNU Coding Standards] as modified for C++ in README.hacking<br />
<br />
Also, you should check out [[Coding_guide_impl|The GNU Radio Coding Style Guide]].<br />
<br />
== How is the code documented? ==<br />
<br />
GNU Radio uses [http://www.stack.nl/~dimitri/doxygen 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 <code>docs/doxygen/other/group_defs.dox</code>. Below is an example of a marked-up header file.<br />
<br />
<pre>/*!<br />
* \brief A new block that does something.<br />
* \ingroup some_group<br />
* \ingroup another_group<br />
*<br />
* Detailed description of what this block does.<br />
* Quoting papers or textbooks is a good idea, too.<br />
*/<br />
class MODNAME_API new_block : public gr::block<br />
{<br />
private:<br />
new_block(int param1, double param2);<br />
<br />
public:<br />
typedef boost::shared_ptr sptr;<br />
<br />
/*!<br />
* \brief Description of public_function()<br />
* \param foo Describe foo<br />
* \param bar Describe bar<br />
*/<br />
virtual int public_function(int foo, float bar) = 0;<br />
<br />
/*!<br />
* \param param1 Describe param1<br />
* \param param2 Describe param2<br />
*/<br />
static sptr make(int param1, double param2);<br />
<br />
};</pre><br />
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 <code>docs/doxygen/other/main_page.dox</code>.<br />
<br />
The top level blocks are all described inside that blocks <code>doc</code> directory in a <code>.dox</code> files named or the component. For example, in the component <code>gr-digital</code>, the manual page describing this component is in <code>gr-digital/doc/digital.dox</code>. 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.<br />
<br />
The component's <code>doc</code> directory will also contain a <code>README.package</code> 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.<br />
<br />
=== Doxygen Markup for Formulas ===<br />
<br />
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 &quot;\f{&quot; to begin and &quot;\f}&quot; 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:<br />
<br />
<pre>This is some text in the header...<br />
\f{html}{<br />
enter Latex formula here -&gt; will only show up in the HTML document.<br />
}<br />
<br />
\xmlonly<br />
Same Latex formula, but this will not be processed; will only be the raw Latex formula.<br />
\endxmlonly<br />
<br />
And here's some following text to the formulas.</pre><br />
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 &quot;\ f&quot;.<br />
<br />
== What's this Copyright Assignment? ==<br />
<br />
Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the [http://www.fsf.org/ FSF]. A description of the process is available [http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html here]. Basically, this guarantees the FSF (who is copyright holder of GNU Radio) does not run into any legal trouble somewhere down the road.<br />
<br />
This boils down to the following instructions:<br />
<br />
'''''' If you've developed some addition or patch to GNU Radio that you would like to contribute, you should send an email to the mailing list, or to one of the GNU Radio maintainers asking for an appropriate form. We might ask you for some more information at this point.<br />
<br />
'''''' You will be sent a short form by email which you should fill in and email back to the FSF.<br />
<br />
'''''' Once the FSF have received this email, they will send you a paper copy of the full copyright assignment papers for you to sign and post back to them.<br />
<br />
'''''' As soon as the signed paperwork is filed at the FSF we can accept your changes into the source tree.<br />
<br />
'''''' Individual small changes (fewer than 10 lines of code) can, however, be accepted without a copyright assignment form on file.<br />
<br />
In order to get the process rolling, please email &quot;tom AT trondeau&quot; for a form to start the copyright process.<br />
<br />
== Who maintains GNU Radio? ==<br />
<br />
GNU Radio is currently maintained by:<br />
<br />
* [https://github.com/bhilburn Ben Hilburn] (Project Lead) and<br />
* [http://corganlabs.com Johnathan Corgan] (Chief Architect) and<br />
* Nathan West (Release Manager) and<br />
* Martin Braun (Community Manager)<br />
<br />
See also the [[Organization|full list of GNU Radio staff]].<br />
<br />
GNU Radio was founded and initially maintained by:<br />
<br />
* [http://www.comsec.com Eric Blossom]</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=Development&diff=637Development2017-03-20T06:38:26Z<p>Bastibl: /* How can I help? */</p>
<hr />
<div>= Contributing to GNU Radio -- FAQ =<br />
<br />
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.<br />
<br />
== Cheat Sheet ==<br />
<br />
See the information throughout this page for details about these steps. But when making looking to contribute, we encourage you to either make a new Issue in the Issue Tracker or identify a current Issue already up and waiting for attention. We also assume you have a public Github repo you can use for the pull requests and that you have cloned the GNU Radio git repo.<br />
<br />
* Identify which branch of the GNU Radio base code to work from.<br />
* Create a new branch from here to work from.<br />
* Work on the bug fix or feature under the new branch.<br />
* Determine the QA code necessary to test and check the fix or feature.<br />
* Provide an appropriate Git commit with log messages.<br />
* Push the branch to a public repo on Github.<br />
* Issue a pull request against the starting branch (i.e., maint or master).<br />
* Update the Issue on [https://gnuradio.org gnuradio.org] with information about the fix, including a link to the pull request on Github.<br />
* Wait for the pull request to be merged -- often after some back and forth and testing by other parties.<br />
* Mark the Issue resolved and note the commit where it was resolved.<br />
<br />
The GNU Radio project maintainers will mark issues as Closed at the appropriate time.<br />
<br />
== How can I help? ==<br />
<br />
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.<br />
<br />
If you want to get involved in the development process, here's some suggestions where to start:<br />
<br />
* Documentation<br />
* Missing test cases<br />
* Bug fixes<br />
* GUIs<br />
<br />
The main place to look is the issue tracker. Also, look at the results posted by our Jenkins continuous integration service: http://jenkins.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.<br />
<br />
We also use Coverity for static code analysis. You can find our project at https://scan.coverity.com/projects. Here, you can find small things to change and fix (a lot of these are so small you don't even need an FSF copyright assignment).<br />
<br />
There's also the possibility to [https://crm.fsf.org/civicrm/contribute/transact?reset=1&id=16 donate] to our project. The Free Software Foundation provides the infrastructure to do so, and can provide a receipt for US tax payers, who can deduct a donation.<br />
<br />
== Development Style ==<br />
<br />
When writing new code, we have a few general rules for where and how things go in. We follow that standard [http://schacon.github.com/git/gitworkflows.html 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.<br />
<br />
* Make sure any changes in 'master' do not break the API (even if there is an error)<br />
** Additions to the API are fine<br />
** Deprecating code by outputting a message is done here<br />
* Removing code or changing API names or calling conventions MUST be done in 'next'<br />
* Work in 'master' for as much as possible unless you are going to change the API<br />
<br />
Following these simple rules will help get your code merged in faster and with less hassle.<br />
<br />
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:<br />
<br />
* Use TODO comments for low-priority fixes<br />
* Use FIXME comments for high-priority fixes<br />
<br />
For all kinds of modifications and changes, try and make sure the following points are observed:<br />
<br />
* 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.<br />
* Diffs are made from the GNU Radio tree root, and are based on an recent master branch.<br />
** use [http://schacon.github.com/git/git-format-patch.html git format-patch] to create your patches.<br />
** Minor bug fixes should be applied to the maint branch<br />
** Addon's and features should be applied to the master branch<br />
** Changes to the structure, API, or other surgery to the code should be applied to the next branch<br />
* After applying your changes or building your branch, the command 'make test' must pass.<br />
* There should be no additional compiler warnings to what already occurs.<br />
* No gratuitous whitespace changes.<br />
<br />
=== Quality Assurance (QA) Code ===<br />
<br />
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.<br />
<br />
Any block that is currently without a QA testing program should be fixed to have one.<br />
<br />
== I've found a bug, but I don't have the skill/time/whatever to fix it... now what? ==<br />
<br />
No problem. If it's really an unfixed bug, you're perhaps the first to stumble upon it. Write an email to the discuss-gnuradio@gnu.org mailing list explaining what's wrong and, ideally, providing a test case so the developers can reproduce the error.<br />
<br />
If it's a confirmed bug, you should add a ticket to the bug tracker (http://gnuradio.org/redmine/projects/gnuradio/issues) by following these steps:<br />
<br />
1. You'll need to login to the website, first, and then click New Issue.<br /><br />
2. Set if this Issue is a bug or perhaps a new feature.<br /><br />
3. Provide an appropriate subject to explain the Issue.<br /><br />
4. Provide a comprehensive description of the Issue. Provide links, code, and any examples here. It's much easier for us to understand a bug if we have a simple test case that demonstrates the issue such as a GRC file or Python program. Feel free to upload attachments using the Files button.<br /><br />
5. The rest of the attributes of the Issue should be left alone. The GNU Radio development team will handle assignment of the bug and any other relevant attributes.<br />
<br />
=== I've fixed and Issue! What do I do now? ===<br />
<br />
That's fantastic! Thanks! To help us provide a consistent experience resolving and fixing issues, please follow these steps.<br />
<br />
1. Create a patch. See the next set of instructions on &quot;How do I submit patches?&quot;. If you have a patch file, you can attach it to the Issue directly or use a pull request through github.com.<br /><br />
2. Update the Issue that you're addressing by setting the Issue status to Feedback and a description of the update, such as the github branch or pull request number.<br /><br />
3. Set the Resolution field to Fixed.<br />
<br />
The GNU Radio development team will take the issue from here. We will handle applying or merging the fix and updating the issue from there. We will set the Status to Resolved and set the target version it belongs to. After a week or so without incident, we will close the Issue.<br />
<br />
See the next section for how to work with our Issue Tracker.<br />
<br />
== Dealing with the GNU Radio Issue Tracker ==<br />
<br />
If you are filing a new bug or feature request, here's what you need to know. First, you'll need an account on gnuradio.org. Sign up for that and make sure you can log in; if you have trouble logging in, contact Tom Rondeau for help with your account.<br />
<br />
Once logged in, you will see the New Issue option right next to Issues. Clicking that will take you to the page to enter the issue you wish to file. First select if this is a bug or a feature and provide a subject line describing it. Fill out the description as clearly as possible to describe the bug or feature. If it's a bug, it is most helpful to us if you would also attached an example application that exercises the bug so that we can easily test it. Add a file by looking below to the Files item and select the button &quot;Choose Files&quot;.<br />
<br />
The rest of the fields are mostly left alone by the initial filer. The GNU Radio team will take a look at the issue and fill in the appropriate fields from there. If the Category of the bug is obvious, please fill that in as appropriate.<br />
<br />
You may select a priority, though we ask you to be reasonable in your assessment of the priority with respect to the project and not your personal requirements. If this is a feature that you are willing to work on or a bug that you feel you can handle yourself, you may also assign yourself to the task. We, of course, will then expect you to actually complete any issues assigned to you in that case.<br />
<br />
=== What do the different Status levels mean? ===<br />
<br />
* New: the default assignment when an issue is added and nothing has been done.<br />
* Feedback: the bug is unclear, we don't know what to do, or it needs more discussion.<br />
* Assigned: we know what to do and have given it to some someone to do it.<br />
* Resolved: patch submitted and merged into maint/master/next. We then wait a few weeks to see if it causes any problems or any other feedback.<br />
* Closed: after a few weeks of either positive or no farther issue with the resolution, we officially close it.<br />
<br />
It is the task of the developer assigned to a task to update the issue for ever level except closed. The GNU Radio management team will decide when to officially close an issue.<br />
<br />
=== Assignment ===<br />
<br />
Assignment to an Issue means that an individual has taken on the task of handling that particular issue of either fixing a bug or adding a feature. When assigned, that issue is claimed by the assignee, and so we expect that person to handle the task. Assigned issues that are not kept up on will be either removed or the assignee will be taken off. Removing the issue will generally occur with a feature request where that feature is not being managed properly. If it is a bug, inaction on it means that others may be discouraged from working on this because it is already assigned.<br />
<br />
There are a few categories that have default assignments to someone on the GNU Radio development team. The default assignment should be looked at as a triage operation. When assigned, the default assignee should look at the issue and decide how to handle it. It might be that someone else should be assigned to that task, or if it falls outside of the abilities, availability of time, or other such reasons, the default assignee can remove themselves from the issue thus freeing it up for others to take.<br />
<br />
=== Target Version ===<br />
<br />
Please leave the Target Version field blank until the issue is resolved. We handle this differently in our project than most as we do not build up a list of issues to tackle on a per-release basis.<br />
<br />
== How do I submit patches? ==<br />
<br />
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, you can just create a diff and attach that to the entry to the issue tracker. Please include a description of the bug and how your patch fixes this bug (see above on obtaining permissions to create bug tracker entries.)<br />
<br />
Another easy, very useful (for both you and us) way is to go through github and send us a pull request (See: How can I use github? below).<br />
<br />
In most cases, these are the commands you will enter:<br />
<br />
<pre># You've just finished editing the patch<br />
$ git add FILE1 FILE2... # Put all the patch-relevant files here<br />
$ git commit -m 'filter: re-snazzled the frombobulator (was zingamawonking)'<br />
$ git format-patch HEAD~ # This will turn the latest commit into a patch file</pre><br />
Note that the commit message should be prefixed with the component you changed (core, filter, audio, ...). Read the previous commit logs for examples (you can get them with 'git log').<br />
<br />
The last command creates a file, usually starting with '0001', which contains the patch. Simply upload this to the issue tracker.<br />
<br />
For larger patches (e.g. several commits), it is probably better to upload a modified version of the git repository, e.g. to github (see below).<br /><br />
If you want to extend GNU Radio and add new features, please read 'How can I add new features to GNU Radio?'.<br />
<br />
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'.<br />
<br />
== How can I add new features to GNU Radio? ==<br />
<br />
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.<br />
<br />
Of course some features (say, new modulators or filters) 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 post a 'Feature' on our issue tracker. This is explained greater detail [http://gnuradio.squarespace.com/blog/2010/10/29/using-git-with-github-for-developing.html here] .<br />
<br />
Before submitting, go through the following check list:<br />
<br />
'''''' Does the code include documentation? GNU Radio uses Doxygen for automatic doc generation, so be aware of this when documenting classes.<br />
<br />
'''''' Are there unit tests? Are they ''sensible'' unit tests, i.e. do they cover the most common errors?<br />
<br />
'''''' Does the patch maintain compatibility with the existing code base?<br />
<br />
'''''' Does the code follow the [[coding_guide_impl|GNU Radio coding conventions]]?<br />
<br />
'''''' Is the code based on the latest GNU Radio revision?<br />
<br />
'''''' Is the code nicely portable?<br />
<br />
'''''' Do you have a copyright assignment on file with the FSF?<br />
<br />
If you're having any trouble with this, don't hesitate to ask on the mailing list.<br />
<br />
== How can I use github to submit patches/features/changes? ==<br />
<br />
'''Note:''' This is the recommended way to provide changes to the GNU Radio code.<br />
<br />
Here's the easiest way:<br />
<br />
* [https://help.github.com/articles/fork-a-repo/ Fork] a repository from https://github.com/gnuradio/gnuradio<br />
* Clone your repository or add it as a remote to a previously cloned gnuradio repo:<br />
** $ git remote add <name for your repo> <SSH link to your forked repo><br />
** $ git remote update <name of your repo><br />
* Make a new feature branch -- please make this distinct from maint/master/next<br />
** $ git branch <feature branch name><br />
** $ git checkout <feature branch name><br />
* Commit your changes on your new branch<br />
** $ git commit <files or -a for all changes><br />
* Make sure it compiles, works, and passes QA<br />
** $ make<br />
** $ make test (or ctest)<br />
* [https://help.github.com/articles/using-pull-requests/ Submit a Pull Request] to merge your branch back into the gnuradio/gnuradio repository<br />
* Wait for us to process that<br />
<br />
You need to figure out what the base branch is for you to work off of. Most likely, this will be either maint or master, but it could be next:<br />
<br />
* '''maint:''' our bug patch branch; this will become a bug release against the current version. These are for bugs only; no new features. Any patches made to this branch will also be applied to the master and next branch. This branch becomes the patch version of a release, the p of an X.Y.Z.p (omitted if p=0).<br />
* '''master:''' this will become our next minor version release, the Z of an X.Y.Z version. This is where new code codes that’s more than just a bug patch.<br />
* '''next:''' in the X.Y.Z model, this is the staging area for the Y version increments, also called the API version. All code within a release version has the same compatible API. If you use code in the X.Y API release starting with minor release Z0, then all releases after Z0 in that API version are guaranteed to have the same backwards-compatible API. We put stuff on the next branch when we have to break the API. We try to avoid this whenever possible since API releases are rare and so any code submitted here will not be released for a while.<br />
<br />
Keep in mind that a pull request is not a guaranteed merge on our part. We will vet the code for both correctness, usefulness, and style, and we might push back requesting some changes. There will likely be a bit of back and forth on this, so don't be discouraged; we're just trying to make sure that the code always gets better.<br />
<br />
== Which kind of patches are accepted into GNU Radio? ==<br />
<br />
There is no definitive answer to this. Bug fixes and missing QA codes are of course always welcome.<br />
<br />
Ultimately, the decision lies with the maintainers. If in doubt, consult the mailing list.<br />
<br />
== How long does it take for my patch to become part of GNU Radio? ==<br />
<br />
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.<br />
<br />
However, the following things are guaranteed to delay acceptance:<br />
<br />
'''''' Lack of documentation and/or test cases<br />
<br />
'''''' Not complying with the [[coding_guide_impl|coding conventions]]<br />
<br />
'''''' Non-portable code<br />
<br />
'''''' QA failures<br />
<br />
'''''' Breaking of next (if it was in master)<br />
<br />
'''''' Lack of [[Development#Whats-this-Copyright-Assignment|copyright assignment]]<br />
<br />
== What if my patch works for master, but not for next? ==<br />
<br />
Ideally, you do this:<br />
<br />
# Create a branch off master, say foo-master<br />
# Implement feature or fix on foo-master<br />
# Create a branch off next called foo-next<br />
# Merge foo-master into foo-next, fix up breakage<br />
# Implement feature or fix on foo-next (this might have been done or partially done as a result of getting through #4)<br />
# Tell us about foo-master and foo-next<br />
<br />
Then we:<br />
<br />
# Merge foo-master into master. No problems since foo-master is branched from master.<br />
# Merge foo-next into next. No problems since #4 above already dealt with merge breakage<br />
# Merge master into next. This should end up being a null merge, but it maintains the master-&gt;next linkage<br />
<br />
== What's this CGRAN? ==<br />
<br />
The Comprehensive GNU Radio Archive Network ([http://cgran.org/ 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.<br />
<br />
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.<br />
<br />
== Which coding conventions apply? ==<br />
<br />
All contributions should conform to the [http://www.gnu.org/prep/standards_toc.html GNU Coding Standards] as modified for C++ in README.hacking<br />
<br />
Also, you should check out [[Coding_guide_impl|The GNU Radio Coding Style Guide]].<br />
<br />
== How is the code documented? ==<br />
<br />
GNU Radio uses [http://www.stack.nl/~dimitri/doxygen 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 <code>docs/doxygen/other/group_defs.dox</code>. Below is an example of a marked-up header file.<br />
<br />
<pre>/*!<br />
* \brief A new block that does something.<br />
* \ingroup some_group<br />
* \ingroup another_group<br />
*<br />
* Detailed description of what this block does.<br />
* Quoting papers or textbooks is a good idea, too.<br />
*/<br />
class MODNAME_API new_block : public gr::block<br />
{<br />
private:<br />
new_block(int param1, double param2);<br />
<br />
public:<br />
typedef boost::shared_ptr sptr;<br />
<br />
/*!<br />
* \brief Description of public_function()<br />
* \param foo Describe foo<br />
* \param bar Describe bar<br />
*/<br />
virtual int public_function(int foo, float bar) = 0;<br />
<br />
/*!<br />
* \param param1 Describe param1<br />
* \param param2 Describe param2<br />
*/<br />
static sptr make(int param1, double param2);<br />
<br />
};</pre><br />
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 <code>docs/doxygen/other/main_page.dox</code>.<br />
<br />
The top level blocks are all described inside that blocks <code>doc</code> directory in a <code>.dox</code> files named or the component. For example, in the component <code>gr-digital</code>, the manual page describing this component is in <code>gr-digital/doc/digital.dox</code>. 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.<br />
<br />
The component's <code>doc</code> directory will also contain a <code>README.package</code> 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.<br />
<br />
=== Doxygen Markup for Formulas ===<br />
<br />
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 &quot;\f{&quot; to begin and &quot;\f}&quot; 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:<br />
<br />
<pre>This is some text in the header...<br />
\f{html}{<br />
enter Latex formula here -&gt; will only show up in the HTML document.<br />
}<br />
<br />
\xmlonly<br />
Same Latex formula, but this will not be processed; will only be the raw Latex formula.<br />
\endxmlonly<br />
<br />
And here's some following text to the formulas.</pre><br />
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 &quot;\ f&quot;.<br />
<br />
== What's this Copyright Assignment? ==<br />
<br />
Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the [http://www.fsf.org/ FSF]. A description of the process is available [http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html here]. Basically, this guarantees the FSF (who is copyright holder of GNU Radio) does not run into any legal trouble somewhere down the road.<br />
<br />
This boils down to the following instructions:<br />
<br />
'''''' If you've developed some addition or patch to GNU Radio that you would like to contribute, you should send an email to the mailing list, or to one of the GNU Radio maintainers asking for an appropriate form. We might ask you for some more information at this point.<br />
<br />
'''''' You will be sent a short form by email which you should fill in and email back to the FSF.<br />
<br />
'''''' Once the FSF have received this email, they will send you a paper copy of the full copyright assignment papers for you to sign and post back to them.<br />
<br />
'''''' As soon as the signed paperwork is filed at the FSF we can accept your changes into the source tree.<br />
<br />
'''''' Individual small changes (fewer than 10 lines of code) can, however, be accepted without a copyright assignment form on file.<br />
<br />
In order to get the process rolling, please email &quot;tom AT trondeau&quot; for a form to start the copyright process.<br />
<br />
== Who maintains GNU Radio? ==<br />
<br />
GNU Radio is currently maintained by:<br />
<br />
* [https://github.com/bhilburn Ben Hilburn] (Project Lead) and<br />
* [http://corganlabs.com Johnathan Corgan] (Chief Architect) and<br />
* Nathan West (Release Manager) and<br />
* Martin Braun (Community Manager)<br />
<br />
See also the [[Organization|full list of GNU Radio staff]].<br />
<br />
GNU Radio was founded and initially maintained by:<br />
<br />
* [http://www.comsec.com Eric Blossom]</div>Bastiblhttps://wiki.gnuradio.org/index.php?title=Development&diff=636Development2017-03-20T06:33:12Z<p>Bastibl: /* Cheat Sheet */</p>
<hr />
<div>= Contributing to GNU Radio -- FAQ =<br />
<br />
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.<br />
<br />
== Cheat Sheet ==<br />
<br />
See the information throughout this page for details about these steps. But when making looking to contribute, we encourage you to either make a new Issue in the Issue Tracker or identify a current Issue already up and waiting for attention. We also assume you have a public Github repo you can use for the pull requests and that you have cloned the GNU Radio git repo.<br />
<br />
* Identify which branch of the GNU Radio base code to work from.<br />
* Create a new branch from here to work from.<br />
* Work on the bug fix or feature under the new branch.<br />
* Determine the QA code necessary to test and check the fix or feature.<br />
* Provide an appropriate Git commit with log messages.<br />
* Push the branch to a public repo on Github.<br />
* Issue a pull request against the starting branch (i.e., maint or master).<br />
* Update the Issue on [https://gnuradio.org gnuradio.org] with information about the fix, including a link to the pull request on Github.<br />
* Wait for the pull request to be merged -- often after some back and forth and testing by other parties.<br />
* Mark the Issue resolved and note the commit where it was resolved.<br />
<br />
The GNU Radio project maintainers will mark issues as Closed at the appropriate time.<br />
<br />
== How can I help? ==<br />
<br />
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.<br />
<br />
If you want to get involved in the development process, here's some suggestions where to start:<br />
<br />
'''''' Documentation<br />
<br />
'''''' Missing test cases<br />
<br />
'''''' Bug fixes<br />
<br />
'''''' GUIs<br />
<br />
The main place to look is the issue tracker. Also, look at the results posted by our Jenkins continuous integration service: http://jenkins.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.<br />
<br />
We also use Coverity for static code analysis. You can find our project at https://scan.coverity.com/projects. Here, you can find small things to change and fix (a lot of these are so small you don't even need an FSF copyright assignment).<br />
<br />
There's also the possibility to [https://crm.fsf.org/civicrm/contribute/transact?reset=1&id=16 donate] to our project. The Free Software Foundation provides the infrastructure to do so, and can provide a receipt for US tax payers, who can deduct a donation.<br />
<br />
== Development Style ==<br />
<br />
When writing new code, we have a few general rules for where and how things go in. We follow that standard [http://schacon.github.com/git/gitworkflows.html 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.<br />
<br />
* Make sure any changes in 'master' do not break the API (even if there is an error)<br />
** Additions to the API are fine<br />
** Deprecating code by outputting a message is done here<br />
* Removing code or changing API names or calling conventions MUST be done in 'next'<br />
* Work in 'master' for as much as possible unless you are going to change the API<br />
<br />
Following these simple rules will help get your code merged in faster and with less hassle.<br />
<br />
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:<br />
<br />
* Use TODO comments for low-priority fixes<br />
* Use FIXME comments for high-priority fixes<br />
<br />
For all kinds of modifications and changes, try and make sure the following points are observed:<br />
<br />
* 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.<br />
* Diffs are made from the GNU Radio tree root, and are based on an recent master branch.<br />
** use [http://schacon.github.com/git/git-format-patch.html git format-patch] to create your patches.<br />
** Minor bug fixes should be applied to the maint branch<br />
** Addon's and features should be applied to the master branch<br />
** Changes to the structure, API, or other surgery to the code should be applied to the next branch<br />
* After applying your changes or building your branch, the command 'make test' must pass.<br />
* There should be no additional compiler warnings to what already occurs.<br />
* No gratuitous whitespace changes.<br />
<br />
=== Quality Assurance (QA) Code ===<br />
<br />
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.<br />
<br />
Any block that is currently without a QA testing program should be fixed to have one.<br />
<br />
== I've found a bug, but I don't have the skill/time/whatever to fix it... now what? ==<br />
<br />
No problem. If it's really an unfixed bug, you're perhaps the first to stumble upon it. Write an email to the discuss-gnuradio@gnu.org mailing list explaining what's wrong and, ideally, providing a test case so the developers can reproduce the error.<br />
<br />
If it's a confirmed bug, you should add a ticket to the bug tracker (http://gnuradio.org/redmine/projects/gnuradio/issues) by following these steps:<br />
<br />
1. You'll need to login to the website, first, and then click New Issue.<br /><br />
2. Set if this Issue is a bug or perhaps a new feature.<br /><br />
3. Provide an appropriate subject to explain the Issue.<br /><br />
4. Provide a comprehensive description of the Issue. Provide links, code, and any examples here. It's much easier for us to understand a bug if we have a simple test case that demonstrates the issue such as a GRC file or Python program. Feel free to upload attachments using the Files button.<br /><br />
5. The rest of the attributes of the Issue should be left alone. The GNU Radio development team will handle assignment of the bug and any other relevant attributes.<br />
<br />
=== I've fixed and Issue! What do I do now? ===<br />
<br />
That's fantastic! Thanks! To help us provide a consistent experience resolving and fixing issues, please follow these steps.<br />
<br />
1. Create a patch. See the next set of instructions on &quot;How do I submit patches?&quot;. If you have a patch file, you can attach it to the Issue directly or use a pull request through github.com.<br /><br />
2. Update the Issue that you're addressing by setting the Issue status to Feedback and a description of the update, such as the github branch or pull request number.<br /><br />
3. Set the Resolution field to Fixed.<br />
<br />
The GNU Radio development team will take the issue from here. We will handle applying or merging the fix and updating the issue from there. We will set the Status to Resolved and set the target version it belongs to. After a week or so without incident, we will close the Issue.<br />
<br />
See the next section for how to work with our Issue Tracker.<br />
<br />
== Dealing with the GNU Radio Issue Tracker ==<br />
<br />
If you are filing a new bug or feature request, here's what you need to know. First, you'll need an account on gnuradio.org. Sign up for that and make sure you can log in; if you have trouble logging in, contact Tom Rondeau for help with your account.<br />
<br />
Once logged in, you will see the New Issue option right next to Issues. Clicking that will take you to the page to enter the issue you wish to file. First select if this is a bug or a feature and provide a subject line describing it. Fill out the description as clearly as possible to describe the bug or feature. If it's a bug, it is most helpful to us if you would also attached an example application that exercises the bug so that we can easily test it. Add a file by looking below to the Files item and select the button &quot;Choose Files&quot;.<br />
<br />
The rest of the fields are mostly left alone by the initial filer. The GNU Radio team will take a look at the issue and fill in the appropriate fields from there. If the Category of the bug is obvious, please fill that in as appropriate.<br />
<br />
You may select a priority, though we ask you to be reasonable in your assessment of the priority with respect to the project and not your personal requirements. If this is a feature that you are willing to work on or a bug that you feel you can handle yourself, you may also assign yourself to the task. We, of course, will then expect you to actually complete any issues assigned to you in that case.<br />
<br />
=== What do the different Status levels mean? ===<br />
<br />
* New: the default assignment when an issue is added and nothing has been done.<br />
* Feedback: the bug is unclear, we don't know what to do, or it needs more discussion.<br />
* Assigned: we know what to do and have given it to some someone to do it.<br />
* Resolved: patch submitted and merged into maint/master/next. We then wait a few weeks to see if it causes any problems or any other feedback.<br />
* Closed: after a few weeks of either positive or no farther issue with the resolution, we officially close it.<br />
<br />
It is the task of the developer assigned to a task to update the issue for ever level except closed. The GNU Radio management team will decide when to officially close an issue.<br />
<br />
=== Assignment ===<br />
<br />
Assignment to an Issue means that an individual has taken on the task of handling that particular issue of either fixing a bug or adding a feature. When assigned, that issue is claimed by the assignee, and so we expect that person to handle the task. Assigned issues that are not kept up on will be either removed or the assignee will be taken off. Removing the issue will generally occur with a feature request where that feature is not being managed properly. If it is a bug, inaction on it means that others may be discouraged from working on this because it is already assigned.<br />
<br />
There are a few categories that have default assignments to someone on the GNU Radio development team. The default assignment should be looked at as a triage operation. When assigned, the default assignee should look at the issue and decide how to handle it. It might be that someone else should be assigned to that task, or if it falls outside of the abilities, availability of time, or other such reasons, the default assignee can remove themselves from the issue thus freeing it up for others to take.<br />
<br />
=== Target Version ===<br />
<br />
Please leave the Target Version field blank until the issue is resolved. We handle this differently in our project than most as we do not build up a list of issues to tackle on a per-release basis.<br />
<br />
== How do I submit patches? ==<br />
<br />
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, you can just create a diff and attach that to the entry to the issue tracker. Please include a description of the bug and how your patch fixes this bug (see above on obtaining permissions to create bug tracker entries.)<br />
<br />
Another easy, very useful (for both you and us) way is to go through github and send us a pull request (See: How can I use github? below).<br />
<br />
In most cases, these are the commands you will enter:<br />
<br />
<pre># You've just finished editing the patch<br />
$ git add FILE1 FILE2... # Put all the patch-relevant files here<br />
$ git commit -m 'filter: re-snazzled the frombobulator (was zingamawonking)'<br />
$ git format-patch HEAD~ # This will turn the latest commit into a patch file</pre><br />
Note that the commit message should be prefixed with the component you changed (core, filter, audio, ...). Read the previous commit logs for examples (you can get them with 'git log').<br />
<br />
The last command creates a file, usually starting with '0001', which contains the patch. Simply upload this to the issue tracker.<br />
<br />
For larger patches (e.g. several commits), it is probably better to upload a modified version of the git repository, e.g. to github (see below).<br /><br />
If you want to extend GNU Radio and add new features, please read 'How can I add new features to GNU Radio?'.<br />
<br />
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'.<br />
<br />
== How can I add new features to GNU Radio? ==<br />
<br />
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.<br />
<br />
Of course some features (say, new modulators or filters) 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 post a 'Feature' on our issue tracker. This is explained greater detail [http://gnuradio.squarespace.com/blog/2010/10/29/using-git-with-github-for-developing.html here] .<br />
<br />
Before submitting, go through the following check list:<br />
<br />
'''''' Does the code include documentation? GNU Radio uses Doxygen for automatic doc generation, so be aware of this when documenting classes.<br />
<br />
'''''' Are there unit tests? Are they ''sensible'' unit tests, i.e. do they cover the most common errors?<br />
<br />
'''''' Does the patch maintain compatibility with the existing code base?<br />
<br />
'''''' Does the code follow the [[coding_guide_impl|GNU Radio coding conventions]]?<br />
<br />
'''''' Is the code based on the latest GNU Radio revision?<br />
<br />
'''''' Is the code nicely portable?<br />
<br />
'''''' Do you have a copyright assignment on file with the FSF?<br />
<br />
If you're having any trouble with this, don't hesitate to ask on the mailing list.<br />
<br />
== How can I use github to submit patches/features/changes? ==<br />
<br />
'''Note:''' This is the recommended way to provide changes to the GNU Radio code.<br />
<br />
Here's the easiest way:<br />
<br />
* [https://help.github.com/articles/fork-a-repo/ Fork] a repository from https://github.com/gnuradio/gnuradio<br />
* Clone your repository or add it as a remote to a previously cloned gnuradio repo:<br />
** $ git remote add <name for your repo> <SSH link to your forked repo><br />
** $ git remote update <name of your repo><br />
* Make a new feature branch -- please make this distinct from maint/master/next<br />
** $ git branch <feature branch name><br />
** $ git checkout <feature branch name><br />
* Commit your changes on your new branch<br />
** $ git commit <files or -a for all changes><br />
* Make sure it compiles, works, and passes QA<br />
** $ make<br />
** $ make test (or ctest)<br />
* [https://help.github.com/articles/using-pull-requests/ Submit a Pull Request] to merge your branch back into the gnuradio/gnuradio repository<br />
* Wait for us to process that<br />
<br />
You need to figure out what the base branch is for you to work off of. Most likely, this will be either maint or master, but it could be next:<br />
<br />
* '''maint:''' our bug patch branch; this will become a bug release against the current version. These are for bugs only; no new features. Any patches made to this branch will also be applied to the master and next branch. This branch becomes the patch version of a release, the p of an X.Y.Z.p (omitted if p=0).<br />
* '''master:''' this will become our next minor version release, the Z of an X.Y.Z version. This is where new code codes that’s more than just a bug patch.<br />
* '''next:''' in the X.Y.Z model, this is the staging area for the Y version increments, also called the API version. All code within a release version has the same compatible API. If you use code in the X.Y API release starting with minor release Z0, then all releases after Z0 in that API version are guaranteed to have the same backwards-compatible API. We put stuff on the next branch when we have to break the API. We try to avoid this whenever possible since API releases are rare and so any code submitted here will not be released for a while.<br />
<br />
Keep in mind that a pull request is not a guaranteed merge on our part. We will vet the code for both correctness, usefulness, and style, and we might push back requesting some changes. There will likely be a bit of back and forth on this, so don't be discouraged; we're just trying to make sure that the code always gets better.<br />
<br />
== Which kind of patches are accepted into GNU Radio? ==<br />
<br />
There is no definitive answer to this. Bug fixes and missing QA codes are of course always welcome.<br />
<br />
Ultimately, the decision lies with the maintainers. If in doubt, consult the mailing list.<br />
<br />
== How long does it take for my patch to become part of GNU Radio? ==<br />
<br />
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.<br />
<br />
However, the following things are guaranteed to delay acceptance:<br />
<br />
'''''' Lack of documentation and/or test cases<br />
<br />
'''''' Not complying with the [[coding_guide_impl|coding conventions]]<br />
<br />
'''''' Non-portable code<br />
<br />
'''''' QA failures<br />
<br />
'''''' Breaking of next (if it was in master)<br />
<br />
'''''' Lack of [[Development#Whats-this-Copyright-Assignment|copyright assignment]]<br />
<br />
== What if my patch works for master, but not for next? ==<br />
<br />
Ideally, you do this:<br />
<br />
# Create a branch off master, say foo-master<br />
# Implement feature or fix on foo-master<br />
# Create a branch off next called foo-next<br />
# Merge foo-master into foo-next, fix up breakage<br />
# Implement feature or fix on foo-next (this might have been done or partially done as a result of getting through #4)<br />
# Tell us about foo-master and foo-next<br />
<br />
Then we:<br />
<br />
# Merge foo-master into master. No problems since foo-master is branched from master.<br />
# Merge foo-next into next. No problems since #4 above already dealt with merge breakage<br />
# Merge master into next. This should end up being a null merge, but it maintains the master-&gt;next linkage<br />
<br />
== What's this CGRAN? ==<br />
<br />
The Comprehensive GNU Radio Archive Network ([http://cgran.org/ 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.<br />
<br />
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.<br />
<br />
== Which coding conventions apply? ==<br />
<br />
All contributions should conform to the [http://www.gnu.org/prep/standards_toc.html GNU Coding Standards] as modified for C++ in README.hacking<br />
<br />
Also, you should check out [[Coding_guide_impl|The GNU Radio Coding Style Guide]].<br />
<br />
== How is the code documented? ==<br />
<br />
GNU Radio uses [http://www.stack.nl/~dimitri/doxygen 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 <code>docs/doxygen/other/group_defs.dox</code>. Below is an example of a marked-up header file.<br />
<br />
<pre>/*!<br />
* \brief A new block that does something.<br />
* \ingroup some_group<br />
* \ingroup another_group<br />
*<br />
* Detailed description of what this block does.<br />
* Quoting papers or textbooks is a good idea, too.<br />
*/<br />
class MODNAME_API new_block : public gr::block<br />
{<br />
private:<br />
new_block(int param1, double param2);<br />
<br />
public:<br />
typedef boost::shared_ptr sptr;<br />
<br />
/*!<br />
* \brief Description of public_function()<br />
* \param foo Describe foo<br />
* \param bar Describe bar<br />
*/<br />
virtual int public_function(int foo, float bar) = 0;<br />
<br />
/*!<br />
* \param param1 Describe param1<br />
* \param param2 Describe param2<br />
*/<br />
static sptr make(int param1, double param2);<br />
<br />
};</pre><br />
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 <code>docs/doxygen/other/main_page.dox</code>.<br />
<br />
The top level blocks are all described inside that blocks <code>doc</code> directory in a <code>.dox</code> files named or the component. For example, in the component <code>gr-digital</code>, the manual page describing this component is in <code>gr-digital/doc/digital.dox</code>. 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.<br />
<br />
The component's <code>doc</code> directory will also contain a <code>README.package</code> 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.<br />
<br />
=== Doxygen Markup for Formulas ===<br />
<br />
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 &quot;\f{&quot; to begin and &quot;\f}&quot; 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:<br />
<br />
<pre>This is some text in the header...<br />
\f{html}{<br />
enter Latex formula here -&gt; will only show up in the HTML document.<br />
}<br />
<br />
\xmlonly<br />
Same Latex formula, but this will not be processed; will only be the raw Latex formula.<br />
\endxmlonly<br />
<br />
And here's some following text to the formulas.</pre><br />
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 &quot;\ f&quot;.<br />
<br />
== What's this Copyright Assignment? ==<br />
<br />
Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the [http://www.fsf.org/ FSF]. A description of the process is available [http://www.gnu.org/prep/maintain/html_node/Legally-Significant.html here]. Basically, this guarantees the FSF (who is copyright holder of GNU Radio) does not run into any legal trouble somewhere down the road.<br />
<br />
This boils down to the following instructions:<br />
<br />
'''''' If you've developed some addition or patch to GNU Radio that you would like to contribute, you should send an email to the mailing list, or to one of the GNU Radio maintainers asking for an appropriate form. We might ask you for some more information at this point.<br />
<br />
'''''' You will be sent a short form by email which you should fill in and email back to the FSF.<br />
<br />
'''''' Once the FSF have received this email, they will send you a paper copy of the full copyright assignment papers for you to sign and post back to them.<br />
<br />
'''''' As soon as the signed paperwork is filed at the FSF we can accept your changes into the source tree.<br />
<br />
'''''' Individual small changes (fewer than 10 lines of code) can, however, be accepted without a copyright assignment form on file.<br />
<br />
In order to get the process rolling, please email &quot;tom AT trondeau&quot; for a form to start the copyright process.<br />
<br />
== Who maintains GNU Radio? ==<br />
<br />
GNU Radio is currently maintained by:<br />
<br />
* [https://github.com/bhilburn Ben Hilburn] (Project Lead) and<br />
* [http://corganlabs.com Johnathan Corgan] (Chief Architect) and<br />
* Nathan West (Release Manager) and<br />
* Martin Braun (Community Manager)<br />
<br />
See also the [[Organization|full list of GNU Radio staff]].<br />
<br />
GNU Radio was founded and initially maintained by:<br />
<br />
* [http://www.comsec.com Eric Blossom]</div>Bastibl