Hamlib/doc/sgml/intro.sgml

294 wiersze
14 KiB
Plaintext
Czysty Zwykły widok Historia

<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>&gt;</prompt> <command>sourceforge.net:/cvsroot/hamlib login</command>
<prompt>myhost:~/src $</prompt> <command>cvs -z3 -d:pserver:anonymous@cvs.hamlib.\</command>
<prompt>&gt;</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>&gt;</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:
-->