mirror of
https://github.com/Hamlib/Hamlib.git
synced 2024-09-21 10:27:18 +00:00
Split chapters from hamlib.texi
Make working with the texinfo files more manageable by splitting the large chapters into their own files. Actually include the texinfo files into the source distribution.
This commit is contained in:
Nate Bargmann
parent
5f8fc0cf6e
commit
c7dc2059eb
@ -1,4 +1,5 @@
|
||||
EXTRA_DIST = hamlib.cfg index.doxygen hamlib.css footer.html
|
||||
EXTRA_DIST = nutshell.texi getting_started.texi fdl.texi \
|
||||
hamlib.cfg index.doxygen hamlib.css footer.html
|
||||
|
||||
dist_doc_DATA = Hamlib_design.png hamlib.html hamlib.pdf
|
||||
|
||||
|
||||
497
doc/getting_started.texi
Normal file
497
doc/getting_started.texi
Normal file
@ -0,0 +1,497 @@
|
||||
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}.
|
||||
718
doc/hamlib.texi
718
doc/hamlib.texi
@ -127,727 +127,13 @@ release(s).
|
||||
@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! :-)
|
||||
|
||||
@include nutshell.texi
|
||||
|
||||
@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}.
|
||||
@include getting_started.texi
|
||||
|
||||
@c ----------------- Appendixes start here ------------------
|
||||
|
||||
|
||||
218
doc/nutshell.texi
Normal file
218
doc/nutshell.texi
Normal file
@ -0,0 +1,218 @@
|
||||
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! :-)
|
||||
Loading…
Reference in New Issue
Block a user