Gnuradio source patch to make it work with a current GCC 4.5.0

GNU Radio
1

Hi all,

The gnuradio git-source (and also the current 3.3.0 release)
is not compatible with a current GCC 4.5.0 compiler.

I changed the source to make it work, omitting the “usrp2::” prefix in 3
cases.
The diff patch to the current trunk is attached to this mail.
Maybe the developers understand this problem, I don’t.
Possibly some faulty namespace classification (or even an gcc bug?).

Btw, why do free software developers spend more commenting
lines for the software license than for the code itself ?
It’s really hard to understand the source. All I see is legal stuff,
but no comment on the top, what a module is really doing.
A few sentences on top of the source file would help a lot, e.g.
“this part is dealing with the raw socket communications,
it supports the module xyz with a higher level API”. Something
like that. Most of the gnuradio source files have no comment
on the top what they are doing. First you have to read to code
to make a guess what’s happening there.

For my own projekts I use doxygen and on top of every
cpp or header file I’m commenting on the meaning of this part of
source code. This is just for myself. It would be even more
important if other people should be able to read and understand the
source.
Especially for OpenSource with many developers on a single source.
This little time savings in the first moment result in a lot of time
wasted
when other people trying to understand the source.

Maybe the gnuradio developers should have a look at the ITPP
sources (itpp.sourceforge.net). They are using doxygen a lot.
I like this doxygen system, for generating HTML and LaTeX
source documentation automatically. It can even generate a good-looking
handbook, if some more examples, text, images and formulas are inserted.
This takes not much time when writing the source, less than writing
a full documentation document later.

Moeller

2

Moeller

Moeller:

You’re familiar with:

http://gnuradio.org/doc/doxygen/index.html

And:

http://gnuradio.org/doc/doxygen/modules.html

The Gnu Radio developers are fond of Doxygen as well…

–
Marcus L.
Principal Investigator
Shirleys Bay Radio Astronomy Consortium

3

Oh sorry, thanks for the hint.
Apparently I only visited those source files without doxygen comments.

Anyway, instead of the long GPL legal advices, I’m missing
at least a tiny little comment on top about the meaning of a certain
source file. For that I’m using the \brief doxygen-tag after \file in
every
of my own source files. In Gnuradio, you first have to dig deep into
the source to understand what a file is about.
This is very common in GNU projects.

For Matlab/Octave I wrote my own Doxygen-Parser, so every function
get it’s \brief \file \param \note \todo \sa tags.
You can generate really good-looking documentation pages
using latex-formulas with \f[ - Tags, \image schematic blocks
and \latexonly \cite literature references etc.

What about Python?

For Doxygen there are two documentation tag styles

http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks

I saw some of the “docstrings” in the gnuradio source,
but not in the Doxygen-Doc. Can this be integrated, or
does it need a second independent Doc?

Moeller

On 04

4

On Wed, Aug 04, 2010 at 02:46:21PM +0200, Moeller wrote:

Hi all,

The gnuradio git-source (and also the current 3.3.0 release)
is not compatible with a current GCC 4.5.0 compiler.

I changed the source to make it work, omitting the “usrp2::” prefix in 3 cases.
The diff patch to the current trunk is attached to this mail.
Maybe the developers understand this problem, I don’t.
Possibly some faulty namespace classification (or even an gcc bug?).

Thanks for the patch.

5

On Wed, Aug 04, 2010 at 05:35:01PM +0200, Moeller wrote:

Oh sorry, thanks for the hint.
Apparently I only visited those source files without doxygen comments.

FWIW, the doxygen comments are in the .h files

Eric

6

On Wed, Aug 4, 2010 at 05:46, Moeller [email protected] wrote:

I changed the source to make it work, omitting the “usrp2::” prefix in 3
cases.
The diff patch to the current trunk is attached to this mail.

This patch was applied. Thanks.

Johnathan

7

On 04.08.2010 19:24, Eric B. wrote:

On Wed, Aug 04, 2010 at 05:35:01PM +0200, Moeller wrote:

Oh sorry, thanks for the hint.
Apparently I only visited those source files without doxygen comments.
FWIW, the doxygen comments are in the .h files
Eric

From the C sources I checked only a few examples.
Now, after digging more into the sources, I see lots of documented
classes.
Anyway, I’m still missing the \file \brief doxygen tags
for the files. These are extremely useful when browsing through
a mass of unknown source material.
Otherwise you have to read the source in depth to find out what
the sourcefile is all about.
But most GNU projects only give the GPL legal information on top.

Python sources are less documented in gnuradio. For example
gnuradio-core\src\python\gnuradio\blks2impl\generic_usrp.py
No short info what this is all about. You have to read until line 130
to have an explanation about what a certain class is doing for
“generic_usrp”.
Is it a substitue for the usrp/usrp2 imports, an alternative way to
access
USRP and USRP2? How to use it? I think most questions could be answered
with a few clear sentences for introduction.
For me, the gnuradio is less a hacking library, but more a solid basis
for student education, research and experimentation.
Like a substitute for Simulink for live radio purposes.

I know, if you’re working a long time with a library, the structure is
very clear.
But for beginners trying to understand the source, comments should be
more helpful. I would suggest to implement a short abstract to every
source
file. Perhaps as a \file \brief header (I’m using these for every file),
in addition to the class based doc. What about extending
the docs/doxygen templates with more of the doxygen features?

Can the doxygen be extended to the Python part, too?
Doxygen is able to handle Python. I just don’t know if the mix with
C-Source is possible. Perhaps it needs two independent doxygen
doc folders. For my own projects, I use Doxygen to generate a manual.
What about creating a readable Gnuradio manual in this way?
This is much more than just a class browser, with a lot of descriptions,
application examples, formulas for math functions, images, files
overview.
It needs to introduce some doxygen text structure tags for this,
latex-includes, formulas, images, bibtex-literature list.

Moeller

8

I like your ideas!

Anyway, I’m still missing the \file \brief doxygen tags
for the files. These are extremely useful when browsing through
a mass of unknown source material.
Otherwise you have to read the source in depth to find out what
the sourcefile is all about.
But most GNU projects only give the GPL legal information on top.

When I was maintaining GDB, I found it very handy to put a one-line
comment at the top of each file, like this:

% head -1 c*.[ch]
==> call-cmds.h <==
/* DEPRECATED The gdblib files must not be calling/using things
in any

==> c-exp.c <==
/* A Bison parser, made by GNU Bison 1.875c. */

==> charset.c <==
/* Character set conversion support for GDB.

==> charset.h <==
/* Character set conversion support for GDB.

==> c-lang.c <==
/* C language support routines for GDB, the GNU debugger.

==> c-lang.h <==
/* C language support definitions for GDB, the GNU debugger.

==> cli-out.c <==
/* Output generating routines for GDB CLI.

==> cli-out.h <==
/* Output generating routines for GDB CLI.

==> coff-pe-read.c <==
/* Read the export table symbols from a portable executable and

==> coff-pe-read.h <==
/* Interface to coff-pe-read.c (portable-executable-specific symbol
reader).

==> coffread.c <==
/* Read coff symbol tables and convert to internal format, for GDB.

==> command.h <==
/* Header file for command-reading library command.c.

==> complaints.c <==
/* Support for complaint handling during symbol reading in GDB.

==> complaints.h <==
/* Definitions for complaint handling during symbol reading in GDB.

==> completer.c <==
/* Line completion stuff for GDB, the GNU debugger.

==> completer.h <==
/* Header for GDB line completion.

==> copying.c <==
/* ==> Do not modify this file!! It is created automatically

==> corefile.c <==
/* Core dump and executable file functions above target vector, for GDB.

==> corelow.c <==
/* Core dump and executable file functions below target vector, for GDB.

==> core-regset.c <==
/* Machine independent GDB support for core files on systems using
“regsets”.

==> cp-abi.c <==
/* Generic code for supporting multiple C++ ABI’s

==> cp-abi.h <==
/* Abstraction of various C++ ABI’s we support, and the info we need

==> cp-name-parser.c <==
/* A Bison parser, made by GNU Bison 1.875c. */

==> cp-namespace.c <==
/* Helper routines for C++ support in GDB.

==> cp-support.c <==
/* Helper routines for C++ support in GDB.

==> cp-support.h <==
/* Helper routines for C++ support in GDB.

==> cp-valprint.c <==
/* Support for printing C++ values for GDB, the GNU debugger.

==> cris-tdep.c <==
/* Target dependent code for CRIS, for GDB, the GNU debugger.

==> c-typeprint.c <==
/* Support for printing C and C++ types for GDB, the GNU debugger.

==> c-valprint.c <==
/* Support for printing C values for GDB, the GNU debugger.

% head -15 c-valprint.c
/* Support for printing C values for GDB, the GNU debugger.

Copyright © 1986, 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996,
1997,
1998, 1999, 2000, 2001, 2003, 2005, 2006, 2007, 2008
Free Software Foundation, Inc.

This file is part of GDB.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
[…]

I suspect that if you, Moeller, submitted a patch that added
a similar comment to every GNU Radio source file that you understand
the function of, it would be accepted. And might even inspire others
who understand different files to add their own insights. And some
maintainer or volunteer might someday complete the task for all the
files, and revise the coding standards to require it on new files.

For me, the gnuradio is less a hacking library, but more a solid basis
for student education, research and experimentation.

The great thing about free software is that one guy can push it
in a direction they choose, like becoming a better educational tool.
All it takes is time, work, and some coordination.

In rx_timed_samples.cpp
the URSP-device is hard-wired, as a uhd-derived class.
“uhd::usrp::simple_usrp::sptr sdev”
So, once compiled, it can only support the USRP-type.

I would prefer to leave this dynamic.

I agree, and have been concerned about this aspect of GNU Radio
for years. Moeller, do you have a design for how it should work?
If the community doesn’t hate your design, are you willing to
implement it?

John

9

On 06.08.2010 00:30, John G. wrote:

When I was maintaining GDB, I found it very handy to put a one-line
comment at the top of each file, like this:

% head -1 c*.[ch]
==> c-exp.c <==
/* A Bison parser, made by GNU Bison 1.875c. */
This is not a replacement for a comprehensive doxygen-header,
but I like this idea of a short one-liner fixed on line “1”.
So, it’s really easy to parse with the head command.
Parsing doxygen comments would be harder, because you have
to detect the context (does \brief belong to a file header or to a
class).

I think this is not redundant to the \file \brief doxygen short
abstract, so
in the end you could have abstract at 3 detail levels: one-liner on top,
a \brief doxygen description in a few lines, and (optionally) a more
detailed description. Not bad when browsing the source.

The \brief doxygen statements are also very nice for generating a
software manual from the source and additional LaTex text files.

I suspect that if you, Moeller, submitted a patch that added
a similar comment to every GNU Radio source file that you understand
the function of, it would be accepted. And might even inspire others
who understand different files to add their own insights. And some
maintainer or volunteer might someday complete the task for all the
files, and revise the coding standards to require it on new files.
Unfortunatly, my spare time is nearly zero. I’m just looking for a solid
basis
for experiments in our laboratory. Gnuradio is a good choice.
Possibly, later we could publish a few contributions to Gnuradio out of
this work.

I attached my idea of a source file template. I’m using a similar header
for all
of my source files. Organization into files give the software a certain
structure,
so I like the file-based documentation. Additionally I write short
comments to the
classes and functions, too.

It would be useful, to place such a source file template somewhere
between
the gnuradio-examples programs. The c++/dial_tone examples are not
documented
at all. The examples in docs/docygen only carry a class based doxygen
header.
This is Ok, if there is only one class per file. But for multiple
classes, I would
add a file-based header.

The great thing about free software is that one guy can push it
in a direction they choose, like becoming a better educational tool.
All it takes is time, work, and some coordination.
I think a handbook for gnuradio is missing.
Students trying to understand gnuradio have no long programming
experience,
and usually no Python experience. They might be frustrated, if it’s too
hard
to understand the library, all the files, includes, classes and
different approaches
(like using separate sources for different device types).
There is not much time for it between exams.

For my own projects I use doxygen to generate software manuals.
One thing is the automatic class documentation, derived from the C++
data
structures and doxygen-tag comments.
Another very important part is the additional text you write for this
manual.
I’m using doxygen- and latex-includes to add a title page, introduction,
some chapters,
formulas, screenshots etc.
It will produce a nice PDF document in the end, with TOC, bibliography,
index.
I’m not familiar with a HTML variant of this. But it should be possible.
There are some \latexonly and \htmlonly statements in doxygen.
So this could be differentiated somehow.

In rx_timed_samples.cpp
the URSP-device is hard-wired, as a uhd-derived class.
“uhd::usrp::simple_usrp::sptr sdev”
So, once compiled, it can only support the USRP-type.

I would prefer to leave this dynamic.
I agree, and have been concerned about this aspect of GNU Radio
for years. Moeller, do you have a design for how it should work?
If the community doesn’t hate your design, are you willing to
implement it?

In the attached txt, I wrote down some thoughts about it.
It seems that UHD has the same direction.
For me it’s important that dynamic data structures are used.
So, e.g. a std::map key-value list of device properties.
At compile-time, all can be left dynamic. If a device does not
provide a certain capability, the property values are simply not
allocated.
If a sample program wants this value, it should handle the case that it
does not exist (e.g. no centerfrequency for an audio device).
In contrast, the standard C++ way would be to derive a device-specific
class from a generic abstract class.
This problem is, that this is not flexible during run-time.
And every device-type would need a special source file.
I didn’t understand exactly, how UHD would handle this.

Moeller

10

On 06.08.2010 00:30, John G. wrote:

When I was maintaining GDB, I found it very handy to put a one-line
comment at the top of each file, like this:

% head -1 c*.[ch]
==> c-exp.c <==
/* A Bison parser, made by GNU Bison 1.875c. */
This is not a replacement for a comprehensive doxygen-header,
but I like this idea of a short one-liner fixed on line “1”.
So, it’s really easy to parse with the head command.
Parsing doxygen comments would be harder, because you have
to detect the context (does \brief belong to a file header or to a
class).

I think this is not redundant to the \file \brief doxygen short
abstract, so
in the end you could have abstract at 3 detail levels: one-liner on top,
a \brief doxygen description in a few lines, and (optionally) a more
detailed description. Not bad when browsing the source.

The \brief doxygen statements are also very nice for generating a
software manual from the source and additional LaTex text files.

I suspect that if you, Moeller, submitted a patch that added
a similar comment to every GNU Radio source file that you understand
the function of, it would be accepted. And might even inspire others
who understand different files to add their own insights. And some
maintainer or volunteer might someday complete the task for all the
files, and revise the coding standards to require it on new files.
Unfortunatly, my spare time is nearly zero. I’m just looking for a solid
basis
for experiments in our laboratory. Gnuradio is a good choice.
Possibly, later we could publish a few contributions to Gnuradio out of
this work.

I attached my idea of a source file template. I’m using a similar header
for all
of my source files. Organization into files give the software a certain
structure,
so I like the file-based documentation. Additionally I write short
comments to the
classes and functions, too.

It would be useful, to place such a source file template somewhere
between
the gnuradio-examples programs. The c++/dial_tone examples are not
documented
at all. The examples in docs/docygen only carry a class based doxygen
header.
This is Ok, if there is only one class per file. But for multiple
classes, I would
add a file-based header.

The great thing about free software is that one guy can push it
in a direction they choose, like becoming a better educational tool.
All it takes is time, work, and some coordination.
I think a handbook for gnuradio is missing.
Students trying to understand gnuradio have no long programming
experience,
and usually no Python experience. They might be frustrated, if it’s too
hard
to understand the library, all the files, includes, classes and
different approaches
(like using separate sources for different device types).
There is not much time for it between exams.

For my own projects I use doxygen to generate software manuals.
One thing is the automatic class documentation, derived from the C++
data
structures and doxygen-tag comments.
Another very important part is the additional text you write for this
manual.
I’m using doxygen- and latex-includes to add a title page, introduction,
some chapters,
formulas, screenshots etc.
It will produce a nice PDF document in the end, with TOC, bibliography,
index.
I’m not familiar with a HTML variant of this. But it should be possible.
There are some \latexonly and \htmlonly statements in doxygen.
So this could be differentiated somehow.

In rx_timed_samples.cpp
the URSP-device is hard-wired, as a uhd-derived class.
“uhd::usrp::simple_usrp::sptr sdev”
So, once compiled, it can only support the USRP-type.

I would prefer to leave this dynamic.
I agree, and have been concerned about this aspect of GNU Radio
for years. Moeller, do you have a design for how it should work?
If the community doesn’t hate your design, are you willing to
implement it?

In the attached txt, I wrote down some thoughts about it.
It seems that UHD has the same direction.
For me it’s important that dynamic data structures are used.
So, e.g. a std::map key-value list of device properties.
At compile-time, all can be left dynamic. If a device does not
provide a certain capability, the property values are simply not
allocated.
If a sample program wants this value, it should handle the case that it
does not exist (e.g. no centerfrequency for an audio device).
In contrast, the standard C++ way would be to derive a device-specific
class from a generic abstract class.
This problem is, that this is not flexible during run-time.
And every device-type would need a special source file.
I didn’t understand exactly, how UHD would handle this.

Moeller