howto: add README.hacking

3 files changed, 103 insertions, 11 deletions

diff --git a/gr-howto-write-a-block/Makefile.am b/gr-howto-write-a-block/Makefile.am
index 50551ed50..98368c211 100644
--- a/gr-howto-write-a-block/Makefile.am
+++ b/gr-howto-write-a-block/Makefile.am
@@ -29,7 +29,9 @@ EXTRA_DIST = \
 	config.h.in \
 	Makefile.swig \
 	Makefile.swig.gen.t \
-	version.sh
+	version.sh \
+	README \
+	README.hacking
 
 SUBDIRS = config lib swig python grc apps
 
diff --git a/gr-howto-write-a-block/README b/gr-howto-write-a-block/README
index 29c1e99b1..368e71994 100644
--- a/gr-howto-write-a-block/README
+++ b/gr-howto-write-a-block/README
@@ -1,5 +1,5 @@
 #
-# Copyright 2005, 2006 Free Software Foundation, Inc.
+# Copyright 2005,2006,2009 Free Software Foundation, Inc.
 # 
 # This file is part of GNU Radio
 # 
@@ -27,7 +27,8 @@ rest of GNU Radio in order to avoid problems for people who have begun
 to write blocks with a modified copy of gr-howto-write-a-block.
 
 This package requires that gnuradio-core is already installed.  It
-also depends on some GNU Radio prerequisites, such as boost.
+also depends on some GNU Radio prerequisites, such as Boost and
+cppunit.
 
 To build the examples from the tarball use the normal recipe:
 
@@ -35,16 +36,10 @@ To build the examples from the tarball use the normal recipe:
   $ make
   $ make check
 
-If you're building from CVS, you'll need to use this sequence, since
-CVS doesn't contain configure or the generated Makefiles.
+If you're building from git, you'll need to use this sequence, since
+git doesn't contain configure or the generated Makefiles.
 
   $ ./bootstrap
   $ ./configure
   $ make
   $ make check
-
-
-The doc directory is not built by default.  This is to avoid spurious
-build problems on systems that don't have xmlto installed.  If you
-have xmlto and its dependencies installed, you can build the html
-version of the howto article by cd'ing to doc and invoking make.
diff --git a/gr-howto-write-a-block/README.hacking b/gr-howto-write-a-block/README.hacking
new file mode 100644
index 000000000..a9e68dd89
--- /dev/null
+++ b/gr-howto-write-a-block/README.hacking
@@ -0,0 +1,95 @@
+#
+# Copyright 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.
+# 
+
+The layout of this tree is as follows. The top-level directory contains
+the autoconf/automake build definition files:
+
+bootstrap
+config.guess
+config.sub
+configure.ac
+Makefile.am
+Makefile.common
+Makefile.swig
+Makefile.swig.gen.t
+version.sh
+
+Of these files, only configure.ac, Makefile.am, and Makefile.common  would
+likely need changing in order to customize this into a new out-of-tree
+project.
+
+Subdirectory Layout
+-------------------
+
+config  - autoconf configuration macros
+lib     - GNU Radio blocks C++ API, shared lib and headers and QA code
+swig    - Generates Python API from C++ blocks
+python  - Pure Python modules (hierarchical blocks, other classes)
+grc     - GNU Radio Companion block wrappers
+apps    - GRC applications, scripts, or other executables installed to bin
+
+The 'config' directory contains autoconf configuration files which help the
+configuration script discover various things about the software development
+environment during the execution of the 'configure' script.  These files
+would likely not need any changing to customize this tree.
+
+The 'lib' directory contains those files needed to generate GNU Radio
+signal processing blocks.  These take the form of a shared library that one
+dynamically links against, and header files that one would include in
+their C++ GNU Radio application.  This directory also contains the framework
+for adding QA tests that are executed during 'make check' using the cppunit
+unit testing framework.  The generated shared library is installed into
+$prefix/lib and the header files are installed into $prefix/include/gnuradio.
+
+Adding new blocks starts here, by adding new .cc and new .h files for each
+new block, and modifying Makefile.am to add them to the build and link.  If
+desired, one can add unit tests to the QA framework that get executed during
+'make check'.
+
+The 'swig' directory contains the SWIG machinery to create a Python module
+that exports the C++ API into a Python namespace.  Each GNU Radio block gets a
+.i file (using SWIG syntax).  The master howto.i file must also have a line
+to include the block header file and a line to import the block .i file. The
+resulting _howto_swig.so and _howto_swig.py files are installed into the
+system Python lib directory under howto/ and become part of the gnuradio.howto
+Python namespace.  The Makefile.am must be customized to recognize new files
+created here.
+
+The 'python' directory contains pure Python modules that get installed into
+the system Python lib directory under howto/ and the __init__.py module
+needed to turn the directory into the gnuradio.howto namespace.  This is the
+appropriate place to put hierarchical blocks and utility classes.  Be sure
+to edit the __init__.py to add your module/symbol imports as necessary, and
+to modify the Makefile.am accordingly.
+
+This directory also contains Python-based QA code, which is executed during
+'make check'.
+
+The 'grc' directory contains the XML-based wrappers that describe your blocks
+to the GNU Radio Companion graphical flowgraph editor.  These get installed
+into the $prefix/share/gnuradio/grc/blocks directory and require modification
+of the Makefile.am to recognize new files put here.  Note: GRC only scans the
+system directory for wrapper files, so you must do a 'make install' before
+GRC will see your new files or modifications to existing ones.
+
+The 'apps' directory contains those Python and C++ programs which are to be
+installed into the system $prefix/bin directory. (FIXME: there is not
+currently an example of building a C++ binary in this directory.)