1HAMLIB-PRIMER(7) Hamlib Information Manual HAMLIB-PRIMER(7)
2
6 hamlib-primer - compiling and using the radio and rotator control
7 library
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. 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 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
51 ⟨https://github.com/Hamlib/Hamlib/releases⟩. RCs are identifed by hav‐
52 ing a ~rc suffix.
53 Daily snapshots of the development repository are available via the
55 World Wide Web from Hamlib Git daily snapshots
56 ⟨http://n0nb.users.sourceforge.net/⟩. These are not official releases
57 but are provided for testing new features and bug fixes.
58 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 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 To clone the repository use the following command:
76 git clone https://git.code.sf.net/p/hamlib/code hamlib
78 or:
80 git clone https://github.com/Hamlib/Hamlib.git
82 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 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 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 Let's get started.
114 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 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 ./configure
130 make
131 sudo make install
132 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 Run:
141 ./configure
143 from the top-level directory.
145 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 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 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 ./configure --prefix=$HOME/local
170 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 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 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 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 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 Run:
210 make
212 from the top-level directory.
214 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 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 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
229 ⟨http://www.ubuntu.com⟩ family of distributions.
230 Run:
232 sudo make install
234 as root from the top-level directory.
236 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 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 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 Run:
254 sudo ldconfig
256 as root from any directory.
258 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 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 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 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 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 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 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 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 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 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 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 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 Run:
329 ../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"
331 from a sibling build directory intended for a debugging build.
333 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 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 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 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
354 ⟨http://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
358 ⟨http://n0nb.users.sourceforge.net/⟩.
359 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 Daily development snapshots feature both a .ZIP archive and the self
366 extracting installer.
367 Bug reports and questions about these archives should be sent to the
369 hamlib-developer mailing list ⟨hamlib-
370 developer@@lists.sourceforge.net⟩.
371
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 Copyright © 2001-2018 Hamlib Group (various contributors)
379 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
385 git(1), hamlib(7), ldconfig(8), make(1), su(1), sudo(8)
386
388 Links to the Hamlib Wiki, Git repository, release archives, and daily
389 snapshot archives:
390 hamlib.org ⟨http://www.hamlib.org⟩.
392Hamlib 2018-05-27 HAMLIB-PRIMER(7)