Cleaned up top-level README, and fixed or deleted lower level ones as

appropriate.


git-svn-id: http://gnuradio.org/svn/gnuradio/trunk@3133 221aa14e-8319-0410-a670-987f0aec2ac5

1 files changed, 178 insertions, 0 deletions

diff --git a/README.hacking b/README.hacking
new file mode 100644
index 000000000..7e211e0b3
--- /dev/null
+++ b/README.hacking
@@ -0,0 +1,178 @@
+# -*- 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., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, 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.
+
+
+* 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++