X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=README.hacking;fp=README.hacking;h=1a604395b76dab1e95f0addea0c1029cbd30ed7d;hb=0cfd4875e519e2b1ee05d074f72ec67391ed13bf;hp=0000000000000000000000000000000000000000;hpb=18a684bf3dc144c48fc4cc6cc72f5070febd8074;p=debian%2Fgnuradio diff --git a/README.hacking b/README.hacking new file mode 100644 index 00000000..1a604395 --- /dev/null +++ b/README.hacking @@ -0,0 +1,203 @@ +# -*- Outline -*- +# +# Copyright 2004 Free Software Foundation, Inc. +# +# This file is part of GNU Radio +# +# GNU Radio 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 2, or (at your option) +# any later version. +# +# GNU Radio is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU Radio; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, +# Boston, MA 02110-1301, USA. +# + + +Random notes on coding conventions, some explanations about why things +aren't done differently, etc, etc, + + +* C++ and Python + +GNU Radio is now a hybrid system. Some parts of the system are built +in C++ and some of it in Python. In general, prefer Python to C++. +Signal processing primitives are still built in C++ for performance. + +It is no longer possible to build user applications entirely in C++. +Essential parts of the runtime system have been moved into Python. + + +* C++ namespaces + +In the cleanup process, I considered putting everything in the +gnuradio namespace and dropping the Gr|gr prefix. In fact, I think +it's probably the right idea, but when I tested it out, I ran into +problems with SWIG's handling of namespaces. Bottom line, SWIG +(1.3.21) got confused and generated bad code when I started playing +around with namespaces in a not particularly convoluted way. I saw +problems using the boost::shared_ptr template in combination with +classes defined in the gnuradio namespace. It wasn't pretty... + + +* Naming conventions + +Death to CamelCaseNames! We've returned to a kinder, gentler era. +We're now using the "STL style" naming convention with a couple of +modifications since we're not using namespaces. + +With the exception of macros and other constant values, all +identifiers shall be lower case with words_separated_like_this. + +Macros and constant values (e.g., enumerated values, +static const int FOO = 23) shall be in UPPER_CASE. + + +** Global names + +All globally visible names (types, functions, variables, consts, etc) +shall begin with a "package prefix", followed by an '_'. The bulk of +the code in GNU Radio logically belongs to the "gr" package, hence +names look like gr_open_file (...). + +Large coherent bodies of code may use other package prefixes, but +let's try to keep them to a well thought out list. See the list +below. + +*** Package prefixes + +These are the current package prefixes: + + gr_ Almost everything + + gri_ Implementation primitives. Sometimes we + have both a gr_ and a gri_. In that case, + gr_ would be derived from gr_block and gri_ + would be the low level guts of the function. + + atsc_ Code related to the Advanced Television + Standards Committee HDTV implementation + + usrp_ Universal Software Radio Peripheral + + qa_ Quality Assurance. Test code. + + +** Class data members (instance variables) + +All class data members shall begin with d_. + +The big win is when you're staring at a block of code it's obvious +which of the things being assigned to persist outside of the block. +This also keeps you from having to be creative with parameter names +for methods and constructors. You just use the same name as the +instance variable, without the d_. + +class gr_wonderfulness { + std::string d_name; + double d_wonderfulness_factor; + +public: + gr_wonderfulness (std::string name, double wonderfulness_factor) + : d_name (name), d_wonderfulness_factor (wonderfulness_factor) + { + ... + } + ... +}; + + +** Class static data members (class variables) + +All class static data members shall begin with s_. + + +** File names + +Each significant class shall be contained in it's own file. The +declaration of class gr_foo shall be in gr_foo.h, the definition in +gr_foo.cc. + + + +* Storage management + +Strongly consider using the boost smart pointer templates, scoped_ptr +and shared_ptr. scoped_ptr should be used for locals that contain +pointers to objects that we need to delete when we exit the current +scope. shared_ptr implements transparent reference counting and is a +major win. You never have to worry about calling delete. The right +thing happens. + +See http://www.boost.org/libs/smart_ptr/smart_ptr.htm + + +* Unit tests + +Build unit tests for everything non-trivial and run them after every +change. Check out Extreme Programming: +http://c2.com/cgi/wiki?ExtremeProgrammingRoadmap + +Unit tests should also be written for all examples. This should kill +off the bit rot we've been plagued with. + +** C++ unit tests + +For C++ we're using the cppunit framework. cppunit has its bad +smells, but it's mostly workable. http://cppunit.sf.net + +Currently each directory contains files qa_.{h,cc} +that bring together all the qa_ test suites in the directory. +We ought to be able to automate this without too much trouble. + +The directory gnuradio-core/src/tests contains programs that run +the tests. test_all runs all of the registered C++ unit tests. + +As far as I can tell, the cppunit TestFactoryRegistry maybe able to be +tricked into doing what we want. As is, I don't think it's enough by +itself, since there's nothing dragging the qa* files out of the +library and into the program. I haven't tested out this idea. + +** Python unit tests + +We use the standard unittest package for unit testing of Python code. + + +* Subversion line ending styles + +All text files in the tree should have the subversion property +'svn:eol-style' set to 'native', with the following exceptions: + +config/*.m4 +configure.ac +gr-howto-write-a-block/config/*.m4 +gr-howto-write-a-block/configure.ac + +The easiest way to ensure this is to add or edit the following lines in +your svn client configuration file (~/.subversion/config): + +enable-auto-props=yes + +[auto-props] +*.c = svn:eol-style=native +*.cc = svn:eol-style=native +*.i = svn:eol-style=native +*.h = svn:eol-style=native +*.am = svn:eol-style=native +*.py = svn:eol-style=native +*.ac = svn:eol-style=LF +*.m4 = svn:eol-style=LF + +* Misc tips + +ccache, a compiler cache, can really speed up your builds. +See http://ccache.samba.org/ + +Be sure to create links for gcc and g++