Provided by: libhamlib-utils_4.5.5-2_amd64 
NAME
hamlib-primer - compiling and using the radio and rotator control library
DESCRIPTION
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®
Installing binary packages on Linux and BSD
The easiest way to install a released version of Hamlib on a Linux based distribution or a
BSD variant is through the provided 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.
A variety of Hamlib sources
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 Git repository
⟨https://github.com/Hamlib/Hamlib⟩. 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.
Getting released source
Official Hamlib source releases, commonly called tarballs can be found on the
SourceForge.net Hamlib files ⟨http://sourceforge.net/projects/hamlib/files/hamlib/⟩ Web
page. The most recent release is listed first.
Getting source snapshots
Testing release candidates (RCs) are posted during the period (often a few weeks) before a
planned release. Beginning with the 4.0 release, RCs are hosted by the SourceForge.net
Hamlib files ⟨http://sourceforge.net/projects/hamlib/files/hamlib/⟩ Web page. RCs are
identifed by having a ~rcX suffix where the X is replace by a numeral for successive
release candidates.
Daily snapshots of the development repository are available via the World Wide Web from
Hamlib Git daily snapshots ⟨http://n0nb.users.sourceforge.net/⟩. 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 should compile but sometimes a bug creeps in that prevents compilation. If that
should happen, please report it to the hamlib-developer mailing list ⟨hamlib-
developer@@lists.sourceforge.net⟩.
Git repository
The source repository can be cloned which copies the repository to your computer including
its entire history, branches, and release tag information. In other words, once the
git(1) 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:
git clone https://git.code.sf.net/p/hamlib/code hamlib
or:
git clone https://github.com/Hamlib/Hamlib.git
Odds are that you will want to run the above command in a sub directory of your home
directory. The hamlib directory will be created by Git and the master branch will be
checked out for you as the 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.
Building from source
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
would like to take part in development and offer your contribution to the project, or you
would 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 Bourne shell environment (compatible Bourne shells
include bash(1), ksh(1), zsh(1), and several more) either in a virtual console (a text
only screen with no graphics) or in a terminal in a desktop environment (xterm(1),
rxvt(1), konsole(1) (included with the KDE desktop), gnome-terminal(1), xfce4-terminal(1),
terminal(1) (included in macOS), etc.). If this is new to you, take some time and read up
on using the shell. A good tutorial can be found at LinuxCommand.org
⟨http://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.
Compiling source tarballs
Before proceeding, it is essential to read the information in the files, README.md,
INSTALL, and README.betatester supplied in the Hamlib top-level directory which will be
named something like hamlib-3.3~git where the latter part is the release version. In this
case the 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 three step which are
each run from the top-level directory:
./configure
make
sudo make install
configure
The ./configure command examines your system and checks it for any packages that are
required or good to have options for compiling Hamlib. The leading ./ tells the shell to
only run the configure command found in the current directory. It is always possible that
a configure command could be lurking elsewhere and we don't want to run that!
Run:
./configure
from the top-level directory.
Note: Some distributions are configured so commands can only be run from
directories listed in the PATH environment variable. The ./ is necessary or the
configure command will not be run as the current directory (defined as .) is not
in the PATH. This is considered a default security feature so that only programs
provided by the distribution are run. PATH can be modified for your own session,
but that is a topic for the LinuxCommand.org reference above.
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 INSTALL and README.betatester files in the Hamlib top-level directory will
have details on the options available for that release.
A useful option is --prefix which tells configure where in the file system hierarchy
Hamlib should be installed. If it is not given, Hamlib will be installed in the
/usr/local file system hierarchy. Perhaps you want to install to your home directory
instead:
./configure --prefix=$HOME/local
Note: For practice you may wish to start out using the --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 $HOME/local.
As a result of this option, all of the files will be installed in the local directory of
your home directory. 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 root,
or superuser (administrator) privileges are not required when running make install. On
the other hand, some extra work will need to be done so other programs can use the
library. The utilities that are compiled as a part of the Hamlib build system will work
as they are linked to the library installed under local. Running them will require
declaring the complete path:
local/bin/rigctl
or modifying your shell's PATH environment variable (see the shell tutorial site above).
Another useful option is --help which will give a few screens full of options for
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
Shift-PageUp key combination to scroll back up. Conversely, 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 (terminal
dependent)).
After a fair amount of time, depending on your computer, and a lot of screen output,
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 README.betatester have been
installed, please ask for help on the hamlib-developer mailing list
⟨hamlib-developer@lists.sourceforge.net⟩.
make
The make(1) command is responsible for running the compiler which reads the source files
and from the instructions it finds in them writes object files which are the binary
instructions the CPU of a computer can execute. make then calls the linker which puts the
object files together in the correct order to create the Hamlib library files and its
executable programs.
Run:
make
from the top-level directory.
Any error that causes make to stop early is cause for a question to the hamlib-developer
mailing list ⟨hamlib-developer@lists.sourceforge.net⟩.
In general make will take longer than configure to complete its run. As it is a system
command, and therefore found in the shell's PATH environment variable, prefixing make with
./ will cause a “command not found” error from the shell.
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, su(1) and sudo(8). sudo is
probably the most popular these days, particularly when using the Ubuntu
⟨http://www.ubuntu.com⟩ family of distributions.
Run:
sudo make install
or:
$ su -l
Password:
# make install
as root from the top-level directory.
Note: The shell session is shown to show the change in prompt from a normal user
account to the root account.
The -l option to su forces a login shell so that environment variables such as PATH are
set correctly.
Running 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 --prefix option to
configure in the directory hierarchy (yes, this is by design and 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 username not having write permissions in the
system directory structure.
ldconfig
Once the installation is complete one more step is required if Hamlib has never been
installed from a local build before. The 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:
sudo ldconfig
as root from any directory or while logged in as root from above.
Note: Subsequent installations of Hamlib will not need to have ldconfig run after
each installation if a newer version of Hamlib was not installed, i.e., when
recompiling the same version during development.
On some distributions a bit of configuration will be needed before ldconfig will add
locally compiled software to its database. Please consult your distribution's
documentation.
Bootstrapping from a 'git clone'
Choosing to build from from a git clone requires a few more development tools (notice a
theme here?) as detailed in README.developer. The most critical will be the GNU Autotools
(autoconf, automake, libtool, and more) from which the build system consisting of
configure, the various Makefile.ins throughout the directory structure, and the final
Makefiles are generated.
In the top-level directory is the bootstrap script from which the build system is
bootsrapped—the process of generating the Hamlib build system from configure.ac and the
various Makefile.ams. At its completion the configure script will be present to configure
the build system.
Next configure is run with any needed build options (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
configure command line.
After the configuration is complete, the build may proceed with the make step as for the
source tarballs above. Or configure --help may be run, and configure run again with
specific options in which case the Makefiles will be regenerated and the build can proceed
with the new configuration.
Other make targets
Besides make install, other targets exist when running make. Running make clean from the
top-level directory removes all of the generated object and executable files generated by
running make freeing up considerable disk space.
Note: During development of individual source files, it is not necessary to run
make clean each time before make. Simply run make and only the modified file(s)
and any objects that depend on them will be recompiled. This speeds up development
time considerably.
To remove even the generated Makefiles, run make distclean from the top-level directory.
After this target is run, configure will need to be run again to regenerate the Makefiles.
This command may not be as useful as the Makefiles do not take up much space, however it
can be useful for rebuilding the Makefiles when modifying a Makefile.am or configure.ac
during build system development.
Parallel build 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
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 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 configure from each directory. The generated Makefiles are unique to each build
directory and will not interfere with each other.
Adding debugging symbols
When additional debugging symbols are needed with, for example, the GNU Debugger, gdb, the
needed compiler and linker options are passed as environment variables.
Run:
../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"
from a sibling build directory intended for a debugging build.
The -ggdb3 option tells the C compiler, in this case the GNU C Compiler, gcc, to add
special symbols useful for GDB, the GNU debugger. The -O0 option tells gcc to turn off
all optimizations which will make it easier to follow some variables that might otherwise
be optimized away. CFLAGS and CXXFLAGS may be set independently for each compiler.
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.
Compiling for Microsoft Windows
Currently compiling is done on a Debian 10 (Buster) virtual machine using MinGW
⟨http://www.mingw.org⟩. README.build-win32 in the scripts directory has details on how
this is accomplished.
Pre-compiled binaries for Microsoft Windows
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 SourceForge.net file download service
⟨http://sourceforge.net/projects/hamlib/files/hamlib/⟩.
Daily development snapshots are available from the daily snapshots page
⟨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 PATH
environment variable will need to be set manually per the included README.w32-bin or
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 hamlib-developer
mailing list ⟨hamlib-developer@lists.sourceforge.net⟩.
COPYING
This file is part of Hamlib, a project to develop a library that simplifies radio and
rotator control functions for developers of software primarily of interest to radio
amateurs and those interested in radio communications.
Copyright © 2001-2020 Hamlib Group (various contributors)
This is free software; see the file COPYING for copying conditions. There is NO warranty;
not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO
git(1), hamlib(7), ldconfig(8), make(1), su(1), sudo(8)
COLOPHON
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives
are available via hamlib.org ⟨http://www.hamlib.org⟩.