Provided by: libhamlib-utils_4.5.5-2_amd64 bug

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⟩.