Provided by: libhamlib-utils_3.3-5_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.  As a convenience, release archives are also mirrored at the GitHub Hamlib  releases
       ⟨https://github.com/Hamlib/Hamlib/releases⟩  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 3.2 release, RCs are hosted by the GitHub release
       archive ⟨https://github.com/Hamlib/Hamlib/releases⟩.  RCs are identifed by  having  a  ~rc
       suffix.

       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 shell environment, either in a virtual console (a text
       only screen with no graphics) or in a terminal in  a  desktop  environment  (xterm,  rxvt,
       konsole,  gnome-terminal,  xfce4-terminal,  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
       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,  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.

       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.

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

       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 PATH, 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

       as root from the top-level directory.

       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.

       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 confgure.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  8  (Jessie)  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/⟩.   As  an   alternative,   official
       releases    are    also    available    though    the    Hamlib    archive    at    GitHub
       ⟨https://github.com/Hamlib/Hamlib/releases⟩.  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-2018 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:

              hamlib.org ⟨http://www.hamlib.org⟩.