Hamlib/doc/sgml/intro.sgml

<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:
-->