Hamlib/doc/hamlib.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename hamlib.info
@include version.texi
@documentencoding UTF-8
@settitle Ham Radio Control Libraries @value{VERSION}
@c %**end of header

@copying
This manual is for the Ham Radio Control Libraries (version @value{VERSION}
updated @value{UPDATED}), which is a development effort to provide a
consistent programming interface for programmers wanting to incorporate
radio and rotor control into their programs.

Copyright @copyright{} 2013 Nate Bargmann

@quotation
Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.3 or any later
version published by the Free Software Foundation; with no Invariant
Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License''.
@end quotation
@end copying

@dircategory Software libraries
@direntry
* Hamlib: (hamlib).             Ham Radio Control Libraries.
@end direntry

@setchapternewpage odd
@titlepage
@title Ham Radio Control Libraries
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Nate Bargmann, N0NB (@email{n0nb@@n0nb.us})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Ham Radio Control Libraries

This manual is for Ham Radio Control Libraries (Hamlib) (version @value{VERSION},
@value{UPDATED}).
@end ifnottex

@menu
* Copying and Redistribution::
* Hamlib in a Nutshell::
* Getting started::
* GNU Free Documentation License::
* Working with Git::
* List of Figures::
* Concept Index::
@end menu


@node Copying and Redistribution
@unnumbered Copying and Redistribution
@cindex Copying, redistribution
@cindex Redistribution, copying
@cindex Copyleft

This manual documents Hamlib, a programming library and various supplied
programs, which is
@url{http://en.wikipedia.org/wiki/Free_Software_Definition, Free
Software, Free Software}.  Besides often being distributed at no cost to
you, Free in this context means that the copyright holders to Hamlib
have agreed to offer their collective work under terms that give you
certain rights that allow you to modify and/or redistribute Hamlib under
the same terms that you received it from them.

Such licensing is often termed
@url{http://en.wikipedia.org/wiki/Copyleft, copyleft, copyleft} as a
play against the common ``all rights reserved'' terms of normal
@url{http://en.wikipedia.org/wiki/Copyright, copyright, copyright}.  In
general, copyleft provides everyone with a license to modify and
distribute the modified work or to simply distribute a copyrighted work
under certain terms.  Hamlib source code is copyrighted by its authors
and is licensed by them under two common licenses---the
@url{http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License, GNU
Lesser General Public License, GNU Lesser General Public License}
@acronym{LGPL} for the ``front end'' and ``back end'' library source
code files, and the
@url{http://en.wikipedia.org/wiki/GNU_General_Public_License, GNU
General Public License, GNU General Public License} @acronym{GPL} for
the supplied programs source code files.  The full text of the LGPL and
the GPL can be found in the files COPYING.LIB and COPYING in the root
directory of the Hamlib source archive.

This manual is covered by the
@url{http://en.wikipedia.org/wiki/GNU_Free_Documentation_License, GNU
Free Documentation License, GNU Free Documentation License}
@acronym{GFDL} with no Invariant Sections, no Front-Cover Texts, and no
Back-Cover Texts.  Source code examples in this manual are parallel
licensed under the GPL unless otherwise noted.

As part of the Copyleft nature of the licenses, the authors of Hamlib
must forbid you from distributing Hamlib under terms that forbid others
from exercising the same rights you received.  You must give anyone you
distribute Hamlib to the same rights to obtain, modify, and distribute
the Hamlib source code that you received nor may you license Hamlib
under other terms than those you received.  Any recipients of Hamlib
must be informed of the rights to the source code that they have
received.

@cindex NO WARRANTY
Finally, the authors of Hamlib require that it be understood that NO
WARRANTY of any kind is offered to anyone receiving the Hamlib source
code distribution.  Anyone distributing modified versions of Hamlib has
the responsibility to inform any recipients that what they have is not
the official release of Hamlib by its authors and should be prepared to
support the modified version(s).  This is to preserve the reputations of
the Hamlib authors and the Hamlib Project.  While it is not a
requirement of the licenses, it is courteous to offer modifications back
to the Hamlib authors for possible incorporation into their official
release(s).


@c ------------ Chapter ------------
@node Hamlib in a Nutshell
@chapter Hamlib in a Nutshell
@cindex Nutshell

The @dfn{Ham Radio Control Libraries}, @dfn{Hamlib} for short, is a
development effort to provide a consistent interface for programmers
wanting to incorporate radio control in their programs.

Hamlib is not a complete user application, rather, it is a software
layer intended to make controlling various radios and other shack
hardware much easier. Hamlib will allow authors of such software as
logging programs, digital communications programs, or those wanting to
develop the ultimate radio control software to concentrate on the user
interface and the basic function of the program rather than radio
control.  Hamlib consists of several parts, the programming library,
utility programs, and library interfaces to other programming languages.

Most recent amateur radio transceivers allow external control of their
functions through a serial interface. Unfortunately, control commands
are not always consistent across a manufacturer's product line and each
manufacturer's product line differs greatly from its competitors.

Hamlib attempts to solve this problem by presenting a "virtual radio" to
the programmer by providing an interface to actions such as setting a
given VFO's frequency, setting the operating mode, querying the radio of
its current status and settings, and giving the application a list of a
given radio's capabilities. Unfortunately, what can be accomplished by
Hamlib is limited by the radios themselves and some offer very limited
capability.

Other devices, such as antenna rotors, can be placed into the Hamlib
control scheme. Other recent developments include network interface
servers and a USB interface capability. Language bindings are provided
for C, C++, Perl, Python, and TCL (more to come).

@menu
* Overview::
* The Hamlib project::
* Applications using Hamlib::
* Licensing implications::
* Radio cloning::
* Pronunciation::
@end menu

@node Overview
@section A view from the top of the tower
@cindex Overview

@cindex Front end library
@cindex Virtual radio
@cindex Virtual rotor
Hamlib is a @dfn{front end} library providing a @emph{C} language
Application Programming Interface @acronym{API} to programmers wishing
to integrate radio or rotor control in their applications.  Hamlib
presents a @dfn{virtual radio} or @dfn{virtual rotor} that is a
consistent interface to an application despite wide differences in radio
and rotor interfaces and capabilities.

@cindex Back end library
The front end library uses a number of @dfn{back end} libraries to
translate from the front end to the various individual radio and
rotor models.  A back end library handles conversion of the
front end variables to the format needed by the radio or rotor
device it controls.  The back end libraries are generally grouped by
manufacturer and in some cases by a common control protocol.

@quotation
Since a picture is worth quite a few words, here is a visual representation
of Hamlib's design.
@ifhtml
@*@*
@end ifhtml
@float Figure, fig:img1
@image{Hamlib_design,,,Hamlib Design}
@caption{Hamlib design---@i{courtesy of Martin Ewing, AA6E}.}
@shortcaption{Hamlib design}
@end float
@*
@end quotation

@cindex Scripting languages
@cindex Languages, scripting
@cindex Interface, languages
Hamlib also provides an interface library for each of several common
@dfn{scripting} languages such as @url{http://www.perl.org, Perl, Perl},
@url{http://www.python.org, Python, Python}, and @url{http://www.tcl.tk,
TCL, TCL}.  These language @dfn{bindings} are generated through the use
of @url{http://www.swig.org, SWIG, SWIG} a parser/generator for multiple
language interfaces to a C library.  A native generated @emph{C++}
language interface is also provided.

@cindex Daemon, network
@cindex Network, daemon
Besides the C and supplemental APIs, Hamlib also provides a pair of
network daemons that provide a text command based API for controlling
an attached radio or rotor through a @emph{TCP/IP} network connection.
The daemons then handle the interface to the Hamlib C API.

More than one type of device, radio or rotor, may be controlled at a
time, however, there is generally a limit of one device per serial port
or other port.

@node The Hamlib project
@section Hamlib project information
@cindex Hamlib project
@cindex Project, Hamlib

The Hamlib Project was founded by Frank Singleton,VK3FCS/KM5WS in July
2000.  Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib
project and the API and implementation development led to a reasonable
level of maturity in a few years.  A major milestone was reached when
Hamlib 1.2.0 was released in March 2004.  The API and Application
Binary Interface (@acronym{ABI}) interfaces have remained stable since
that time up to the latest release of 1.2.15.3 in late 2012.

Development continues with a bump of the public version number to 3.0
(essentially simply dropping the ``1.'' of previous releases).  While some
API tweaks are planned, ABI compatibility with the prior 1.2.@i{x}
releases remains a priority.  Other goals include streamlining the
build system (done), improving the SWIG generated language bindings
(in progress), improving the overall documentation (this manual, in
progress), and other updates as warranted.

The Project is hosted by @url{https://sourceforge.net/,
SourceForge.net} at the @url{https://sourceforge.net/projects/hamlib/,
Hamlib project page} and the
@url{http://sourceforge.net/apps/mediawiki/hamlib/index.php, Hamlib
Wiki}.

Development discussion and most user support take place on the
@url{https://sourceforge.net/p/hamlib/mailman/, hamlib-developer mailing
list}.  While there are
@url{https://sourceforge.net/p/hamlib/discussion/, SourceForge.net
discussion forums}, they are rarely used and not as closely read by the
developers as the mailing list.

For @dfn{source code management}, the project uses
@url{http://git-scm.com/, Git}, a fast, distributed content tracker.
Among its features is that every developer has the complete Hamlib
development history available locally.  While a canonical Git
repository is hosted as SourceForge, its availability is not essential to
continued development, although development work flows would change
temporarily.  For more information on using Git, @pxref{Working with
Git}.

@quotation Note
The SourceForge.net Web interface to the Hamlib Git repository is
currently broken (a ticket is pending) as of late February, 2013.  A
mirror exists at @url{https://github.com/N0NB/hamlib, GitHub} which
supports browsing via the Web and other Git commands.  Access of the
SF.net repository by other means (SSH or Git protocols) is unaffected
by this issue.
@end quotation

@node Applications using Hamlib
@section Applications using Hamlib
@cindex Hamlib applications
@cindex Applications, using Hamlib

A number of application developers have taken advantage of Hamlib's
capabilities to implement radio and/or rotor control.  While not
exhaustive, a list is maintained at the Hamlib Wiki,
@url{https://sourceforge.net/apps/mediawiki/hamlib/,
Applications/Screenshots}.  Developers are encouraged to request their
applications be added to the gallery by way of the hamlib-developer
mailing list.

@node Licensing implications
@section Using Hamlib with your program
@cindex Hamlib licensing
@cindex Licensing, Hamlib

As with other Free Software projects, Hamlib relies heavily on copyleft
licensing to encourage development contributions and provide an open
atmosphere for development.  Hamlib's source code is released under two
licenses, the @acronym{LGPL} for the library portion, and the
@acronym{GPL} for the utility programs.

The LGPL allows the library to be used (linked) by programs regardless
of their individual license.  However, any contributions to the library
source remain under copyleft which means that the library source code
may not be used in violation of the terms of the LGPL.

The utility program source files are released under the GPL.  Any direct
use of these sources must be in a form that complies with the terms of
the GPL.  Concepts learned by studying these sources for the purpose of
understanding the Hamlib API is not covered nor prohibited by the GPL,
however, directly copying GPL sources into any work that is incompatible
with the terms of the GPL is prohibited.

@xref{Copying and Redistribution}.

@node Radio cloning
@section Radios with a clone capability
@cindex Radio cloning
@cindex Cloning, radio

Hamlib's focus is on controlling rigs that employ a port and command
protocol for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF
transceivers do not employ such control capability but do provide for
cloning the memory contents from radio to another of the same model. A
related project, @url{http://chirp.danplanet.com/, CHIRP}, aims to
support rigs with such a clone capability. Please contact the CHIRP
project for support of such rigs.

@node Pronunciation
@section Pronouncing Hamlib
@cindex Pronouncing Hamlib
@cindex Hamlib, pronouncing

English speakers seem to have two alternate pronunciations for our
project:

@itemize @bullet
@item Hamlib (Ham - lib, long "i", as in library.) IPA style: /'ham læb/
@item Hamlib (Ham - lib, short "i", as in liberty.) IPA style: /'ham lɪb/
@end itemize

Then again, we have people who say Linux "L-eye-nux" and those who say
"L-in-nux"...

If you're French, the above does not apply! :-)


@c ------------ Chapter ------------
@node Getting started
@chapter Getting started

There are several ways to obtain a working installation of Hamlib.  In
the following sections discuss installing from a package manager,
building from source, and installing Hamlib project supplied binaries on
Microsoft Windows@registeredsymbol{}.

@menu
* Unix binary packages::
* Source options::
* Building from source::
* MS Windows 32 binaries::
@end menu

@node Unix binary packages
@section Installing binary packages on Linux and BSD
@cindex Binary packages, Linux, BSD
@cindex Linux binary packages
@cindex BSD binary packages

The easiest way to install a released version of Hamlib on a Linux
based distribution or a BSD variant is through the provided
@dfn{package manager}.  While package managers vary according to the
distribution (it's easy to lump BSD variants in this group too) their
end goal is to provide ready to use software packages.  Since such a
wide variety of package managers exist, it is best to recommend that
the documentation for your chosen distribution be your guide.


@node Source options
@section A variety of Hamlib sources
@cindex Source options

Distribution packages are most often official Hamlib releases and in
some cases could be quite old and lacking support for newer radios or
rotors.  In some cases support is improved in existing radio or rotor
back ends and bugs are fixed in newer releases.  Often times to get
the improved support/bug fixes, building from source will be required.
Relax, it's not hard.  :-)

Source code is available as official releases, testing snapshots,
daily development snapshots, and the bleeding edge of development
directly from the @url{http://git-scm.com/, Git} repository.  As a
rule, even the bleeding edge tarballs should configure and compile
without error even though certain implementation work may be in
progress and may be incomplete or have errors.

@menu
* Source releases::
* Source snapshots::
* Git clone::
@end menu

@node Source releases
@subsection Getting released source
@cindex Getting released source
@cindex Source, getting released
@cindex Source, obtaining releases

Official Hamlib source releases, commonly called @dfn{tarballs} can be
found on the @url{http://sourceforge.net/projects/hamlib/files/hamlib/,
SourceForge.net Hamlib files} Web page.  The most recent release is
listed first.

@node Source snapshots
@subsection Getting source snapshots
@cindex Getting source snapshots
@cindex Source, getting snapshots
@cindex Source, obtaining snapshots
@cindex Source, daily snapshots

Testing release candidates and daily snapshots of the development
repository are available via the World Wide Web from
@url{http://n0nb.users.sourceforge.net/, Hamlib Git daily snapshots}.
These are not official releases but are provided for testing new
features and bug fixes.

Testing release snapshots are only posted for a few weeks before a
planned release.  The daily development snapshot is made and posted
each day by around 1030 UTC.  Daily snapshots @i{should} compile but
sometimes a bug creeps in that prevents compilation.  If that should
happen, please report it to the
@email{hamlib-developer@@lists.sourceforge.net, hamlib-developer
mailing list}.

@node Git clone
@subsection Git repository
@cindex Git repository
@cindex Git clone

The source repository can be @dfn{cloned} which copies the repository
to your computer including its entire history, branches, and release
tag information.  In other words, once the @command{git}
@option{clone} command is finished a complete copy of the Hamlib
development will be on your computer.  You can do quite a lot with
this as nothing is hidden from view since the entire
history of Hamlib is right there all the way from the very first
commit to the present.  None of the meta-data is hidden away on
some central server.

To clone the repository use the following command:

@example
git clone git://git.code.sf.net/p/hamlib/code hamlib
@end example

Odds are that you will want to run the above command in a sub
directory of your home directory.  The @file{hamlib} directory will be
created by Git and the @dfn{master} branch will be checked out for you
as the @dfn{working copy}.  The master branch is one of several
branches used in Hamlib development.  It is the main branch of new
features and bug fixes.  The working copy will be the latest revision
of every file at the time of the clone.  Later updates from the
developers will require using another Git command to update your local
repository.

@xref{Working with Git}.

@node Building from source
@section Building from source
@cindex Building from source
@cindex Source, building from

Building from source will be required for various reasons.  Perhaps
only an older release is provided by your distribution, or you'd like
to test recent changes to Hamlib---either a specific back end or API
changes---and offer a report to the developers, or you'd like to take
part in development and offer your contribution to the project, or
you'd just like to learn how to build a relatively comprehensive
package from source.  Any is a good reason to build from the source
code.

Before going further, this manual assumes familiarity with working
from the command prompt in a Linux/BSD/Unix like system's @dfn{shell}
environment, either in a @dfn{virtual console} (a text only screen
with no graphics) or in a @dfn{terminal} in a desktop environment
(@command{xterm}, @command{rxvt}, @command{konsole},
@command{gnome-terminal}, @command{xfce4-terminal},
@command{terminal}, etc.).  If this is new to you, take some time and
read up on using the shell.  A good tutorial can be found at
@url{http://linuxcommand.org/, LinuxCommand.org} which also offers an
in-depth book that can be purchased or downloaded for no cost (the
Hamlib project is not associated with nor has any interest in the sale
of this book, it just looks like a very good effort on the part of its
author).

Let's get started.

@menu
* Compiling source tarballs::
* Bootstrapping from a Git clone::
* Other make targets::
* Parallel build trees::
* Adding debugging symbols::
* Compiling MS Windows 32::
@end menu

@node Compiling source tarballs
@subsection Compiling source tarballs
@cindex Compiling source tarballs
@cindex Source tarballs, compiling

Before proceeding, it is essential to read the information in the
files, @file{README}, @file{INSTALL}, and @file{README.betatester}
supplied in the Hamlib @dfn{top-level} directory which will be named
something like @file{hamlib-3.0~git} where the latter part is
the release version.  In this case the @samp{3.0~git} indicates this is
a development snapshot of the Git master branch.  These files
provide detailed information for compiling Hamlib and will vary some
from release to release.

Compiling from a source tarball whether it is an official release or
a testing or daily development snapshot follows the same set of commands,
known as the @dfn{three step} which are each run from the top-level
directory:

@example
./configure
make
sudo make install
@end example

@menu
* configure::
* make::
* make install::
* ldconfig::
@end menu

@node configure
@subsubsection @command{configure}
@cindex configure

The @command{./configure} command examines your system and checks it
for any packages that are required or good to have options for
compiling Hamlib.  The leading @file{./} tells the shell to only run
the @command{configure} command found in the current directory.  It's
always possible that a @command{configure} command could be lurking
elsewhere and we don't want to run that!

Run:

@example
@command{./configure}
@end example

from the top-level directory.

@quotation Note
Some distributions are configured so commands can only be run from
directories listed in the @env{PATH} environment variable.  The
@file{./} is necessary or the @command{configure} command will not be
run as the @dfn{current directory} (defined as @file{.}) is not in the
@env{PATH}.  This is considered a default security feature so that
only programs provided by the distribution are run.  @env{PATH} can be
modified for your own session, but that is a topic for the
LinuxCommand.org reference above.
@end quotation

Of course, things are usually complicated a bit by options and Hamlib
is no exception.  The good news is that the defaults, i.e. no options,
work well in most situations.  Options are needed to enable the
compilation of certain portions of Hamlib such as the language
bindings.  Optional features usually require that more development
tools are installed.  The @file{INSTALL}, and @file{README.betatester}
files in the Hamlib top-level directory will have details on the
options available for that release.

A useful option is @samp{--prefix} which tells @command{configure}
where in the file system hierarchy Hamlib should be installed.  If it
is not given, Hamlib will be installed in the @file{/usr/local} file
system hierarchy.  Perhaps you want to install to your home directory
instead:

@example
@command{./configure --prefix=~/local}
@end example

All of the files will be installed in the @file{local} directory of
your home directory.  @file{local} will be created if it does not
exist during installation as will several other directories in it.
Installing in your home directory means that @dfn{root}, or superuser
(administrator) privileges are not required when running @command{make
install}.  On the other hand, some extra work will need to be done so
other programs can use the library.  (TODO: describe this in an
appendix).

Another useful option is @samp{--help} which will give a few screens
full of options for @command{configure}.  If in a desktop environment
the scroll bar can be used to scroll back up through the output.  In
either a terminal or a virtual console Linux supports the
@key{Shift-PageUp} key combination to scroll back up.  As luck would
have it, @key{Shift-PageDown} can be used to scroll down toward the
end of the output and the shell prompt.

After a fair amount of time, depending on your computer, and a lot of
screen output, @command{configure} will finish its job.  So long as
the few lines previous to the shell prompt don't say ``error'' or some
such failure message Hamlib is ready to be compiled.  If there is an
error and all of the required packages listed in
@file{README.betatester} have been installed, please ask for help on
the @email{hamlib-developer@@lists.sourceforge.net, hamlib-developer
mailing list}.

@node make
@subsubsection @command{make}
@cindex make

The @command{make} command is responsible for running the
@dfn{compiler} which reads the source files and from the instructions
it finds in them writes @dfn{object} files which are the binary
instructions the @acronym{CPU} of a computer can execute.
@command{make} then calls the @dfn{linker} which puts the object files
together in the correct order to create the Hamlib library files and
its executable programs.

Run:

@example
@command{make}
@end example

from the top-level directory.

Any error that causes @command{make} to stop early is cause for a
question to the @email{hamlib-developer@@lists.sourceforge.net,
hamlib-developer mailing list}.

In general @command{make} will take longer than @command{configure} to
complete its run.  As it is a system command and therefore found in
the @env{PATH}, prefixing @command{make} with @file{./} will cause a
@samp{command not found} error from the shell.

@node make install
@subsubsection @command{make install}
@cindex make install

Assuming that you have not set the installation prefix to your home
directory, root (administrator) privileges will be required to install
Hamlib to the system directories.  Two popular methods exist for
gaining root privileges, @command{su} and @command{sudo}.
@command{sudo} is probably the most popular these days, particularly
when using the @url{http://www.ubuntu.com, Ubuntu} family of
distributions.

Run:

@example
@command{sudo make install}
@end example

as root from the top-level directory.

Running @command{make install} will call the installer to put all of
the newly compiled files and other files (such as this document) in
predetermined places set by the @samp{--prefix} option to
@command{configure} in the directory hierarchy (yes, this is by design
and @command{make} is not just flinging files any old place!).

A lot of screen output will be generated.  Any errors will probably be
rather early in the process and will likely be related to your
@var{username} not having write permissions in the system directory
structure.

@node ldconfig
@subsubsection @command{ldconfig}
@cindex ldconfig

Once the installation is complete one more step is required if Hamlib
has never been installed from a local build before.  The
@command{ldconfig} command tells the system library loader where to
find the newly installed Hamlib libraries.  It too will need to be run
with root privileges:

Run:

@example
@command{sudo ldconfig}
@end example

as root from any directory.

@quotation Note
Subsequent installations of Hamlib will not need to have
@command{ldconfig} run after each installation so long as no new
backend libraries nor a newer major version of Hamlib were installed.

A developer adding a new backend (see @file{README.developer}) will
need to run @command{ldconfig} for the new back end library to be
found by the library loader (this refers a new back end, i.e. a
sibling to the existing Icom, Kenwood, Yaesu, etc.@: back ends, not a
new model in an existing back end).

Likewise, any time a new back end appears in a source tarball,
@command{ldconfig} will need to be run for the library loader to find
it.  There is no harm running @command{ldconfig} after each run of
@command{make install}.
@end quotation

On some distributions a bit of configuration will be needed before
@command{ldconfig} will add locally compiled software to its database.
Please consult your distribution's documentation.

@node Bootstrapping from a Git clone
@subsection Bootstrapping from a @command{git clone}
@cindex Bootstrapping from a Git clone
@cindex Git clone, bootsrapping

Choosing to build from from a @command{git clone} requires a few more
development tools (notice a theme here?) as detailed in
@file{README.developer}.  The most critical will be the GNU Autotools
(@command{autoconf}, @command{automake}, @command{libtool}, and more)
from which the build system consisting of @file{configure}, the
various @file{Makefile.in}s throughout the directory structure, and
the final @file{Makefile}s are generated.

In the top-level directory is the @command{autogen.sh} script from
which the build system is @dfn{bootsrapped}---the process of building
the Hamlib build system.  At its completion @command{autogen.sh} will
run @command{configure} and will pass any command line arguments it
receives to @command{configure}.  Environment variables intended for
the compiler may also be set on the @command{autogen.sh} command line.

After the configuration is complete, the build may proceed with the
@command{make} step as for the source tarballs above.  Or
@command{configure --help} may be run, and @command{configure} run
again with specific options in which case the @file{Makefile}s will be
regenerated and the build will proceed.

@node Other make targets
@subsection Other @command{make} targets
@cindex Other @command{make} targets
@cindex @command{make}, other targets

Besides @command{make install}, other @dfn{targets} exist when running
@command{make}.  Running @command{make clean} from the top-level
directory removes all of the generated object and executable files
generated by running @command{make} freeing up considerable disk
space.

@quotation Note
During development of individual source files, it is not necessary to
run @command{make clean} each time before @command{make}.  Simply run
@command{make} and only the modified file(s) and any objects that
depend on them will be recompiled.  This speeds up development time
considerably.
@end quotation

To remove even the generated @file{Makefile}s, run @command{make
distclean} from the top-level directory.  After this target is run,
@command{configure} will need to be run again to regenerate the
@file{Makefile}s.  This command may not be as useful as the
@file{Makefile}s do not take up much space.

@node Parallel build trees
@subsection Parallel build trees
@cindex Parallel build trees
@cindex Build, parallel trees

One feature of the GNU build system used by Hamlib is that the object
files can be kept in a directory structure separate from the source
files.  While this has no effect on the @command{make} targets
described above, it does help the developer find files in the source
tree!  One such way of using parallel builds is described in
@file{README.developer}.

Parallel builds can be very useful as one build directory can be
configured for a release and another build directory can be configured
for debugging with different options passed to @command{configure}
from each directory.  The generated @file{Makefile}s are unique to
each build directory and will not interfere with each other.

@node Adding debugging symbols
@subsection Adding debugging symbols
@cindex Adding debugging symbols

When additional debugging symbols are needed with, for example, the
GNU Debugger, @command{gdb}, the needed compiler and linker options
are passed as environment variables.

Run:
@example
@command{../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"}
@end example

from a build directory intended for a debugging build.

The @samp{-ggdb3} option tells the C compiler, this case the GNU C
Compiler, @command{gcc}, to add special symbols useful for
@command{gdb}.  The @samp{-O0} option tells @command{gcc} to turn off
all optimizations which will make it easier to follow some variables
that might otherwise be optimized away.  @samp{CFLAGS} and
@samp{CXXFLAGS} may be set independently for each compiler (sadly, a
bug in the build system source file in Hamlib 1.2.15.3 and earlier did
not preserve @samp{CXXFLAGS}).

@quotation Note
There are a number compiler options available for controlling debugging
symbols and setting optimization levels.  Please consult the compiler's
manual for all the details.
@end quotation

@node Compiling MS Windows 32
@subsection Compiling for MS Windows 32 bit architectures
@cindex Compiling for MS Windows 32
@cindex MS Windows 32, compiling

Currently compiling is done on an Xubuntu 10.10 virtual machine using
@url{http://www.mingw.org/, MinGW32}.  @file{README.build-win32} in
the @file{scripts} directory has details on how this is accomplished.

Work is ongoing to correct build issues in the
@url{http://www.cygwin.com/, Cygwin} environment running on MS
Windows.

@node MS Windows 32 binaries
@section Pre-compiled binaries for MS Windows 32 bit architectures
@cindex Pre-compiled binaries for MS Windows 32
@cindex MS Windows 32, compiled binaries
@cindex MS Windows 32, pre-compiled binaries

Pre-compiled binaries for MS Windows 32 bit architectures (Windows NT
and newer) are available for both official releases and daily
development snapshots.  Official releases are available through the
@url{http://sourceforge.net/projects/hamlib/files/hamlib/,
SourceForge.net file download service}.  Daily development snapshots
are available from @url{http://n0nb.users.sourceforge.net/}.

Beginning with the Hamlib 1.2.15.3 release a self-extracting installer
is available.  Among its features are selecting which portions of
Hamlib are installed.  The @env{PATH} environment variable will need
to be set manually per the included @file{README.win32-bin} file.

Daily development snapshots feature both a .ZIP archive and the self
extracting installer.

Bug reports and questions about these archives should be sent to the
@email{hamlib-developer@@lists.sourceforge.net, hamlib-developer
mailing list}.

@c ----------------- Appendixes start here ------------------


@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi


@node Working with Git
@appendix Working with Git

Git offers a myriad of commands and options.  Fortunately, only a few
are needed for Hamlib development.


@node List of Figures
@unnumbered List of Figures
@listoffloats Figure


@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye