From a74955fefb3f80515e1b5a667f27d76fff06dc4a Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Sun, 12 Jun 2011 22:33:28 -0500 Subject: [PATCH] README* files updated for purpose. README - Add info on availability, compiling, and version. README.betatester - Remove info relevant to developers, include 'make' targets, add info on rigctl verbosity. README.developer - Add note on developer Git acces via SSH, --- README | 122 ++++++++++++++++++++++++++++++++++------------ README.betatester | 85 ++++++++++++++++++-------------- README.developer | 20 ++++---- 3 files changed, 150 insertions(+), 77 deletions(-) diff --git a/README b/README index f034f9860..e5bde576a 100644 --- a/README +++ b/README @@ -16,7 +16,7 @@ Supported Radios ---------------- The Hamlib Wiki page, Supported Radios, contains a snapshot of the supported -radio at the time of the last Hamlib release. Go to http://www.hamlib.org +radios at the time of the last Hamlib release. Go to http://www.hamlib.org to reach the Wiki. Hamlib Design @@ -62,50 +62,112 @@ is accomplished via the Linux kernel support. USB to serial converters are well supported. Other such devices may be supported as long as they present a serial (RS-232) interface to Hamlib. +Availability +------------ + +Most distributions have the latest Hamlib release in their testing or alpha +versions of their distribution. Check your package manager for the Hamlib +version included in your distribution. + +Developing with Hamlib API +-------------------------- + +C language API documentation is at: + + http://www.hamlib.org/index.php?title=Documentation + +Take a look at tests/README for more info on simple programming examples and +test programs. + +C++ programming is supported and language bindings are available for Perl, +Python, and TCL. A network daemon utility is also available for any +programming language that supports network sockets (even netcat!). + + Recompiling ----------- Hamlib is entirely developed using GNU tools, under various Linux systems. -That is, if you want to take part in the development of Hamlib, you'll need -at least the following tools: - * autoconf > 2.54 - * automake > 1.7 - * libtool >= 2.2.6b - * doxygen - * svn and ssh to connect to http://sourceforge.net/ +The library may be recompiled by the familiar "three step": -There are also the README.betatester and README.developer files in this -directory if you feel like testing or hacking Hamlib. Otherwise, -contributions of rig specifications and protocol documentation are highly + ./configure + make + sudo make install + +See the INSTALL file for more information. + +Contributing +------------ + +Consult the README.betatester and README.developer files in this directory +if you feel like testing or helping with Hamlib development. + +Contributions of rig specifications and protocol documentation are highly encouraged. Do keep in mind that in some cases the manufacturer may not provide complete control information or it is only available under a Non-Disclosure Agreement (NDA). Any documentation *must* be publicly available so we can legally write and distribute Free Software supporting a given device. -However, if you just want to recompile the library, please refer to the -INSTALL and README.betatester files. - -IMPORTANT: If autoconf or automake are installed on your system, make sure -they are matching *at least* the version shown above. The Hamlib team is -very interested to hear from you, how Hamlib builds and works on your -system, especially on non-Linux system or non-PC systems. We try to make -Hamlib as portable as possible. +The Hamlib team is very interested to hear from you, how Hamlib builds and +works on your system, especially on non-Linux system or non-PC systems. We +try to make Hamlib as portable as possible. Please report in case of problems at hamlib-developer@lists.sourceforge.net -Patches in unified diff format are welcome too! - -Most distributions have the latest Hamlib release in their testing or alpha -versions of their distribution. Check your package manager for the Hamlib -version included in your distribution. - -Take a look at tests/README for more info on simple programming examples and -test programs. +Git email formatted patches or in unified diff format are welcome! Also, take a look at http://sourceforge.net/projects/hamlib/ Here you will -find a mail list, and the latest releases. Feedback, questions, etc. about -Hamlib are very welcome at the mail list: - +find a mail list, link to the Wiki, and the latest releases. Feedback, +questions, etc. about Hamlib are very welcome at the mail list: + + + +Hamlib Version Numbers +---------------------- + +Like other software projects, Hamlib uses a version numbering scheme to help +program authors and users understand which releases are compatible and which +are not. Hamlib releases now follow the format of: + +Major.minor.release.incremental + +Where + +Major: Equals 1 for this C language API implementation of rig +control and won't change. Any successor that is a major code rewrite or +differing implementation would have this number advanced (not too likely). + +Minor: Currently at 2, but can be advanced when changes to the API +require client programs to be rewritten to continue to use Hamlib. This +number has advanced a couple of times throughout the life of Hamlib. +Advancement of the minor number is only for frontend API changes that +require modification of client source. Also indicates ABI compatibility so +that a program linked to an earlier 1.X.Y release will work with a later +1.X.Y release without recompiling. + +Release: This number advances when either new backend(s) or new rig +model(s) to existing backend(s) are added. Advancing this number informs +client program authors (and users of those programs) that new model/backend +support has been added. Will also include bug fixes since the last +Incremental release. + +Incremental: May be undefined (e.g. Hamlib 1.2.14) and would advance to 1 +(e.g. Hamlib 1.2.14.1) for any bug fixes or feature additions to existing +model(s) or backend(s), then to 2, etc. New rig models or backends are not +included in Incremental. When Release is advanced, Incremental will reset +to undefined and will not be included as part of the version number. + +Release schedule +---------------- + +Hamlib has in the past maintained a "ready when it's ready" philosophy. +However, given that much of the Linux user base is now influenced by the +Ubuntu distribution and its timed six month release schedule, Hamlib +releases will be scheduled in advance of Ubuntu releases. Planned release +dates for Hamlib are now 1 February and 1 August of each calendar year. +Between those dates various Incremental releases will occur as development +warrants. + Have Fun / Frank S / Stephane F / The Hamlib Group diff --git a/README.betatester b/README.betatester index 51b15999a..4618f5c48 100644 --- a/README.betatester +++ b/README.betatester @@ -31,14 +31,15 @@ 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 Git repository, then rebuild the Hamlib +out the latest sources from the Git 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 - - POSIXish compiler toolchain (gcc, GNU Autotools, Perl, etc., - see README.developer) + - POSIXish compiler toolchain (gcc, make, C library development headers, + etc., see README.developer for a complete list and building from a Git + checkout) So here we go: @@ -54,33 +55,29 @@ You'll find a tarball with a name like hamlib-1.2.14~git-01db7a3-20110402.tar.gz, i.e. a check out made 02 Apr 2011 With a Git SHA1 of 01db7a3 (The SHA1 is a signature of each commit. Each is unique and as our project is small, the first seven characters for the full -20 character SHA1 are likely unique. The shorthand SHA1 is automatically +40 character SHA1 are likely unique. The shorthand SHA1 is automatically generated and may become longer in the future.), 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 Git snapshot is that you won't need as many tools -installed to build Hamlib as the work of Autoconf, Automake, and Libtool -have already been done. Most of the other packages listed below will be -needed. If you tell the 'configure' script to build certain parts of Hamlib -like documentation or scripting language bindings the relavent optional -packages will be needed. See 'configure --help' for more information. +installed to build Hamlib as the work of the GNU Build System has already +been done. Most of the other packages listed below will be needed. If you +tell the 'configure' script to build certain parts of Hamlib like +documentation or scripting language bindings the relavent optional packages +will be needed. See 'configure --help' for more information. Here is a list of development packages needed for a complete build of the library (Debian package names are listed, other distributions may differ): * Gnu C or any C99 compliant compiler # gcc --version * Gnu make (or any modern one, BSD okay) # make --version -* libtool 2.2.6b # libtool --version -* libltdl-dev 2.2.6b * Git for connection to hamlib.svn.sourceforge.net 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. -N.B. Hamlib requires libtool >= 2.2.6b in compliance with CVE-2009-3736. - Optional, but highly recommended for a complete build: * GNU C++ # g++ --version * swig (for bindings) 1.3.14 # swig -version @@ -106,31 +103,21 @@ Git master branch daily snapshot build: Reading the INSTALL file in top directory will explain in more detail how to do the following commands. - ./configure --disable-static --prefix=/usr/local - make - make install + ./configure --disable-static --prefix=/usr/local + make + make install -The prefix argument is optional. Convention is that local packages be placed -in /usr/local away from distribution installed packages and this is the default -location for the snapshots. The --disable-static option speeds up compilation -if you don't plan to use static libraries (static libraries are usually not -needed). +The prefix argument is optional. Convention is that local packages be +placed in /usr/local away from distribution installed packages This is the +default location for the snapshots so it may be disregarded unless you wish +to install Hamlib elsewhere. The --disable-static option speeds up +compilation if you don't plan to use static libraries (static libraries are +usually not needed). Other useful options are '--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). If unsure it is safe to -ignore these options. - -If you don't want the build files cluttering the source directories, do the -following in the same parent directory of hamlib: - - mkdir build && cd build - ../hamlib/configure --disable-static --prefix=/usr/local - make - make install - -This will keep the binary output files seperate from the source tree. +'--enable-tcl-binding' if you are interested in Swig binding support for +those scripting languages If you are unsure it is safe to ignore these +options. NOTE! If Hamlib has not been previously installed as a locally built package you will need to make sure that 'ldconfig' is configured correctly @@ -146,6 +133,28 @@ If your system does not have such a file, one will need to be created and then 'ldconfig' will need to be run as the root user so that applications using the Hamlib libraries can find them. +To delete the binary files from the source directory after compiling: + + make clean + +To also remove the Makefiles and other build files, along with the binary +files as above: + + make distclean + +The configure script will need to be run again as above. + +The above commands will clean things up so Hamlib can be compiled with other +configure script options. + +To remove Hamlib from your system: + + sudo make uninstall + +Note that due to a limitation in a Perl support script that if the Perl +binding is built and installed that not all of the files under +/usr/local/lib/perl/PERL_VERSION will not be removed. + Git checkout: ============= @@ -217,8 +226,10 @@ Let's say you own an Icom IC-756: rigctl -vvvvv -r /dev/ttyS0 -m 326 The -vvvvv is very important since this will increase verbosity, and give -precious traces to developers if something goes wrong. At this level, -the protocol data exchanged will also be dumped to the screen. +precious traces to developers if something goes wrong. At this level, the +protocol data exchanged will also be dumped to the screen. Some backends +produce a useful amount of data regarding function calls and critical +variables with the -vvvv option without all the protocol data. Unless some problem shows up, you should be presented with a menu like "Rig command: ". Enter "?" followed by return to have the list diff --git a/README.developer b/README.developer index 6b3f7789b..7a1e66394 100644 --- a/README.developer +++ b/README.developer @@ -186,8 +186,7 @@ $ git branch Hamlib-1.2.13 Hamlib-1.2.13.1 * master - n0nb_k3_level - test-mingw32-build + n0nb_k3 there are a number of branches in my local repository. Most, such as "Hamlib-1.2.13", exist in the canonical repository as well. They can be @@ -197,7 +196,9 @@ checkout BRANCH_NAME' command. Finally, once your changes are ready for inclusion in Hamlib, commit your changes to the branch you are working in, checkout the master branch, and use 'git merge' to synchronize your changes into the master branch. Lastly, -push your changes to the canonical repository or email them to +push your changes to the canonical repository (developer write access and +checkout using the SSH protocol required. See +https://sourceforge.net/scm/?type=git&group_id=8305) or email them to hamlib-developer@lists.sourceforge.net for inclusion into Hamlib. @@ -219,7 +220,7 @@ the repository and changes made to any file. 1.2. Requirements Hamlib is entirely developed using GNU tools, under various Linux systems. -Note that it is not restricted to Linux systems. We welcome anyone who +Note that Hamlib is not restricted to Linux systems. We welcome anyone who has access to a POSIXish system to port Hamlib. Contact us for help. That is, if you want to take part in the development of Hamlib, @@ -233,7 +234,7 @@ distributions may differ). * Gnu C or any C99 compliant compiler # gcc --version * Gnu make (or any modern one, BSD okay) # make --version -* autoconf 2.54 # autoconf --version +* autoconf 2.59 # autoconf --version * automake 1.7 # automake --version * libtool 2.2.6b # libtool --version * libltdl-dev 2.2.6b @@ -313,9 +314,7 @@ 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 -default). +Swig binding support for those scripting languages. 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. @@ -540,7 +539,7 @@ 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 from commit logs -(see "git blame"). :-) +(also see "git blame"). :-) Patches should take portability issues into account. Keep in mind Hamlib has to run under: @@ -620,7 +619,8 @@ the RIG_DEBUG_LEVEL values has been somewhat haphazard (at least by this scribe) so fixing these when working in a given backend is encouraged. If an application sets the debugging level to RIG_DEBUG_NONE, then -rig_debug() functions will produce no output. +rig_debug() functions will produce no output. Therefore rig_debug() cannot +be counted on to output a message in all runtime cases. 8.3 Submitting patches