kopia lustrzana https://github.com/Hamlib/Hamlib
294 wiersze
14 KiB
Plaintext
294 wiersze
14 KiB
Plaintext
<chapter id="intro">
|
|
<title>Introduction to Hamlib</title>
|
|
<para>When browsing through the owners manual of that new radio, the pages
|
|
devoted to the computer commands seem like an afterthought. While the
|
|
manufacturers are not interested in becoming software houses, they do
|
|
adequately document the computer control capabilities which allow
|
|
independent control software to be written. With the myriad possibilities
|
|
of radios and manufacturers available, writing that ultimate logging or
|
|
<acronym>PSK31</acronym> application can be a daunting task if even basic
|
|
radio control support is desired. The Ham Radio Control Libraries project
|
|
aims to develop a solution to this problem.</para>
|
|
|
|
<section id="overview">
|
|
<title>Overview of Hamlib</title>
|
|
<para>Hamlib itself is not an end-user application for radio
|
|
control. Rather, it is a collection of libraries, both shared, or
|
|
dynamic linked libraries, if you will, and static libraries that
|
|
provide end-user applications with
|
|
a common means of acessing and controlling radios (and perhaps other
|
|
ham radio related peripheral devices in the future) directly connected
|
|
to a computer or remotely over a network. Hamlib is currently being
|
|
developed on the Linux operating system, but plans include it being
|
|
usable on various flavors of <trademark>UNIX</trademark> and
|
|
<trademark>Windows</trademark>, or whatever platform GNU autoconf
|
|
will support.</para>
|
|
|
|
<para>Hamlib consists of several parts. The application programming
|
|
interface, <acronym>API</acronym>, shared library is
|
|
<filename>libhamlib-&curver;.so</filename> which is installed in
|
|
<filename class="directory">/usr/local/lib</filename> by default.
|
|
For ease of use when linking,
|
|
<filename class="symlink">libhamlib.so</filename> is provided as a
|
|
symbolic link to the latest version of Hamlib installed. Of course,
|
|
the installation directory may be changed by passing the proper
|
|
option to the <command>configure</command> script in the base
|
|
directory of the source distribution. While the static library is
|
|
<filename>libhamlib.a</filename> and installed in <filename
|
|
class="directory">/usr/local/lib</filename> as well.</para>
|
|
|
|
<para>The second main part of Hamlib consists of a number of
|
|
"backend" libraries each able to communicate to a specific radio.
|
|
For example, <filename>libhamlib-ft747.so</filename> is the shared
|
|
backend library that provides Hamlib access to the Yaesu FT-747
|
|
radio. By default the backend libraries are also installed in
|
|
<filename class="directory">/usr/local/lib</filename>. Both shared
|
|
and static libraries are provided by the default
|
|
installation.</para>
|
|
</section>
|
|
|
|
<section id="freesoftware">
|
|
<title>Hamlib is Free Software</title>
|
|
<para>The Hamlib libraries are Free
|
|
Software licensed under the GNU Public License, <acronym>GPL</acronym>,
|
|
version 2. It is important to be aware that use of Hamlib in a
|
|
proprietary program has severe restrictions placed on it by the
|
|
<acronym>GPL</acronym>. As a result one must carefully consider
|
|
what kind of license to use for your program. Of course we
|
|
encourage using the <acronym>GPL</acronym> for your program as it
|
|
adds to the pool of available Free Software to the ham
|
|
community.</para>
|
|
|
|
<para>The advantages of Free Software are multitude, but the primary ones
|
|
include accessability of your code to others who can fix problems or
|
|
add new functionality. Another advantage is that your code is
|
|
always available to be studied by other experimenters and your code
|
|
has a much lower chance of becoming dead bits that can't be used on
|
|
newer operating systems. For an experimenter's hobby like ham
|
|
radio, Free Software offers many more advantages than disadvantages
|
|
to you and the ham community.</para>
|
|
</section>
|
|
|
|
<section id="resources">
|
|
<title>Hamlib development resources</title>
|
|
<para>If you are interested in working on Hamlib development itself,
|
|
there exist a few resources on the World Wide Web. The main project
|
|
page is at <ulink url="http://sourceforge.net/projects/hamlib/">http://sourceforge.net/projects/hamlib/</ulink>.
|
|
A homepage is currently in development at <ulink url="http://hamlib.sourceforge.net">http://hamlib.sourceforge.net</ulink>
|
|
A development mailing list is hosted by <ulink url="http://sourceforge.net">http://sourceforge.net</ulink>. Subscription information and an archive
|
|
can be accessed through the Hamlib project main page.</para>
|
|
</section>
|
|
|
|
<section id="gettinghamlib">
|
|
<title>Getting Hamlib</title>
|
|
<para>At this time Hamlib is not included as a binary package in any
|
|
major distribution that we're aware of (hopefully this will change
|
|
soon). Until then you may retrieve the source from the Hamlib project
|
|
page at <ulink
|
|
url="http://sourceforge.net/projects/hamlib/">http://sourceforge.net/projects/hamlib/</ulink>.</para>
|
|
|
|
<section id="stablever">
|
|
<title>Latest stable version</title>
|
|
<para>The latest stable version is &curver;. Currently the project is
|
|
in its early stages and only a few backend libraries are included.
|
|
Hamlib is currently in heavy development.</para>
|
|
</section>
|
|
|
|
<section id="develver">
|
|
<title>Latest development version</title>
|
|
<para>The latest development code is available via anonymous
|
|
<acronym>CVS</acronym> through the
|
|
<ulink url="http://sourceforge.net/projects/hamlib/">project
|
|
page</ulink>.</para>
|
|
|
|
<section id="anonymouscvs">
|
|
<title>Accessing anonymous CVS</title>
|
|
<para>The following instructions are copied from the
|
|
<ulink url="http://sourceforge.net">Sourceforge</ulink> website
|
|
(modified with hamlib in the right places) and did work for me.</para>
|
|
|
|
<section id="anonymouscvsinstr">
|
|
<title>Anonymous CVS instructions</title>
|
|
<para>Hamlib's SourceForge CVS repository can be checked out through
|
|
anonymous (pserver) CVS with the following instruction set. When
|
|
prompted for a password for <emphasis>anonymous</emphasis>, simply
|
|
press the <keycap>Enter</keycap> key.</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>myhost:~/src $</prompt> <command>cvs -d:pserver:anonymous@cvs.hamlib.\</command>
|
|
<prompt>></prompt> <command>sourceforge.net:/cvsroot/hamlib login</command>
|
|
<prompt>myhost:~/src $</prompt> <command>cvs -z3 -d:pserver:anonymous@cvs.hamlib.\</command>
|
|
<prompt>></prompt> <command>sourceforge.net:/cvsroot/hamlib co hamlib</command>
|
|
</screen>
|
|
|
|
<note><title>Working with long commandlines</title>
|
|
<para>Long commands like those above are difficult to work with
|
|
because once the line wraps the <literal>bash(1)</literal> shell
|
|
seems to start doing weird things. The trick is breaking the line
|
|
into two (or more) parts with the <quote>\</quote> character.
|
|
When the right edge of the screen is reached simply add
|
|
<literal>\</literal> to the end of the text you are typing and
|
|
then press
|
|
<keycap>Enter</keycap>. You will receive a <prompt>></prompt>
|
|
from <literal>bash(1)</literal> and you may continue typing the
|
|
command. If there is no space character in the command you are
|
|
typing, be sure you don't add a space before the <literal>\</literal>
|
|
or at the beginning of the next line. If you break the line where
|
|
a space would exist in the command, either putting the space before
|
|
the <literal>\</literal> or at the beginning of the next line.
|
|
<literal>bash(1)</literal> will splice the lines together to form one
|
|
command once it receives a <keycap>Enter</keycap> character not
|
|
preceded by a <literal>\</literal>.
|
|
</note>
|
|
|
|
<para>Updates from within the hamlib directory do not need the
|
|
<command>-d</command> parameter.</para>
|
|
|
|
<para>If you get the following error:</para>
|
|
<literallayout>cvs login: failed to open /home/user/.cvspass for reading:
|
|
No such file or directory
|
|
cvs [login aborted]: fatal error: exiting
|
|
</literallayout>
|
|
<para>You can probably solve this by using the <command>touch</command>
|
|
command to create the file <literal>.cvspass</literal> in your home
|
|
directory:</para>
|
|
|
|
<screen>
|
|
<prompt>myhost:~ $</prompt> <command>touch .cvspass</command>
|
|
</screen>
|
|
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="building">
|
|
<title>Building Hamlib</title>
|
|
<para>Building Hamlib from source isn't as daunting as it may seem
|
|
at first, thanks to GNU <command>autoconf</command>, a tool used by
|
|
the developers that generates the <command>configure</command>
|
|
script found in the base directory of the source distribution.
|
|
Running <command>configure</command> will test your system to be
|
|
sure that any required packages for building Hamlib are present.
|
|
While <command>configure</command> checks for many components, the
|
|
only critical dependency is that the C library development header
|
|
files are installed. Of course, you'll need a C compiler and its
|
|
associated libraries.</para>
|
|
|
|
<section id="unpacking">
|
|
<title>Unpacking the source archive</title>
|
|
<para>While my favorite method of unpacking
|
|
<filename>.tar.gz</filename> files is to use the Linux version of
|
|
the Swiss Army Knife, Midnight Commander, the instructions
|
|
provided are for using <command>tar</command> at the command
|
|
prompt.</para>
|
|
|
|
<section id="tarunpack">
|
|
<title>Using <command>tar</command> to extract the archive</title>
|
|
<para>The first order of business is choosing a location for the
|
|
source distribution. Some may choose to place the archive under
|
|
<filename class="directory">/usr/local/src</filename>, or may
|
|
prefer to work within their home directory. The disadvantage of
|
|
working in <filename class="directory">/usr/local/src</filename>
|
|
is that one must either be logged in as <literal>root</literal> or
|
|
be a member of a group such as <literal>staff</literal> that has
|
|
write permissions on the directory. The advantage of working in
|
|
one's home directory is that writing and deleting files can be
|
|
done with much lower risk of damage to the system areas of the
|
|
filesystem. Either way, you will need to be logged in as
|
|
<literal>root</literal> to install the libraries after compiling.
|
|
On with unpacking the archive.</para>
|
|
|
|
<para>For this example I will make a few assumptions, the archive
|
|
is downloaded and stored in <filename class="directory">~/Download</filename>
|
|
and the source distribution will be installed in <filename class="directory">~/src</filename>.</para>
|
|
|
|
<note>
|
|
<title>Interpreting <filename class="directory">~</filename></title>
|
|
<para>If you are new to <trademark>UNIX</trademark> type
|
|
systems, you may be puzzled just what <literal>~</literal>
|
|
prepended to a path name means. It is simply a short hand for
|
|
your home directory. If your user name is
|
|
<literal>fred</literal>, then <literal>~</literal> refers to
|
|
<filename class="directory">/home/fred</filename> on most
|
|
systems, of course there are exceptions. If you are logged in
|
|
as <literal>root</literal> then <literal>~</literal> refers to
|
|
<filename class="directory">/root</filename>.</para>
|
|
</note>
|
|
|
|
<para>The following sequence of commands will get the Hamlib
|
|
archive to the right place (substitute your paths in the
|
|
examples). First we'll move the archive into the directory where
|
|
it will be extracted then use the tar command to extract the
|
|
archive into its own directory.</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>myhost:~ $</prompt> <command>mv Download/hamlib-&curver;.tar.gz src</command>
|
|
<prompt>myhost:~ $</prompt> <command>cd src</command>
|
|
<prompt>myhost:~/src $</prompt> <command>tar xvfz hamlib-&curver;.tar.gz</command>
|
|
</screen>
|
|
|
|
<para>Now you should have a directory called <filename class="directory">hamlib-&curver;</filename>
|
|
in the directory you executed the <command>tar</command> command.
|
|
This would be a good time to familiarize yourself with the files in
|
|
the archive.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="compiling">
|
|
<title>Compiling Hamlib</title>
|
|
<para>Thanks to the clever design of GNU <literal>autoconf</literal>
|
|
compiling Hamlib is as easy as running:</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>myhost:~/src/hamlib-&curver; $</prompt> <command>./configure</command>
|
|
</screen>
|
|
|
|
<para>The <literal>configure</literal> script checks for the presence of
|
|
the proper development files required to build Hamlib. After the checks
|
|
<literal>configure</literal> then creates the Makefiles from the
|
|
included templates in the archive. The next step is to compile
|
|
Hamlib:</para>
|
|
|
|
<screen format="linespecific">
|
|
<prompt>myhost:~/src/hamlib-&curver; $</prompt> <command>make</command>
|
|
</screen>
|
|
|
|
<para>Now there should be considerable output to the screen during
|
|
the compile process. The main thing here is to make sure that
|
|
<command>gcc</command> doesn't fail while reporting an error. The most
|
|
common failure is a message saying that a certain file cannot be
|
|
found. Most likely the named file will have a <literal>.h</literal>
|
|
extension which means the development files of a required library
|
|
aren't installed on your system. As of this writing only the glibc
|
|
development files are required.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="summary">
|
|
<title>Summary</title>
|
|
<para>Hamlib is a tool for software authors wishing to take advantage of
|
|
the computer control capabilities of modern transceivers and other
|
|
devices used around the radio shack. When Hamlib reaches maturity
|
|
it will likely be available in your favorite packaging format and
|
|
manually compiling it won't be necessary unless you wish to customize
|
|
Hamlib itself.</para>
|
|
|
|
<para>The remainder of this manual assumes a working knowledge of
|
|
<trademark>UNIX</trademark> type systems. If you are new to Linux,
|
|
I suggest getting a copy of Running Linux by O'Reilly and Associates
|
|
from your local bookstore. You can preview this excellent reference
|
|
on the Web at <ulink url="http://www.oreilly.com/catalog/runux3/">http://www.oreilly.com/catalog/runux3/</ulink>.
|
|
</section>
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("hamlib.sgml" "book" "chapter")
|
|
End:
|
|
-->
|
|
|
|
|
|
|