merge from gr36_ni branch

1 files changed, 320 insertions, 0 deletions

diff --git a/README.hacking b/README.hacking
new file mode 100644
index 000000000..58b269887
--- /dev/null
+++ b/README.hacking
@@ -0,0 +1,320 @@
+# -*- Outline -*-
+#
+# Copyright 2004,2007,2008,2009 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 3, 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,
+
+
+* Boost 1.35
+
+Until boost 1.35 or later is common in distributions, you'll need to
+build boost from source yourself.  See README.building-boost.
+
+Also, when running make distcheck you'll need to provide the
+DISTCHECK_CONFIGURE_FLAGS.  E.g.,
+
+  $ make distcheck DISTCHECK_CONFIGURE_FLAGS=--with-boost=/opt/boost_1_36_0
+
+
+* 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.
+
+
+* 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
+
+    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++
+
+
+* Standard command line options
+
+When writing programs that are executable from the command line,
+please follow these guidelines for command line argument names (short
+and long) and types of the arguments.  We list them below using the
+Python optparse syntax.  In general, the default value should be coded
+into the help string using the "... [default=%default]" syntax.
+
+** Mandatory options by gr_block
+
+*** Audio source
+
+Any program using an audio source shall include:
+
+  add_option("-I", "--audio-input", type="string", default="",
+             help="pcm input device name.  E.g., hw:0,0 or /dev/dsp")
+
+The default must be "".  This allows an audio module-dependent default
+to be specified in the user preferences file.
+
+
+*** Audio sink
+
+  add_option("-O", "--audio-output", type="string", default="",
+             help="pcm output device name.  E.g., hw:0,0 or /dev/dsp")
+
+The default must be "".  This allows an audio module-dependent default
+to be specified in the user preferences file.
+
+
+** Standard options names by parameter
+
+Whenever you want an integer, use the "intx" type.  This allows the
+user to input decimal, hex or octal numbers.  E.g., 10, 012, 0xa.
+
+Whenever you want a float, use the "eng_float" type.  This allows the
+user to input numbers with SI suffixes.  E.g, 10000, 10k, 10M, 10m, 92.1M
+
+If your program allows the user to specify values for any of the
+following parameters, please use these options to specify them:
+
+
+To specify a frequency (typically an RF center frequency) use:
+
+  add_option("-f", "--freq", type="eng_float", default=<your-default-here>,
+             help="set frequency to FREQ [default=%default]")
+
+
+To specify a decimation factor use:
+
+  add_option("-d", "--decim", type="intx", default=<your-default-here>,
+             help="set decimation rate to DECIM [default=%default]")
+
+
+To specify an interpolation factor use:
+
+  add_option("-i", "--interp", type="intx", default=<your-default-here>,
+             help="set interpolation rate to INTERP [default=%default]")
+
+
+To specify a gain setting use:
+
+  add_option("-g", "--gain", type="eng_float", default=<your-default-here>,
+	     help="set gain in dB [default=%default]")
+
+
+If your application specifies both a tx and an rx gain, use:
+
+  add_option("", "--rx-gain", type="eng_float", default=<your-default-here>,
+	     help="set receive gain in dB [default=%default]")
+
+  add_option("", "--tx-gain", type="eng_float", default=<your-default-here>,
+	     help="set transmit gain in dB [default=%default]")
+
+
+To specify the number of channels of something use:
+
+  add_option("-n", "--nchannels", type="intx", default=1,
+             help="specify number of channels [default=%default]")
+
+
+To specify an output filename use:
+
+  add_option("-o", "--output-filename", type="string", default=<your-default-here>,
+             help="specify output-filename [default=%default]")
+
+
+To specify a rate use:
+
+  add_option("-r", "--bit-rate", type="eng_float", default=<your-default-here>,
+             help="specify bit-rate [default=%default]")
+     or
+
+  add_option("-r", "--sample-rate", type="eng_float", default=<your-default-here>,
+             help="specify sample-rate [default=%default]")
+
+
+If your application has a verbose option, use:
+
+  add_option('-v', '--verbose', action="store_true", default=False,
+	     help="verbose output")
+
+
+If your application allows the user to specify the "fast USB" options, use:
+
+  add_option("", "--fusb-block-size", type="intx", default=0,
+             help="specify fast usb block size [default=%default]")
+
+  add_option("", "--fusb-nblocks", type="intx", default=0,
+             help="specify number of fast usb blocks [default=%default]")