diff --git a/INSTALL b/INSTALL index 6413c1e06..ac8e6f54d 100644 --- a/INSTALL +++ b/INSTALL @@ -17,20 +17,17 @@ main directory and do the following: $ ./configure - If you're planning to install the package into your home directory + If you are planning to install the package into your home directory or to a location other than `/usr/local' then add the flag `--prefix=PATH' to `configure'. For example, if your home directory - is `/home/username' you can configure the package to install itself + is `/home/username' and you would like to install it to a directory + named 'local' you can configure the package to install itself there by invoking: - $ ./configure --prefix=/home/username + $ ./configure --prefix=$HOME/local - 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. + The configure script has several options to configure Hamlib. See the + Optional Features section below. N.B. If you know that you won't need static libaries (most applications dynamically link Hamlib by default) invoke `configure' as follows: @@ -60,6 +57,8 @@ main directory and do the following: Be careful: 'make check' needs an already installed hamlib library. That means that this step has to wait until you finished step 4 (and 5). + TODO: Fix 'make check' to work before installation. + 4. Type `make install' to install the programs and any data files and documentation. Type `make uninstall' to undo the installation. @@ -116,8 +115,8 @@ main directory and do the following: While the programs built along with Hamlib will probably work fine without running `ldconfig', experience has shown that precompiled - binaries like Fldigi will not be able to find libhamlib.so.2 without - updating the ld.so.cache. + binaries like Fldigi will not be able to find a locally compiled + libhamlib.so.2 without updating the ld.so.cache. 6. You can remove the program binaries and object files from the source code directory by typing `make clean'. To also remove the @@ -156,12 +155,11 @@ want to enable or disable various debugging mechanisms: All programs are compiled with optimization level 2 by default (-O2). Occasionally that confuses the debugger when code is inlined. To disable optimization and enable debugging, set the shell environment variables -CFLAGS, CXXFLAGS, FFLAGS to `-g'. On the bash shell, you can do this +CFLAGS, CXXFLAGS. On the bash shell, you can do this like this: $ export CFLAGS="-g" $ export CXXFLAGS="-g" - $ export FFLAGS="-g" On the tcsh shell, use the `setenv' command instead: @@ -197,9 +195,9 @@ be considered for the next release. If at some point `config.cache' contains results you don't want to keep, you may remove or edit it. The file `configure.ac' is used to create `configure' by a program -called `autoconf'. You only need `configure.ac' if you want to change +called `autoreconf'. You only need `configure.ac' if you want to change it or regenerate `configure' using a newer version of `autoconf'. This -project uses a custom `autoconf.sh' for running autoconf in a developer's +project uses a custom `autogen.sh' for running autoreconf in a developer's checkout of Hamlib from a source repository. Advanced installation options. @@ -238,31 +236,57 @@ find the X include and library files automatically, but if it doesn't, you can use the `configure' options `--x-includes=DIR' and `--x-libraries=DIR' to specify their locations. - Win32 ===== - Debian system with mingw32msvc cross-compiler - ./configure --host=i586-mingw32msvc + ./configure --with-included-ltdl --host=i586-mingw32msvc - Mingw compiler under Cygwin - CC="gcc -mno-cygwin" CXX="g++ -mno-cygwin" ./configure --host=i686-pc-mingw32 + CC="gcc -mno-cygwin" CXX="g++ -mno-cygwin" \ + ./configure --with-included-ltdl --host=i686-pc-mingw32 - Cygwin Native Cygwin requires no special options besides regular ones. +N.B. See the 'build-win32.sh' script and its associated README.build-win32 file +in the 'scripts' directory for complete details on build a Win32 binary. -Hamlib specific Features +Hamlib Specific Features ======================== + Various Hamlib features requiring the presence of third party packages are +enabled with options beginning with '--with-'. At this time these options +are: + + --with-xml-support build rigmem with XML support [default=no] + --without-cxx-binding do not build C++ binding and demo [default=yes] + --with-perl-binding build perl binding and demo [default=no] + --with-perl-inc directory containing perl includes + --with-tcl-binding build Tcl binding and demo [default=no] + --with-tcl=PATH directory containing tcl configuration (tclConfig.sh) + --with-python-binding build python binding and demo [default=no] + + Optional features that are disabled by default but may require specialized +hardware are: + + --enable-rigmatrix generate rigmatrix tool (requires libgd) + --disable-winradio do not build winradio backend [default=yes] + --enable-usrp build USRP backend [default=no] + +Bindings notes +-------------- + Should you encounter any problem with the build of the C++ binding, you can disable this optional part by passing `--without-cxx-binding' to the configure script (may happen under MacOSX). - Any problem encountered with the perl, tcl, python or swig tool can be -disabled by passing `--without-tcl-binding', `--without-perl-binding', -and/or '--without-python-binding'. Note that these bindings are disabled -by default. + Note that the Perl, Python, and TCL 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 given and the Swig package is +not installed. Building static libraries can be disabled by use of the `--disable-static' option. This will reduce the installed size of Hamlib considerably. diff --git a/README b/README index e5bde576a..fcf02758f 100644 --- a/README +++ b/README @@ -1,6 +1,6 @@ Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com) (C) Stephane Fillod 2000-2011 - (C) The Hamlib Group 2000-2011 + (C) The Hamlib Group 2000-2012 The purpose of this project is to provide stable, flexible, shared libraries that enable quicker development of Amateur Radio Equipment Control @@ -41,7 +41,9 @@ Frontend Library libhamlib.so - frontend lib that provides generic API for all RIG types. This is what Application - programmers will "see". + programmers will "see". Will have different + names on other platforms, e.g. libhamlib-2.dll + on MS windows. Backend Examples are: --------------------- @@ -129,30 +131,28 @@ 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 +Major.minor.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). +Major: Currently at 3, but can be advanced when changes to the API require +client programs to be rewritten to take advantage of new features of +Hamlib. This number has advanced a couple of times throughout the life of +Hamlib. Advancement of the major number is only for frontend API changes +that require modification of client source. ABI compatibility is presently +maintained to prior releases so that a program linked to an earlier +1.2.Y.[Z] release will work with a later 3.Y[.Z] release without +recompiling. Itis our intention to maintain such ABI compatibility as long +as practical. -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 +Minor: 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 +Incremental: May be undefined (e.g. Hamlib 3.0) and would advance to 1 +(e.g. Hamlib 3.0.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. diff --git a/README.betatester b/README.betatester index f622bb44e..9eb4778d8 100644 --- a/README.betatester +++ b/README.betatester @@ -1,6 +1,6 @@ Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com) (C) Stephane Fillod 2000-2011 - (C) The Hamlib Group 2000-2011 + (C) The Hamlib Group 2000-2012 Why does Hamlib need beta-testers? ================================== @@ -52,8 +52,8 @@ Download the latest Git master branch snapshot from: http://n0nb.users.sourceforge.net 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 +hamlib-3.0~git-30e58df-20121009.tar.gz, i.e. a check out made 09 Oct 2012 +With a Git SHA1 of 30e58df (The SHA1 is a signature of each commit. Each is unique and as our project is small, the first seven characters for the full 40 character SHA1 are likely unique. The shorthand SHA1 is automatically generated and may become longer in the future.), ready for building using @@ -72,7 +72,6 @@ library (Debian package names are listed, other distributions may differ): * Gnu C (gcc) or any C99 compliant compiler # gcc --version * Gnu make (or any modern one, BSD okay) # make --version -* libltdl-dev 2.2.6b+ N.B. The Debian and derivatives (Ubuntu and friends) 'build-essentials' package will install a number of tools and minimize the number of packages @@ -121,10 +120,10 @@ 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 -and run periodically after 'make install'. Most modern distributions have -an /etc/ld.so.conf.d/ directory where local configuration can be made. -Later versions of Debian and derivatives have a file named 'libc.conf' in -this directory. The contents of libc.conf are: +and run after 'make install'. Most modern distributions have an +/etc/ld.so.conf.d/ directory where local configuration can be made. Later +versions of Debian and derivatives have a file named 'libc.conf' in this +directory. The contents of libc.conf are: # libc default configuration /usr/local/lib @@ -137,8 +136,8 @@ 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: +To also remove the Makefiles and other build files generated by 'configure', +along with the binary files as above: make distclean diff --git a/README.developer b/README.developer index e986d81f8..638000b83 100644 --- a/README.developer +++ b/README.developer @@ -1,6 +1,6 @@ Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com) (C) Stephane Fillod 2000-2011 - (C) The Hamlib Group 2000-2011 + (C) The Hamlib Group 2000-2012 Take a look at http://sourceforge.net/projects/hamlib/ Here you will find a mail list, and the latest releases. @@ -28,7 +28,9 @@ Frontend Library libhamlib.so - frontend lib that provides generic API for all RIG types. This is what Application - programmers will "see". + programmers will "see". Will have different + names on other platforms, e.g. libhamlib-2.dll + on MS windows. Backend Examples are: --------------------- @@ -232,8 +234,8 @@ distributions may differ). * Gnu C or any C99 compliant compiler # gcc --version * Gnu make (or any modern one, BSD okay) # make --version -* autoconf 2.59 # autoconf --version -* automake 1.7 # automake --version +* autoconf 2.67 # autoconf --version +* automake 1.11 # automake --version * libtool 2.2.6b+ # libtool --version * libltdl-dev 2.2.6b+ * Git for connection to hamlib.git.sourceforge.net @@ -275,12 +277,12 @@ files, i.e. configure, config.guess, Makefile, etc. Hence after a fresh checkout, you'll have to generate those files. 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, only do this if a problem arises). +AUTOCONF, AUTOMAKE, and LIBTOOLIZE variables with the required versions seen +in the previous section (most systems will be fine with the default names, +only do this if a problem arises and please let us know). cd hamlib - sh ./autogen.sh [--disable-static] [CFLAGS=<"-g -O0">] + sh ./autogen.sh [--disable-static] [CFLAGS="-g -O0"] make make install @@ -288,7 +290,7 @@ 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 - sh ../hamlib/autogen.sh [--disable-static] [CFLAGS=<"-g -O0">] + sh ../hamlib/autogen.sh [--disable-static] [CFLAGS="-g -O0"] make make install @@ -317,14 +319,6 @@ 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. -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 Git master branch snapshot from: - -http://n0nb.users.sourceforge.net - For a Tcl build, add this if needed: --with-tcl=/usr/lib/tcl8.2 @@ -514,10 +508,10 @@ http://www.kernel.org/doc/Documentation/CodingStyle Hamlib is a code base from many contributors and a variety of styles have been employed. If you work on a source file, go ahead and apply good judgment and clean it up per the kernel style guide. Lining things up -nicely with 8 space tabs (use tabs, not spaces) is an excellent start. -Next, put spaces in assignments to aid readability. Align closing braces -with the opening block's keyword. In function definitions put the opening -brace on its own line under the definition's parameter line. +nicely is an excellent start. Next, put spaces in assignments to aid +readability. Align closing braces with the opening block's keyword. In +function definitions put the opening brace on its own line under the +definition's parameter line. Hamlib source code is no place for an entry into the obsfucated C contest! Many of us are hobbyists and write this for fun. Easy to read and @@ -622,7 +616,7 @@ If an application sets the debugging level to RIG_DEBUG_NONE, then rig_debug() functions will produce no output. Therefore rig_debug() cannot be counted on to output a message in all runtime cases. -The debugging levels may be an area for consideration in API_3. +The debugging levels may be an area for consideration in Hamlib 3. 8.3 Submitting patches @@ -633,7 +627,7 @@ to be given to the author and submitter of the patches. Alternately, patches can be submitted in unified format (diff -u), against the Git master branch or a given release (please note well which one!). Both formats make patches easily readable. The patches are to be sent to the hamlib-developer -mailing list ( hamlib-developer@lists.sourceforge.net). If the file is too +mailing list (hamlib-developer@lists.sourceforge.net). If the file is too big, you can send it as a compressed attachment. @@ -642,7 +636,7 @@ big, you can send it as a compressed attachment. Simply summarize your changes when the files are committed to Git 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 commit log (Git -formatted emails will inlcude this already). +formatted emails will include this already). 8.4 Git commit access