#
# Copyright 2001,2002,2003 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.
# 

-------------------------------------------------------------------------------

				Brief News

-------------------------------------------------------------------------------

2003-09-29:  You can now compile and link your own code to GNU Radio using
  pkg-config.  This allows you to side step the autoconf / automake jungle.
  See "using pkg-config" below.

-------------------------------------------------------------------------------

				IMPORTANT

-------------------------------------------------------------------------------

Prerequisites (you may already have these):
(1)  pkgconfig 0.15.0 or later  http://www.freedesktop.org/Software/pkgconfig

From the web site:

pkgconfig is a system for managing library compile/link flags that
works with automake and autoconf. It replaces the ubiquitous *-config
scripts you may have seen with a single tool.


(2)  FFTW 3.0 or later	      http://www.fftw.org

When building FFTW, please use the --enable-single configure option.
This builds the single precision floating point version which we use.
You may also want to consider the --enable-3dnow --enable-sse or
--enable-sse2 options if your hardware supports them.


(3) Python 2.2		      http://www.python.org

Python 2.2 is now required.  Python 2.3 will probably work too, but
hasn't been tested.  If your distribution splits python into a bunch
of separate RPMS including python-devel or libpython you'll most
likely need those too.


(4) wxPython 2.4.2.4 or later	http://www.wxpython.org

Get the version that matches your copy of Python.  You'll need the
devel libs too.  


(5) Numeric Python (Numeric-22 -23 probably works too, not tested)


http://sourceforge.net/projects/numpy


Optional (but at least for now, nice to have)
---------------------------------------------

(O1)  Qt 2.2.1 or later			http://www.trolltech.com


Qt 2.2.1 or later is also useful (but many GNU/linux distributions
already have it installed).

Most recently we've been using Qt-3.1.1.  If Qt is included in your
distribution and has qt-devel split out into a separate RPM, you'll
need need it too.



Also, some 2.2 linux systems have a bug in their version of
/usr/include/sys/io.h.  If the build breaks trying to compile ppio.c,
the fix is to edit your /usr/include/sys/io.h file, and replace all
occurrences of "::" with ": :" (Insert a space between the colons)

-------------------------------------------------------------------------------

Notes for those on the bleeding edge:

      If you're building a version of GNU Radio checked out of CVS,
      see the notes at the bottom, and then come back here...

-------------------------------------------------------------------------------


For the impatient, just do the following:

	$ ./configure
	$ make
	$ make check
	$ make install

If it doesn't work, fix it and send us a patch...


See http://www.gnu.org/software/gnuradio/ for an overview.
The project is hosted at http://savannah.gnu.org/projects/gnuradio/


The Advanced Television Standards Committee (ATSC) Digital Television
transmitter and receiver are now working and have successfully
demodulated off-the-air signals.

The main programs for each are:

    src/gnu/atsc/atsc_tx.cc
    src/gnu/atsc/atsc_rx.cc

run_rx provides an interface for running the receiver and summarizing
its performance.

There are scripts that will exercise both in a loop back fashion.
Try src/gnu/atsc/test_full_loopback.

The ATSC code lives in gnuradio/src/gnu/lib/{gr,dtv}


For less complicated examples see this code:


      $ cd src/gnu/examples

      $ ./mono_audio_out
      $ ./stereo_audio_out
      $ ./audio_scope
      $ ./simple_fft
      $ ./mixer
	       

If you've got some kind of RF input, there are also FM demodulators
available in the examples directory.

	  microtune_fm_demo demodulates a single FM channel
	  fm_demod2 demods 2 FM channels concurrently

If you've got the microtune eval board and a PCI DAS4020/12, then
these commands are the fun ones:
	
      $ ./adc3_fft &			# read adc channel 3 and plot
      $ ./microtune 93.9		# tune 93.9 MHz to center of IF

or, to listen to two FM stations that are within 5.5 MHz of each other:

      $ ./fm_demod2 102.5 103.9

Most of the screen shots on the web site we were created running
microtune_fm_demo or adc3_fft.  We were using a cable modem tuner
module hooked to a Measurement Computing PCI DAS4020/12 12-bit 
20 million sample/sec A/D board.

If you've got doxygen installed, the build process creates
documentation for the class hierarchy etc.  Point your browser at
.../doc/html/index.html

We're looking for more demos.  Dive in, join the mailing list, let us
know what you come up with.

The GNU Radio Team!


----------------------------------------------------------------

			Misc notes

----------------------------------------------------------------

Configure now supports a --disable-gui option which eliminates
the dependency on Qt.  Using this option, we've successsfully built on
solaris 2.8 using gcc and gmake.

----

Solaris note:  The default kernel parameters for shared memory are way
too small for our use.  We use lots of small segments to implement
circular buffers.  You'll need to bump up these kernel parameters (see
/etc/system)

  shmsys:shminfo_shmmax       MAXINT
  shmsys:shminfo_shmmni         1024
  shmsys:shmseg_shmseg          1024

----

If you're building with g++ 3.x and your distribution was built with
2.96, ./configure will probably fail trying to locate Qt 2.x, even
though you're sure you've got it installed.  The problem is that the
default installation of Qt will have been built with g++ 2.96 which is
not binary compatible with the code generated by 3.x.  The fix is to
download the source for Qt and build it using g++ 3.x, then set some
environment variables prior to running configure.

On our systems, this bit of shell code has us win with g++ 3.x

CC=gcc-3.1.1
CXX=g++-3.1.1
F77=g77-3.1.1
QTDIR=~/build/qt-x11-free-3.0.4
LD_LIBRARY_PATH=$QTDIR/lib
export CC CXX F77 QTDIR LD_LIBRARY_PATH


--------------------------------------------------------------------

 Using pkg-config to compile & link your stuff with libgnuradio

			     or

        Notes on compiling and linking programs you write
 without getting lost in a twisty maze of autoconf / automake cruft

--------------------------------------------------------------------

What do I need to do to link to gnuradio?

Gnuradio uses pkg-config.  Find a package for your favorite distribution
and OS, or build it from source. To build your Gnuradio program, try

$ g++ -o myprog `pkg-config --cflags --libs gnuradio` myprog.cc

This process can be integrated into your autoconf/automake build system
with pkg.m4, included in the pkg-config package. Just add the line

PKG_CHECK_MODULES(GNURADIO, gnuradio, HAVE_GNURADIO=true, HAVE_GNURADIO=false)

to your configure.ac.

In addition to HAVE_GNURADIO, the variables GNURADIO_LIBS and
GNURADIO_CFLAGS will be created. To substitute on them
you'll have to AC_SUBST both of them separately.


Note: if you get the message,

      "Package gnuradio was not found in the pkg-config search path."

Try this:

    $ export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:/usr/local/gnuradio/lib/pkgconfig"

By default, GNU Radio installs in /usr/local/gnuradio.  Setting
PKG_CONFIG_PATH tells pkg-config where to look for the .pc
configuration files.

----------------------------------------------------------------

    Notes on building GNU Radio from the CVS repository

----------------------------------------------------------------

If you're building from the CVS repository YOU MUST BE PLAYING BY THE
RULES THAT THE OTHER DEVELOPERS ARE USING.  This is especially true
with regard to the versions of the tools below...

Ensure that you've got THESE VERSIONS of the following tools:

       autoconf 2.57    or later
       automake 1.7.4   or later
       libtool  1.5     or later
       swig     1.3.19  or later

If you're using earlier versions than these, don't expect the system
to build.  Get these versions or something later.  They're available
at any of the GNU mirrors.

Then, check out a copy of GNU Radio.  

See http://www.gnu.org/software/gnuradio for directions on anonymous
access to the CVS repository.

Then in the top level directory, execute

     $ ./bootstrap

This builds configure from configure.ac and also builds all the
Makefile.in's from the Makefile.am's.

Then ./configure adding the  --enable-maintainer-mode flag.
This enables the maintainer rules in the Makefiles that allow for the
regeneration of Makefile.in's from Makefile.am's.

FYI, in the tarballs that we distribute, these rules are turned off to
ensure that end users don't need the versions of the auto tools that
we're using.  We generate the Makefile.in's from the Makefile.am's
when we build the tarball, and include them in the distribution.  This
generally causes less pain, since they aren't likely to be wanting to
modify Makefile.am's.  Since you want to build from the CVS
repository, (or modify Makefile.am's) you need to be operating with
the tools we're using.

     $ ./bootstrap
     $ ./configure --enable-maintainer-mode
     $ make
     $ make check
     $ make install



Another handy trick if for example your fftw includes and libs are
installed in, say ~/local/include and ~/local/lib, instead of
/usr/local is this:

    $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/local/lib
    $ make CPPFLAGS="-I$HOME/local/include"

----------------------------------------------------------------

	   Very Brief Guide to the Source Code

----------------------------------------------------------------

Date: Thu, 31 Jul 2003 17:30:48 -0700
From: Matt Ettus <matt@ettus.com>
To: Rob Judd <judd@ob-wan.com>
Subject: Re: [Discuss-gnuradio] Directory structure
References: <3F295E1E.712C48FD@ob-wan.com>
Cc: "discuss-gnuradio@gnu.org" <discuss-gnuradio@gnu.org>

Quoting Rob Judd <judd@ob-wan.com>:

> Hi,
>
> I've been wondering why I found gnuradio so incomprehensible to work on,
> and just discovered the reason. Find attached the structure of
> directories as it stands, after one minor attempt to build under cygwin.

This is true, but its not as bad as you think.  If you just want to make radios,
the only directories you need to know are

src/gnu/examples  --- to see how it's done
src/gnu/python --- to see how it's done in Python
src/gnu/lib/gr  --- general processing blocks
src/gnu/lib/grio --- IO device blocks, like files, soundcards, AD boards, etc.
src/pspectra/lib/{vrp,vrio} --- older, soon-to-be-replaced blocks

You never need to look in cppunit or any of the config-related stuff.  Most of
the stuff under pspectra, especially the needs-work dirs are not really of
interest either.

> Is there some way this can be reduced/combined without losing separation
> between functional components, or at least can the nesting level be
> brought down somewhat?

We are planning on eventually removing the pspectra stuff as it is updated or
replaced.

Matt

----------------------------------------------------------------

	 Not quite so Brief Guide to the Source Code

----------------------------------------------------------------

On Fri, Aug 01, 2003 at 04:21:18AM +1000, Rob Judd wrote:
> Hi,
> 
> I've been wondering why I found gnuradio so incomprehensible to work on,

Lack of documentation?

> Is there some way this can be reduced/combined without losing separation
> between functional components, or at least can the nesting level be
> brought down somewhat?


Below are a few annotations:

Unless you're out looking for trouble, I'd stay away from the
"needs-work" directories.  They contain lots of code fragments, most
of which don't work, and have suffered major bit rot over the years.
Some of them can serve as a base of ideas, but most don't match the
current infrastructure.  Not a good place for seeing current idioms.


  gnuradio-0.8

  	config		# standard directory of autotools magic (ignore)

  	cppunit		# sub-project:  unit testing framework (ignore)

  	doc		# directory that docs are built in if you've
			# got doxygen installed
  		other

  	src		# where the bulk of the code lives

  		data_files	    # old data files (ignore)

  		gnu		    # all the new code lives in here

  			atsc	    # main programs and tests for digital TV

  			codecon	    # (bad) examples from codecon conference

  			examples    # reasonable place to look for examples,
				    # though not all have been updated to current
				    # idioms or preferred classes.

				    # To see examples of the latest and greatest
				    # thinking and idioms, I suggest the atsc and dtv
				    # directories.


  			gen_interpolator_taps	 # very cool old fortran code
						 #  used to generate optimal
						 #  taps for polyphase interpolator
						 #  (ignore)

  			lib	    # src for guts of GNU Radio library

  				dtv	  # digital TV stuff

  				gr	  # lots of interesting stuff. Most filtering
					  # and general purpose signal processing
					  # routines are here.  The Gr<foo> classes
					  # are usable in your flow graph.

  				grgui	  # lots of stuff related to soon to deprecated
					  #   Qt GUI

  				grio	  # signal processing primitives related
					  #  to i/o.  E.g., A/D, D/A, files...

  				reed-solomon
					  # Phil Karn's Reed-Solomon encoder/decoder
					  #  used for forward error correction
					  #  with ATSC and anything else that needs RS

  			tests		  # main test programs
					  #   these invoke qa_* test suites
					  #   found in various directories

  		pspectra     # legacy code from MIT SpectrumWare.
			     # At this point we're mostly only using a few
			     # of the very bottom level classes.

  			amps # highly incomplete amps decoder (ignore)

  			doc

  			lib	# src for pSpectra library (partially used)

  				audio	# ignore

  				perf	# obsolete performance measurement stuff (ignore)

  				vr
  				vrgui
  				vrio
  				vrp

  			pam		# obsolete test program

  		utils			# misc utilities for octave, etc.


I hope this helps remove some of the mystery.

----------------------------------------------------------------

Have fun!
