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

NAME

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

COPYING

399       This  file  is part of Hamlib, a project to develop a library that sim‐
400       plifies radio and rotator control functions for developers of  software
401       primarily  of  interest to radio amateurs and those interested in radio
402       communications.
403
404       Copyright © 2001-2020 Hamlib Group (various contributors)
405
406       This is free software; see the file  COPYING  for  copying  conditions.
407       There  is  NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A
408       PARTICULAR PURPOSE.
409

SEE ALSO

411       git(1), hamlib(7), ldconfig(8), make(1), su(1), sudo(8)
412

COLOPHON

414       Links to the Hamlib Wiki, Git repository, release archives,  and  daily
415       snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
416
417
418
419Hamlib                            2020-09-08                  HAMLIB-PRIMER(7)
Impressum