From: Johnathan Corgan Date: Fri, 13 Nov 2009 19:14:08 +0000 (-0800) Subject: howto: add README.hacking X-Git-Url: https://git.gag.com/?p=debian%2Fgnuradio;a=commitdiff_plain;h=86e93e757a16c139f58b8b524c99f994c7bc60c4 howto: add README.hacking --- diff --git a/gr-howto-write-a-block/Makefile.am b/gr-howto-write-a-block/Makefile.am index 50551ed5..98368c21 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 29c1e99b..368e7199 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 00000000..a9e68dd8 --- /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.)