Hamlib/doc/getting_started.texi

There are several ways to obtain a working installation of Hamlib.
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::
* Microsft Windows 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
rotators.  In some cases support is improved in existing radio or
rotator 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{https://github.com/Hamlib/Hamlib, 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.  As a convenience, release
archives are also mirrored at the
@url{https://github.com/Hamlib/Hamlib/releases, GitHub Hamlib
releases} 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
@cindex Source, release candidates
@cindex Source, RC

Testing release candidates (RCs) are posted during the period (often a
few weeks) before a planned release.  Beginning with the 3.2 release,
RCs are hosted by the @url{https://github.com/Hamlib/Hamlib/releases,
GitHub release archive}.  RCs are identifed by having a @i{~rc}
suffix.

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.

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

or:

@example
git clone https://github.com/Hamlib/Hamlib.git
@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 would
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 archive.

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 Microsoft Windows::
@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.3~git} where the latter part is the
release version.  In this case the @samp{3.3~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 is
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=$HOME/local}
@end example

@quotation Note
For practice you may wish to start out using the
@samp{--prefix=$HOME/local} option to install the Hamlib files into
your home directory and avoid overwriting any version of Hamlib
installed into the system directories.  The code examples in the
remainder of this manual will assume Hamlib has been installed to
@samp{$HOME/local}.
@end quotation

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.

@ignore
(TODO: describe library hackery in an appendix).
@end ignore

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.  Converesely
@key{Shift-PageDown} can be used to scroll down toward the end of the
output and the shell prompt (Shift-UpArrow/Shift-DownArrow may also
work to scroll one line at a time).

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 if a newer major
version of Hamlib was not installed, i.e. when recompiling the same
version during development.
@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{bootstrap} script from
which the build system is @dfn{bootsrapped}---the process of
generating the Hamlib build system from @file{configure.ac} and the
various @file{Makefile.am}s.  At its completion the
@command{configure} script will be present to configure the build
system.

Next @command{configure} is run with any needed build options
(@command{configure --help} is useful) to enable certain features or
provide paths for locating needed build dependencies, etc.
Environment variables intended for the preprocessor and/or compiler
may also be set on the @command{configure} 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 can proceed with the new configuration.

@xref{configure}.

@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, however it can be useful
for rebuilding the @file{Makefile}s when modifying a
@file{Makefile.am} or @file{confgure.ac} during build system
development.

@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 sibling 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 GDB, the
GNU debugger.  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.

@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 Microsoft Windows
@subsection Compiling for Microsoft Windows
@cindex Compiling for Microsoft Windows
@cindex Microsoft Windows, compiling

Currently compiling is done on a Debian 8 (Jessie) virtual machine
using @url{http://www.mingw.org/, MinGW}.  @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 Microsft Windows binaries
@section Pre-compiled binaries for Microsoft Windows
@cindex Pre-compiled binaries for Microsoft Windows
@cindex Microsoft Windows, compiled binaries
@cindex Microsoft Windows, pre-compiled binaries

Pre-compiled binaries for Microsoft Windows 32 and 64 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}.  As an alternative, official
releases are also available though the
@url{https://github.com/Hamlib/Hamlib/releases, Hamlib archive at
GitHub}.  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.w32-bin} or
@file{README.w64-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}.