From 96c0a1c14a80eca3c388e9066879793779b94eb4 Mon Sep 17 00:00:00 2001 From: "Nate Bargmann, N0NB" Date: Thu, 20 Jan 2011 03:23:17 +0000 Subject: [PATCH] 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 | 48 +++++++++----- README.betatester | 22 ++++--- README.developer | 164 +++++++++++++++++++++++++++------------------- 3 files changed, 140 insertions(+), 94 deletions(-) diff --git a/INSTALL b/INSTALL index 62dee4413..9452fafa4 100644 --- a/INSTALL +++ b/INSTALL @@ -1,12 +1,14 @@ Basic Installation ================== - For more information specific to this package, please read the README -file. This source code distribution is autoconfiguring and you should be -able to compile it and install it without manual interventions such as -editing Makefiles, configuration files, and so on. These are generic -instructions for people who are not familiar with installing autoconfiguring -software (along with some Hamlib-specific information). +For more information specific to Hamlib, please read the README as well as +README.betatester and the first part of README.developer to see which +additional development packages are needed. This source code distribution +is autoconfiguring and you should be able to compile it and install it +without manual interventions such as editing Makefiles, configuration files, +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, - Python, or TCL) and that you won't need static libaries (most - applications dynamically link Hamlib by default) invoke `configure' - as follows: + As of SVN rev-2882, the scripting language bindings are disabled by + default so they will need to be specifically enabled for language + binding support (this has no effect on rigctld/rotctld). You may get a + 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. + + N.B. If you know that you won't need static libaries (most applications + dynamically link Hamlib by default) invoke `configure' as follows: - $ ./configure --without-perl-binding --without-python-binding \ - --without-tcl-binding --disable-static + $ ./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 - verification. If this package includes such tests, you can - optionally run them after compilation by typing + 3. Some packages are bundled with self-tests for source-code verification. + If this package includes such tests, you can optionally run them after + compilation by typing $ make check @@ -56,6 +62,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 @@ -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". diff --git a/README.betatester b/README.betatester index 42d6b3ec0..6c6ce60a7 100644 --- a/README.betatester +++ b/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 -of the latest sources from the SVN repository, then rebuild the Hamlib package -and finally test it with your rig. Don't worry, it's much simpler than it looks, -despite the size of the package. +To proceed, you will have first to obtain either a daily snapshot or a check +out of the latest sources from the SVN repository, then rebuild the Hamlib +package and finally test it with your rig. Don't worry, it's much simpler +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 -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 -"three step" (see below). Each morning by about 1130z a new snapshot is -generated and uploaded and the prior day's version is removed. +Download the latest SVN trunk snapshot from: + +http://n0nb.users.sourceforge.net + +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 diff --git a/README.developer b/README.developer index 3a535a558..0843049ed 100644 --- a/README.developer +++ b/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,9 +207,9 @@ Documentation: * Doxygen * DocBook # Deprecated in favor of Doxygen -Note: Some systems can have several versions of the autotools installed. -In that case, autoconf may be called "autoconf2.50", autoheader -"autoheader2.50", and automake "automake-1.7", aclocal "aclocal-1.7" or a +N.B.: Some systems can have several versions of the autotools installed. In +that case, autoconf may be called "autoconf2.50", autoheader +"autoheader2.50", and automake "automake-1.7", aclocal "aclocal-1.7" or a newer version. IMPORTANT: If autoconf or automake are installed on your system, @@ -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" @@ -220,59 +247,64 @@ following in the same parent directory of hamlib: make make install -This will keep the binary output files seperate from the source tree and aid +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 -config.sub (needed to guess your system type). Anything of at least year 2004 -should be fine, unless you run some exotic hardware/software system: +Once you've run `autogen.sh', make sure you've got some recent config.guess +and config.sub (needed to guess your system type). Anything of at least +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 -built packages be installed in /usr/local away from distribution installed -packages. The '--disable-static' and 'CFLAGS="-g -O0"' speeds up compilation -if you don't plan to use static libraries and can bear less optimized binaries -while the '-g' option adds debugging info which can be changed to -ggdb to -generate debugging info for gdb. +The '--prefix' option to `autogen.sh' is optional. Convention is that +locally built packages be installed in /usr/local away from distribution +installed packages. The '--disable-static' and 'CFLAGS="-g -O0"' speeds up +compilation if you don't plan to use static libraries and can bear less +optimized binaries while the '-g' option adds debugging info which can be +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 -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 +Additionally, you may want to add the '--with-perl-binding' or +'--with-python-binding' or '--enable-tcl-binding' if you are interested in +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). 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 -new Makefile targets and dependencies and not force a rebuild of the Makefiles -when make is executed. This is why we recommend that beta testers use the -daily SVN snapshot from http://n0nb.users.sourceforge.net +The difference between building as a beta tester and a developer is in the +'--enable-maintainer-mode' option passed to configure from autogen.sh. This +option will add new Makefile targets and dependencies and not force a +rebuild of the Makefiles when make is executed. This is why we recommend +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 -instead, or pass "SHELL=bash" as a parameter to make. +Note: C-shell users may have to run autogen.sh and make through a bourne +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 -to make Hamlib as portable as possible. Please report problems to our developer -mailing list, hamlib-developer@lists.sourceforge.net +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 to make Hamlib as portable as possible. Please report problems to our +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 @@ -319,11 +351,11 @@ So far, Hamlib has been tested successfully under the following systems: $ svn add Makefile.am mybackend.c mybackend.h $ 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 - `-m' option. The editor specified in the EDITOR or VISUAL - environment variables will be started where a more detailed message - may be composed. + 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 `-m' + option. The editor specified in the EDITOR or VISUAL environment + variables will be started where a more detailed message may be + composed. 3. How to add a new model to an existing backend @@ -375,10 +407,9 @@ this. The error checking is removed for simplicity. "Build it and they will come ..." -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 -shack. +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 shack. Starting points (not exhaustive): gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog, xtlf @@ -388,8 +419,8 @@ Starting points (not exhaustive): 8.1 License -Contributed code to the Hamlib frontend must be released under the LGPL. -Contributed code to Hamlib backends must follow backend current license. +Contributed code to the Hamlib frontend must be released under the LGPL. +Contributed code to Hamlib backends must follow backend current license. Needless to say, the LGPL is the license of choice. End user applications like rigctl, rotctl and RPC daemons should be released @@ -397,14 +428,14 @@ 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 -state, and not regress unless stated otherwise. +Try to keep current style of existing code. Improvements are welcome though. +Contributed code should always keep the source base in a compilable state, +and not regress unless stated otherwise. -There's no need to tag the source in a patch with your name in comments +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 -latest release. This format makes it easily readable. -The patches are to be sent to the hamlib-developer -mailing list. If the file is too big, you can send it as a compressed -attachement. +Patches should be in unified format (diff -u), against SVN trunk/ or latest +release. This format makes it easily readable. The patches are to be sent to +the hamlib-developer mailing list. If the file is too big, you can send it +as a compressed attachment. 8.3.1 Changelog -Caveat: The svn2cl program is used before each release to generate -the Changelog file so any changes made directly to it WILL BE LOST! -Simply summarize your changes when the files are committed to SVN or, -if providing patches to the mailing list, provide a summary so the -uploader can include it in the commit message. +Caveat: The svn2cl program is used before each release to generate the +Changelog file so any changes made directly to it WILL BE LOST! Simply +summarize your changes when the files are committed to SVN or, if providing +patches to the mailing list, provide a summary so the uploader can include +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 -asking one of the project administrators. Sometimes we'll ask you! +Generally, volunteers can get access to SourceForge Hamlib SVN upon asking +one of the project administrators. Sometimes we'll ask you! -However, before your start commiting, the project admins would like -first to have a look at your "style", just to make sure you have grok -the Hamlib approach (c.f. previous section on submitting a patch). -Then you'll be able to commit by yourself to the backend you have -maintainance of. Please follow the rules hereunder: +However, before your start commiting, the project admins would like first to +have a look at your "style", just to make sure you grok the Hamlib approach +(c.f. previous section on submitting a patch). Then you'll be able to commit +by yourself to the backend you have maintainance of. Please follow the rules +hereunder: * Always keep the SVN trunk repository in a compilable state. * Follow the coding guidelines