--- /dev/null
+# -*- 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_<foo> and a gri_<foo>. In that case,
+ gr_<foo> would be derived from gr_block and gri_<foo>
+ 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_<foo>.
+
+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_<foo>.
+
+
+** 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 <dirname> contains files qa_<dirname>.{h,cc}
+that bring together all the qa_<foo> 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++
projects / debian / gnuradio / blobdiff