1HAMLIB-PRIMER(7) Hamlib Information Manual HAMLIB-PRIMER(7)
2
6 hamlib-primer - compiling and using the radio and rotator control li‐
7 brary
8
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 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 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 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 Getting released source
40 Official Hamlib source releases, commonly called tarballs can be found
41 on the SourceForge.net Hamlib files
42 ⟨http://sourceforge.net/projects/hamlib/files/hamlib/⟩ Web page. The
43 most recent release is listed first.
44 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
49 ⟨http://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 Daily snapshots of the development repository are available via the
54 World Wide Web from Hamlib Git daily snapshots
55 ⟨http://n0nb.users.sourceforge.net/⟩. These are not official releases
56 but are provided for testing new features and bug fixes.
57 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 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 To clone the repository use the following command:
75 git clone https://git.code.sf.net/p/hamlib/code hamlib
77 or:
79 git clone https://github.com/Hamlib/Hamlib.git
81 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 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 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 Let's get started.
116 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 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 ./configure
132 make
133 sudo make install
134 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 Run:
143 ./configure
145 from the top-level directory.
147 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 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 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 ./configure --prefix=$HOME/local
172 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 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 local/bin/rigctl
192 or modifying your shell's PATH environment variable (see the shell tu‐
194 torial site above).
195 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 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 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 Run:
222 make
224 from the top-level directory.
226 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 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 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
241 ⟨http://www.ubuntu.com⟩ family of distributions.
242 Run:
244 sudo make install
246 or:
248 $ su -l
250 Password:
251 # make install
252 as root from the top-level directory.
254 Note: The shell session is shown to show the change in prompt
256 from a normal user account to the root account.
257 The -l option to su forces a login shell so that environment variables
259 such as PATH are set correctly.
260 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 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 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 Run:
278 sudo ldconfig
280 as root from any directory or while logged in as root from above.
282 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 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 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 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 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 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 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 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 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 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 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 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 Run:
355 ../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"
357 from a sibling build directory intended for a debugging build.
359 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 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 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 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 Official releases are available through the SourceForge.net file
381 download service
382 ⟨http://sourceforge.net/projects/hamlib/files/hamlib/⟩.
383 Daily development snapshots are available from the daily snapshots page
385 ⟨http://n0nb.users.sourceforge.net/⟩.
386 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 Daily development snapshots feature both a .ZIP archive and the self
393 extracting installer.
394 Bug reports and questions about these archives should be sent to the
396 hamlib-developer mailing list ⟨hamlib-developer@lists.sourceforge.net⟩.
397
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 Copyright © 2001-2020 Hamlib Group (various contributors)
405 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
411 git(1), hamlib(7), ldconfig(8), make(1), su(1), sudo(8)
412
414 Links to the Hamlib Wiki, Git repository, release archives, and daily
415 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
416Hamlib 2020-09-08 HAMLIB-PRIMER(7)