1HAMLIB-PRIMER(7)           Hamlib Information Manual          HAMLIB-PRIMER(7)
2
3
4

NAME

6       hamlib-primer  -  compiling  and  using  the  radio and rotator control
7       library
8

DESCRIPTION

10       There are several ways to obtain a working installation of Hamlib.  The
11       following  sections discuss installing from a package manager, building
12       from source, and installing Hamlib project supplied binaries on  Micro‐
13       soft Windows®
14
15   Installing binary packages on Linux and BSD
16       The  easiest  way  to  install  a released version of Hamlib on a Linux
17       based distribution or a BSD variant is  through  the  provided  package
18       manager.   While  package  managers  vary according to the distribution
19       (it's easy to lump BSD variants in this group too) their end goal is to
20       provide  ready  to use software packages.  Since such a wide variety of
21       package managers exist, it is best to recommend that the  documentation
22       for your chosen distribution be your guide.
23
24   A variety of Hamlib sources
25       Distribution  packages  are  most often official Hamlib releases and in
26       some cases could be quite old and lacking support for newer  radios  or
27       rotators.  In some cases support is improved in existing radio or rota‐
28       tor back ends and bugs are fixed in newer releases.  Often times to get
29       the  improved support/bug fixes, building from source will be required.
30       Relax, it's not hard.  :-)
31
32       Source code is available as official releases, testing snapshots, daily
33       development  snapshots,  and  the bleeding edge of development directly
34       from the Git repository ⟨https://github.com/Hamlib/Hamlib⟩.  As a rule,
35       even  the  bleeding  edge tarballs should configure and compile without
36       error even though certain implementation work may be  in  progress  and
37       may be incomplete or have errors.
38
39   Getting released source
40       Official  Hamlib source releases, commonly called tarballs can be found
41       on          the          SourceForge.net          Hamlib          files
42http://sourceforge.net/projects/hamlib/files/hamlib/⟩  Web page.  As a
43       convenience, release archives are also mirrored at  the  GitHub  Hamlib
44       releases  ⟨https://github.com/Hamlib/Hamlib/releases⟩  page.   The most
45       recent release is listed first.
46
47   Getting source snapshots
48       Testing release candidates (RCs) are posted during the period (often  a
49       few  weeks)  before a planned release.  Beginning with the 3.2 release,
50       RCs    are     hosted     by     the     GitHub     release     archive
51https://github.com/Hamlib/Hamlib/releases⟩.  RCs are identifed by hav‐
52       ing a ~rc suffix.
53
54       Daily snapshots of the development repository  are  available  via  the
55       World     Wide     Web     from     Hamlib    Git    daily    snapshots
56http://n0nb.users.sourceforge.net/⟩.  These are not official  releases
57       but are provided for testing new features and bug fixes.
58
59       The  daily  development  snapshot is made and posted each day by around
60       1030 UTC.  Daily snapshots should compile but sometimes a bug creeps in
61       that  prevents compilation.  If that should happen, please report it to
62       the        hamlib-developer        mailing        list         ⟨hamlib-
63       developer@@lists.sourceforge.net⟩.
64
65   Git repository
66       The source repository can be cloned which copies the repository to your
67       computer including its entire history, branches, and release tag infor‐
68       mation.   In  other  words, once the git(1) clone command is finished a
69       complete copy of the Hamlib development will be on your computer.   You
70       can  do  quite a lot with this as nothing is hidden from view since the
71       entire history of Hamlib is right there all the way from the very first
72       commit  to  the  present.  None of the meta-data is hidden away on some
73       central server.
74
75       To clone the repository use the following command:
76
77            git clone https://git.code.sf.net/p/hamlib/code hamlib
78
79       or:
80
81            git clone https://github.com/Hamlib/Hamlib.git
82
83       Odds are that you will want to run the above command in a sub directory
84       of  your  home  directory.  The hamlib directory will be created by Git
85       and the master branch will be checked out for you as the working  copy.
86       The  master  branch  is one of several branches used in Hamlib develop‐
87       ment.  It is the main branch of new features and bug fixes.  The  work‐
88       ing  copy  will be the latest revision of every file at the time of the
89       clone.  Later updates from the developers will  require  using  another
90       Git command to update your local repository.
91
92   Building from source
93       Building  from  source  will  be required for various reasons.  Perhaps
94       only an older release is provided by your distribution,  or  you  would
95       like to test recent changes to Hamlib—either a specific back end or API
96       changes—and offer a report to the developers, or you would like to take
97       part  in development and offer your contribution to the project, or you
98       would just like to learn how to build a relatively comprehensive  pack‐
99       age  from  source.   Any is a good reason to build from the source code
100       archive.
101
102       Before going further, this manual assumes familiarity with working from
103       the command prompt in a Linux/BSD/Unix like system's shell environment,
104       either in a virtual console (a text only screen with no graphics) or in
105       a terminal in a desktop environment (xterm, rxvt, konsole, gnome-termi‐
106       nal, xfce4-terminal, terminal, etc.).  If this is new to you, take some
107       time  and  read up on using the shell.  A good tutorial can be found at
108       LinuxCommand.org ⟨http://linuxcommand.org/⟩ which also  offers  an  in-
109       depth  book that can be purchased or downloaded for no cost (the Hamlib
110       project is not associated with nor has any interest in the sale of this
111       book, it just looks like a very good effort on the part of its author).
112
113       Let's get started.
114
115   Compiling source tarballs
116       Before  proceeding,  it  is  essential  to  read the information in the
117       files, README, INSTALL, and README.betatester supplied  in  the  Hamlib
118       top-level  directory  which will be named something like hamlib-3.3~git
119       where the latter part is the release version.  In this case the 3.3~git
120       indicates  this  is  a  development  snapshot of the Git master branch.
121       These files provide detailed information for compiling Hamlib and  will
122       vary some from release to release.
123
124       Compiling  from a source tarball whether it is an official release or a
125       testing or daily development snapshot follows the same set of commands,
126       known  as  the  three step which are each run from the top-level direc‐
127       tory:
128
129            ./configure
130            make
131            sudo make install
132
133   configure
134       The ./configure command examines your system  and  checks  it  for  any
135       packages  that  are required or good to have options for compiling Ham‐
136       lib.  The leading ./ tells the shell to only run the configure  command
137       found in the current directory.  It is always possible that a configure
138       command could be lurking elsewhere and we don't want to run that!
139
140       Run:
141
142            ./configure
143
144       from the top-level directory.
145
146              Note: Some distributions are configured so commands can only  be
147              run  from  directories  listed in the PATH environment variable.
148              The ./ is necessary or the configure command will not be run  as
149              the  current directory (defined as .)  is not in the PATH.  This
150              is considered a default security feature so that  only  programs
151              provided  by the distribution are run.  PATH can be modified for
152              your own session, but that is a topic for  the  LinuxCommand.org
153              reference above.
154
155       Of  course,  things are usually complicated a bit by options and Hamlib
156       is no exception.  The good news is that the defaults, i.e., no options,
157       work  well in most situations.  Options are needed to enable the compi‐
158       lation of certain portions of Hamlib such  as  the  language  bindings.
159       Optional  features  usually  require  that  more  development tools are
160       installed.  The INSTALL and README.betatester files in the Hamlib  top-
161       level  directory  will  have  details on the options available for that
162       release.
163
164       A useful option is --prefix which tells configure  where  in  the  file
165       system  hierarchy Hamlib should be installed.  If it is not given, Ham‐
166       lib will be installed in the /usr/local file system hierarchy.  Perhaps
167       you want to install to your home directory instead:
168
169            ./configure --prefix=$HOME/local
170
171              Note:  For  practice  you may wish to start out using the --pre‐
172              fix=$HOME/local option to install the  Hamlib  files  into  your
173              home  directory  and  avoid  overwriting  any  version of Hamlib
174              installed into the system directories.  The code examples in the
175              remainder  of  this manual will assume Hamlib has been installed
176              to $HOME/local.
177
178       All of the files will be installed in the local directory of your  home
179       directory.  local will be created if it does not exist during installa‐
180       tion as will several other directories in it.  Installing in your  home
181       directory  means that root, or superuser (administrator) privileges are
182       not required when running make install.  On the other hand, some  extra
183       work will need to be done so other programs can use the library.
184
185       Another  useful  option is --help which will give a few screens full of
186       options for configure.  If in a desktop environment the scroll bar  can
187       be  used to scroll back up through the output.  In either a terminal or
188       a virtual console Linux supports the Shift-PageUp  key  combination  to
189       scroll  back up.  Conversely, Shift-PageDown can be used to scroll down
190       toward the  end  of  the  output  and  the  shell  prompt  (Shift-UpAr‐
191       row/Shift-DownArrow may also work to scroll one line at a time).
192
193       After  a  fair amount of time, depending on your computer, and a lot of
194       screen output, configure will finish its job.  So long as the few lines
195       previous  to  the  shell  prompt don't say “error” or some such failure
196       message Hamlib is ready to be compiled.  If there is an error  and  all
197       of   the  required  packages  listed  in  README.betatester  have  been
198       installed, please ask for help on  the  hamlib-developer  mailing  list
199       ⟨hamlib-developer@@lists.sourceforge.net⟩.
200
201   make
202       The make(1) command is responsible for running the compiler which reads
203       the source files and from the instructions  it  finds  in  them  writes
204       object  files  which  are the binary instructions the CPU of a computer
205       can execute.  make then calls the linker which puts  the  object  files
206       together  in  the  correct order to create the Hamlib library files and
207       its executable programs.
208
209       Run:
210
211            make
212
213       from the top-level directory.
214
215       Any error that causes make to stop early is cause for a question to the
216       hamlib-developer                      mailing                      list
217       ⟨hamlib-developer@@lists.sourceforge.net⟩.
218
219       In general make will take longer than configure to  complete  its  run.
220       As  it  is a system command, and therefore found in the PATH, prefixing
221       make with ./ will cause a “command not found” error from the shell.
222
223   make install
224       Assuming that you have not set the installation  prefix  to  your  home
225       directory,  root (administrator) privileges will be required to install
226       Hamlib to the system directories.  Two popular methods exist for  gain‐
227       ing root privileges, su(1) and sudo(8).  sudo is probably the most pop‐
228       ular   these    days,    particularly    when    using    the    Ubuntu
229http://www.ubuntu.com⟩ family of distributions.
230
231       Run:
232
233            sudo make install
234
235       as root from the top-level directory.
236
237       Running  make  install  will call the installer to put all of the newly
238       compiled files and other files (such as this document) in predetermined
239       places set by the --prefix option to configure in the directory hierar‐
240       chy (yes, this is by design and make is not just flinging files any old
241       place!).
242
243       A  lot of screen output will be generated.  Any errors will probably be
244       rather early in the process and will likely be related to your username
245       not having write permissions in the system directory structure.
246
247   ldconfig
248       Once  the  installation is complete one more step is required if Hamlib
249       has never been installed from a local build before.  The ldconfig  com‐
250       mand  tells the system library loader where to find the newly installed
251       Hamlib libraries.  It too will need to be run with root privileges:
252
253       Run:
254
255            sudo ldconfig
256
257       as root from any directory.
258
259       Note: Subsequent installations of Hamlib will not need to have ldconfig
260       run  after  each  installation  if  a  newer  version of Hamlib was not
261       installed, i.e. when recompiling the same version during development.
262
263       On some distributions a bit of  configuration  will  be  needed  before
264       ldconfig  will  add  locally compiled software to its database.  Please
265       consult your distribution's documentation.
266
267   Bootstrapping from a 'git clone'
268       Choosing to build from from a git clone requires a few more development
269       tools (notice a theme here?) as detailed in README.developer.  The most
270       critical will be the GNU Autotools (autoconf,  automake,  libtool,  and
271       more)  from which the build system consisting of configure, the various
272       Makefile.ins throughout the directory structure, and  the  final  Make‐
273       files are generated.
274
275       In the top-level directory is the bootstrap script from which the build
276       system is bootsrapped—the process of generating the Hamlib build system
277       from  configure.ac and the various Makefile.ams.  At its completion the
278       configure script will be present to configure the build system.
279
280       Next configure is run with any needed build options  (configure  --help
281       is  useful)  to  enable  certain features or provide paths for locating
282       needed build dependencies, etc.  Environment variables intended for the
283       preprocessor  and/or  compiler may also be set on the configure command
284       line.
285
286       After the configuration is complete, the build  may  proceed  with  the
287       make step as for the source tarballs above.  Or configure --help may be
288       run, and configure run again with specific options in  which  case  the
289       Makefiles  will  be  regenerated and the build can proceed with the new
290       configuration.
291
292   Other make targets
293       Besides make install, other targets exist when running  make.   Running
294       make  clean  from  the top-level directory removes all of the generated
295       object and executable files generated by running make freeing  up  con‐
296       siderable disk space.
297
298       Note:  During  development of individual source files, it is not neces‐
299       sary to run make clean each time before make.  Simply run make and only
300       the modified file(s) and any objects that depend on them will be recom‐
301       piled.  This speeds up development time considerably.
302
303       To remove even the generated Makefiles, run  make  distclean  from  the
304       top-level  directory.  After this target is run, configure will need to
305       be run again to regenerate the Makefiles.  This command may not  be  as
306       useful  as  the  Makefiles do not take up much space, however it can be
307       useful for rebuilding the Makefiles when  modifying  a  Makefile.am  or
308       confgure.ac during build system development.
309
310   Parallel build trees
311       One  feature  of the GNU build system used by Hamlib is that the object
312       files can be kept in a directory structure  separate  from  the  source
313       files.   While  this has no effect on the make targets described above,
314       it does help the developer find files in the source tree!  One such way
315       of using parallel builds is described in README.developer.
316
317       Parallel  builds  can be very useful as one build directory can be con‐
318       figured for a release and another build directory can be configured for
319       debugging  with  different options passed to configure from each direc‐
320       tory.  The generated Makefiles are unique to each build  directory  and
321       will not interfere with each other.
322
323   Adding debugging symbols
324       When additional debugging symbols are needed with, for example, the GNU
325       Debugger, gdb, the needed compiler and linker  options  are  passed  as
326       environment variables.
327
328       Run:
329
330            ../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"
331
332       from a sibling build directory intended for a debugging build.
333
334       The  -ggdb3  option  tells  the C compiler, in this case the GNU C Com‐
335       piler, gcc, to add special symbols useful for GDB,  the  GNU  debugger.
336       The  -O0 option tells gcc to turn off all optimizations which will make
337       it easier to follow some variables that might  otherwise  be  optimized
338       away.  CFLAGS and CXXFLAGS may be set independently for each compiler.
339
340       Note:  There  are  a  number compiler options available for controlling
341       debugging symbols and setting optimization levels.  Please consult  the
342       compiler's manual for all the details.
343
344   Compiling for Microsoft Windows
345       Currently  compiling  is  done  on  a Debian 8 (Jessie) virtual machine
346       using MinGW ⟨http://www.mingw.org⟩.  README.build-win32 in the  scripts
347       directory has details on how this is accomplished.
348
349   Pre-compiled binaries for Microsoft Windows
350       Pre-compiled binaries for Microsoft Windows 32 and 64 bit architectures
351       (Windows NT and newer) are available for  both  official  releases  and
352       daily  development  snapshots.  Official releases are available through
353       the        SourceForge.net        file         download         service
354http://sourceforge.net/projects/hamlib/files/hamlib/⟩.  As an alterna‐
355       tive, official releases are also available though the Hamlib archive at
356       GitHub  ⟨https://github.com/Hamlib/Hamlib/releases⟩.  Daily development
357       snapshots   are   available   from    the    daily    snapshots    page
358http://n0nb.users.sourceforge.net/⟩.
359
360       Beginning  with the Hamlib 1.2.15.3 release a self-extracting installer
361       is available.  Among its features are selecting which portions of  Ham‐
362       lib  are  installed.  The PATH environment variable will need to be set
363       manually per the included README.w32-bin or README.w64-bin file.
364
365       Daily development snapshots feature both a .ZIP archive  and  the  self
366       extracting installer.
367
368       Bug  reports  and  questions about these archives should be sent to the
369       hamlib-developer            mailing            list            ⟨hamlib-
370       developer@@lists.sourceforge.net⟩.
371

COPYING

373       This  file  is part of Hamlib, a project to develop a library that sim‐
374       plifies radio and rotator control functions for developers of  software
375       primarily  of  interest to radio amateurs and those interested in radio
376       communications.
377
378       Copyright © 2001-2018 Hamlib Group (various contributors)
379
380       This is free software; see the file  COPYING  for  copying  conditions.
381       There  is  NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A
382       PARTICULAR PURPOSE.
383

SEE ALSO

385       git(1), hamlib(7), ldconfig(8), make(1), su(1), sudo(8)
386

COLOPHON

388       Links to the Hamlib Wiki, Git repository, release archives,  and  daily
389       snapshot archives:
390
391              hamlib.org ⟨http://www.hamlib.org⟩.
392
393
394
395Hamlib                            2018-05-27                  HAMLIB-PRIMER(7)
Impressum