Info on daily snapshot tarball and Debian packages

git-svn-id: https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk@3022 7ae35d74-ebe9-4afe-98af-79ac388436b8

INSTALL

@@ -1,12 +1,14 @@
 Basic Installation
 ==================
 
-    For more information specific to this package, please read the README
+For more information specific to Hamlib, please read the README as well as 
-file. This source code distribution  is autoconfiguring and you should be 
+README.betatester and the first part of README.developer to see which 
-able to compile it and install it without manual interventions such as 
+additional development packages are needed. This source code distribution  
-editing Makefiles, configuration files, and so on. These are generic 
+is autoconfiguring and you should be able to compile it and install it 
-instructions for people who are not familiar with installing autoconfiguring
+without manual interventions such as editing Makefiles, configuration files, 
-software (along with some Hamlib-specific information).
+and so on. These are generic instructions for people who are not familiar 
+with installing autoconfiguring software (along with some Hamlib-specific 
+information).
 
 The simplest way to compile this package is to enter the source code
 main directory and do the following:
@@ -23,13 +25,17 @@ main directory and do the following:
         
         $ ./configure --prefix=/home/username
 
-     N.B. If you know that you won't be using scripting languages (Perl,
+     As of SVN rev-2882, the scripting language bindings are disabled by 
-     Python, or TCL) and that you won't need static libaries (most
+     default so they will need to be specifically enabled for language 
-     applications dynamically link Hamlib by default) invoke `configure'
+     binding support (this has no effect on rigctld/rotctld).  You may get a 
-     as follows:
+     make error (which means it will quit before compilation is complete) if 
+     the --with-[perl|python|tcl]-binding option(s) are used and the Swig 
+     package is not installed.
 
-        $ ./configure --without-perl-binding --without-python-binding \
+     N.B. If you know that you won't need static libaries (most applications
-        --without-tcl-binding --disable-static
+     dynamically link Hamlib by default) invoke `configure' as follows:
+     
+        $ ./configure --disable-static
 
      This will result in a much smaller Hamlib installation (and faster
      compilation :-) ).  See also the "Hamlib specific Features" section 
@@ -45,9 +51,9 @@ main directory and do the following:
      Running `make' takes a while.  Since Hamlib is a package, now is the 
      time to go get a cup of coffee.
      
-  3. Some packages are bundled with self-tests for source-code 
+  3. Some packages are bundled with self-tests for source-code verification. 
-     verification. If this package includes such tests, you can 
+     If this package includes such tests, you can optionally run them after 
-     optionally run them after compilation by typing 
+     compilation by typing 
 
         $ make check
 
@@ -57,6 +63,12 @@ main directory and do the following:
   4. Type `make install' to install the programs and any data files and
      documentation. Type `make uninstall' to undo the installation.
      
+     N.B.  Be aware that Super User (root) privileges will be required to 
+     install to /usr/local or any other system location outside of your home
+     directory.  Many distributions include the `sudo' command which will
+     permit you to install Hamlib after entering your password.  Otherwise
+     you will need to log in as 'root'.
+
      During installation, the following files go to the following directories:
         Executables          -> /prefix/bin
         Libraries            -> /prefix/lib
@@ -126,8 +138,8 @@ main directory and do the following:
      from the Hamlib source directory.  This will work unless `make distclean'
      has been run.
 
-Compiler configuration
+Compiler configuration (Advanced usage)
-======================
+=======================================
 
    The `configure' shell script is responsible for choosing and configuring
 the compiler(s). 
@@ -156,7 +168,7 @@ On the tcsh shell, use the `setenv' command instead:
   % setenv CFLAGS "-g"
   ...etc...
 
-For other shell, please consult your shell's documentation.
+For other shells, please consult your shell's documentation.
 
 Similarly, you can increase the optimization level by assigning these
 variables to "-g -O3". 

README.betatester

@@ -28,10 +28,10 @@ test from the latest SVN version of the code.  And, depending on feedback you
 make, developers can commit a fix, so you can try out the change soon after,
 without waiting for the next official version.
 
-To proceed, you will have first to obtain either a daily snapshot or a check out
+To proceed, you will have first to obtain either a daily snapshot or a check 
-of the latest sources from the SVN repository, then rebuild the Hamlib package
+out of the latest sources from the SVN repository, then rebuild the Hamlib 
-and finally test it with your rig. Don't worry, it's much simpler than it looks,
+package and finally test it with your rig. Don't worry, it's much simpler 
-despite the size of the package.
+than it looks, despite the size of the package.
 
 Pre-requisite:
  - some kind of internet access
@@ -43,11 +43,15 @@ So here we go:
 
 * Daily SVN trunk snapshots:
 
-Download the latest SVN trunk snapshot from http://n0nb.users.sourceforge.net
+Download the latest SVN trunk snapshot from:
-You'll find a tarball with a name like hamlib-1.2.10svn-20090306.tar.gz,
+
-i.e. a check out made 06 Mar 2009, ready for building using the familiar
+http://n0nb.users.sourceforge.net
-"three step" (see below).  Each morning by about 1130z a new snapshot is
+
-generated and uploaded and the prior day's version is removed.
+You'll find a tarball with a name like 
+hamlib-1.2.13svn-rev-3021-20110119.tar.gz, i.e. a check out made 19 Jan 2011 
+at SVN revision 3021, ready for building using the familiar "three step" 
+(see below).  Each morning by about 1130z a new snapshot is generated and 
+uploaded and the prior day's version is removed.
 
 The advantage of the SVN snapshot is that you won't need as many tools
 installed to build Hamlib as the work of Autoconf, Automake, and Libtool

README.developer

@@ -49,16 +49,17 @@ I expect that IP, USB, and other connectivity will follow afterwards.
 General Guidelines.
 -------------------
 
-0. The top level directory looks like this as of 06 Mar 2009
+0. The top level directory looks like this as of 19 Jan 2011
 (Note, it has grown considerably).
 
 ~/test/hamlib $ tree -d -I .svn
+
 .
 |-- alinco
 |-- aor
+|-- ars
 |-- bindings
 |-- c++
-|-- debian
 |-- doc
 |   `-- sgml
 |-- drake
@@ -80,7 +81,12 @@ General Guidelines.
 |   `-- tests
 |-- lib
 |-- libltdl
+|   |-- config
+|   |-- libltdl
+|   |-- loaders
+|   `-- m4
 |-- lowe
+|-- m2
 |-- macros
 |-- microtune
 |-- miniVNA
@@ -92,8 +98,10 @@ General Guidelines.
 |-- rotorez
 |-- rpcrig
 |-- rpcrot
+|-- rs
 |-- sartek
 |-- skanti
+|-- spid
 |-- src
 |-- tapr
 |-- tentec
@@ -110,7 +118,7 @@ General Guidelines.
 |-- wj
 `-- yaesu
 
-54 directories
+62 directories
 
 
 1. Building
@@ -144,6 +152,21 @@ for more information about how to use the SVN repository of Hamlib.
 A SVN manual is online at http://svnbook.red-bean.com/
 
 
+1.1.5 Experimental Git repository
+
+An experimental Git repository has been set up.  As of this moment it is 
+only tracking SVN trunk/* as its master branch.  Commits are made first to 
+SVN (git svn dcommit) and then pushed to this repository to tie the SVN ID 
+to the Git commits.  The hosting address for cloning is:
+
+git://hamlib.git.sourceforge.net/gitroot/hamlib/hamlib
+
+Nate, N0NB, will accept patches emailed from Git (they may be posted to the 
+hamlib-developer mailing list).  Patches should apply to the current SVN 
+trunk/* tree.  Keep in mind that with the SVN repository being the primary 
+repository that things like your local branching information will be lost.
+
+
 1.2. Requirements
 
 Hamlib is entirely developed using GNU tools, under various Linux systems.
@@ -154,6 +177,10 @@ That is, if you want to take part in the development of Hamlib,
 you'll need the following tools. Make sure you have at least the required
 version or you won't even be able to build from the SVN checkout.
 
+N.B. The Debian and derivatives (Ubuntu and friends) 'build-essentials' 
+package will install a number of tools and minimize the number of packages 
+that need to be installed manually.
+
 * Gnu C or any C99 compliant compiler       # gcc --version
 * Gnu make  (or any modern one, BSD okay)   # make --version
 * autoconf      2.54                        # autoconf --version
@@ -180,8 +207,8 @@ Documentation:
 * Doxygen
 * DocBook                           # Deprecated in favor of Doxygen
 
-Note:  Some systems can have several versions of the autotools installed.
+N.B.:  Some systems can have several versions of the autotools installed. In 
-In that case, autoconf may be called "autoconf2.50", autoheader
+that case, autoconf may be called "autoconf2.50", autoheader 
 "autoheader2.50", and automake "automake-1.7", aclocal "aclocal-1.7" or a 
 newer version.
 
@@ -205,7 +232,7 @@ bundled libtool source only if a newer version is installed on the system.
 To proceed, first edit the autogen.sh script, and set appropriately the
 AUTOCONF, AUTOHEADER, AUTOHEADER, and ACLOCAL variables with the required
 versions seen in the previous section (most systems will be fine with the
-default names).
+default names, only do this if a problem arises).
 
     cd hamlib
     sh ./autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
@@ -223,23 +250,23 @@ following in the same parent directory of hamlib:
 This will keep the binary output files seperate from the source tree and aid 
 in development by reducing clutter in the source tree.
 
-Once you've run `autogen.sh', make sure you've got some recent config.guess and
+Once you've run `autogen.sh', make sure you've got some recent config.guess 
-config.sub (needed to guess your system type).  Anything of at least year 2004
+and config.sub (needed to guess your system type).  Anything of at least 
-should be fine, unless you run some exotic hardware/software system:
+year 2004 should be fine, unless you run some exotic hardware/software system:
 
     ./config.guess --version
     ./config.sub --version
 
-The '--prefix' option to `autogen.sh' is optional.  Convention is that locally
+The '--prefix' option to `autogen.sh' is optional.  Convention is that 
-built packages be installed in /usr/local away from distribution installed
+locally built packages be installed in /usr/local away from distribution 
-packages.  The '--disable-static' and 'CFLAGS="-g -O0"' speeds up compilation
+installed packages.  The '--disable-static' and 'CFLAGS="-g -O0"' speeds up 
-if you don't plan to use static libraries and can bear less optimized binaries
+compilation if you don't plan to use static libraries and can bear less 
-while the '-g' option adds debugging info which can be changed to -ggdb to
+optimized binaries while the '-g' option adds debugging info which can be 
-generate debugging info for gdb.
+changed to -ggdb to generate debugging info for gdb.
 
 Additionally, you may want to add the '--with-perl-binding' or 
-'--with-python-binding' or '--enable-tcl-binding' if you are interested in Swig
+'--with-python-binding' or '--enable-tcl-binding' if you are interested in 
-binding support for those scripting languages (This is a change as of
+Swig binding support for those scripting languages (This is a change as of 
 1.2.11svn revision 2882 where Swig generated bindings are no longer built by 
 default).
 
@@ -247,32 +274,37 @@ NOTE: The autogen.sh script has only to be run the first time after a fresh
 checkout or when a Makefile.am or other build file is modified or added.
 
 The difference between building as a beta tester and a developer is in the 
-'--enable-maintainer-mode' option passed to configure from .  This option will add
+'--enable-maintainer-mode' option passed to configure from autogen.sh.  This 
-new Makefile targets and dependencies and not force a rebuild of the Makefiles
+option will add new Makefile targets and dependencies and not force a 
-when make is executed.  This is why we recommend that beta testers use the
+rebuild of the Makefiles when make is executed.  This is why we recommend 
-daily SVN snapshot from http://n0nb.users.sourceforge.net
+that beta testers use the daily SVN snapshot from:
+ 
+http://n0nb.users.sourceforge.net
 
 For a Tcl build, add this if needed:
 
     --with-tcl=/usr/lib/tcl8.2
 
-Note: C-shell users may have to run autogen.sh and make through a bourne shell
+Note: C-shell users may have to run autogen.sh and make through a bourne 
-instead, or pass "SHELL=bash" as a parameter to make.
+shell instead, or pass "SHELL=bash" as a parameter to make.
 
 
 1.4. Feedback
 
 The Hamlib team is very interested to hear from you, how Hamlib builds and 
-works on your system, especially on non-Linux or non-PC systems. We are trying
+works on your system, especially on non-Linux or non-PC systems. We are 
-to make Hamlib as portable as possible. Please report problems to our developer
+trying to make Hamlib as portable as possible. Please report problems to our 
-mailing list, hamlib-developer@lists.sourceforge.net
+developer mailing list, hamlib-developer@lists.sourceforge.net
 
-Patches are welcome too!  Just send them to the mailing list.
+Patches are welcome too!  Just send them to the mailing list.  Unified diff 
+(diff -u) is the prefered format and patches should apply to the current SVN 
+trunk, if possible.  If you're patching against an older released version of 
+Hamlib, we can take those as well.
 
 So far, Hamlib has been tested successfully under the following systems:
 (if your system is not present, please report to the mailing list)
 
-    * Debian i386
+    * Debian i386 (plus derivatives--Ubuntu, etc.)
     * Debian sid mipsel
     * RedHat i386
     * Linux ppc
@@ -320,10 +352,10 @@ So far, Hamlib has been tested successfully under the following systems:
          $ svn commit -m "Initial release" Makefile.am mybackend.c mybackend.h
 
          Note: The `-m' switch passes a short message to the SVN repository 
-         upon a commit.  If a longer message is desired, do not use the
+         upon a commit.  If a longer message is desired, do not use the `-m' 
-         `-m' option.  The editor specified in the EDITOR or VISUAL
+         option.  The editor specified in the EDITOR or VISUAL environment 
-         environment variables will be started where a more detailed message
+         variables will be started where a more detailed message may be 
-         may be composed.
+         composed.
 
 
 3. How to add a new model to an existing backend
@@ -377,8 +409,7 @@ this. The error checking is removed for simplicity.
 
 Seriously, I am hoping the API's will provide a solid framework for some 
 cool GUI development. I would like to see some GTK or Qt apps that use the 
-hamlib API's so they can be used by end users as a nice part of the Ham
+hamlib API's so they can be used by end users as a nice part of the Ham shack.
-shack.
 
 Starting points (not exhaustive):
     gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog, xtlf
@@ -398,13 +429,13 @@ under the GPL, so any contributed code must follow the rule.
 8.2 Coding guidelines and style
 
 Try to keep current style of existing code. Improvements are welcome though. 
-Contributed code should always keep the source base in a compilable
+Contributed code should always keep the source base in a compilable state, 
-state, and not regress unless stated otherwise.
+and not regress unless stated otherwise.
 
 There's no need to tag the source in a patch with your name in comments 
 behind each modification, we already know the culprit :-)
 
-Patches should take care of portability issues.
+Patches should take portability issues into account.
 Keep in mind Hamlib has to run under:
 
     * various Linux's
@@ -429,30 +460,29 @@ Portability issues to watch:
 
 8.3 Submitting patches
 
-Patches should be in unified format (diff -u), against SVN head or
+Patches should be in unified format (diff -u), against SVN trunk/ or latest 
-latest release. This format makes it easily readable.
+release. This format makes it easily readable. The patches are to be sent to 
-The patches are to be sent to the hamlib-developer
+the hamlib-developer mailing list. If the file is too big, you can send it 
-mailing list. If the file is too big, you can send it as a compressed
+as a compressed attachment.
-attachement.
 
 8.3.1 Changelog
 
-Caveat: The svn2cl program is used before each release to generate
+Caveat: The svn2cl program is used before each release to generate the 
-the Changelog file so any changes made directly to it WILL BE LOST!
+Changelog file so any changes made directly to it WILL BE LOST! Simply 
-Simply summarize your changes when the files are committed to SVN or,
+summarize your changes when the files are committed to SVN or, if providing 
-if providing patches to the mailing list, provide a summary so the
+patches to the mailing list, provide a summary so the uploader can include 
-uploader can include it in the commit message.
+it in the commit message which will show in the Changelog.
 
 8.4 SVN commit access
 
-Generally, volunteers can get access to SourceForge Hamlib SVN upon
+Generally, volunteers can get access to SourceForge Hamlib SVN upon asking 
-asking one of the project administrators.  Sometimes we'll ask you!
+one of the project administrators.  Sometimes we'll ask you!
 
-However, before your start commiting, the project admins would like
+However, before your start commiting, the project admins would like first to 
-first to have a look at your "style", just to make sure you have grok
+have a look at your "style", just to make sure you grok the Hamlib approach 
-the Hamlib approach (c.f. previous section on submitting a patch).
+(c.f. previous section on submitting a patch). Then you'll be able to commit 
-Then you'll be able to commit by yourself to the backend you have
+by yourself to the backend you have maintainance of. Please follow the rules 
-maintainance of. Please follow the rules hereunder:
+hereunder:
 
     * Always keep the SVN trunk repository in a compilable state.
     * Follow the coding guidelines