From 5f8fc0cf6ef803e202def5a38eb903d7cd840229 Mon Sep 17 00:00:00 2001 From: Nate Bargmann Date: Sun, 3 Mar 2013 06:54:18 -0600 Subject: [PATCH] hamlib.texi: Chapter 2 draft Initial draft of chapter 2 of the Hamlib manual. --- doc/hamlib.texi | 459 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 436 insertions(+), 23 deletions(-) diff --git a/doc/hamlib.texi b/doc/hamlib.texi index eb732de86..bbeb6267f 100644 --- a/doc/hamlib.texi +++ b/doc/hamlib.texi @@ -33,7 +33,7 @@ License''. @titlepage @title Ham Radio Control Libraries @subtitle for version @value{VERSION}, @value{UPDATED} -@author Nate Bargmann (@email{n0nb@@n0nb.us}) +@author Nate Bargmann, N0NB (@email{n0nb@@n0nb.us}) @page @vskip 0pt plus 1filll @insertcopying @@ -360,6 +360,7 @@ Microsoft Windows@registeredsymbol{}. * Unix binary packages:: * Source options:: * Building from source:: +* MS Windows 32 binaries:: @end menu @node Unix binary packages @@ -368,33 +369,37 @@ Microsoft Windows@registeredsymbol{}. @cindex Linux binary packages @cindex BSD binary packages -The easiest way to install a released version of Hamlib on a Linux based -distribution or a BSD variant is through the provided @dfn{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 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. +The easiest way to install a released version of Hamlib on a Linux +based distribution or a BSD variant is through the provided +@dfn{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. @node Source options @section A variety of Hamlib sources +@cindex Source options Distribution packages are most often official Hamlib releases and in some cases could be quite old and lacking support for newer radios or -rotors. In some cases support is improved in existing radio or -rotor back ends and bugs are fixed. Often times to get improved -support building from source will be required. Relax, it's not hard. -:-) +rotors. In some cases support is improved in existing radio or rotor +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, and -the bleeding edge of development. As a rule, even the bleeding edge -tarballs should configure and compile without error even though certain -implementation work may be in progress and be incomplete or have errors. +Source code is available as official releases, testing snapshots, +daily development snapshots, and the bleeding edge of development +directly from the @url{http://git-scm.com/, Git} repository. 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. @menu * Source releases:: * Source snapshots:: +* Git clone:: @end menu @node Source releases @@ -421,20 +426,428 @@ repository are available via the World Wide Web from These are not official releases but are provided for testing new features and bug fixes. +Testing release snapshots are only posted for a few weeks before a +planned release. The daily development snapshot is made and posted +each day by around 1030 UTC. Daily snapshots @i{should} compile but +sometimes a bug creeps in that prevents compilation. If that should +happen, please report it to the +@email{hamlib-developer@@lists.sourceforge.net, hamlib-developer +mailing list}. + +@node Git clone +@subsection Git repository +@cindex Git repository +@cindex Git clone + +The source repository can be @dfn{cloned} which copies the repository +to your computer including its entire history, branches, and release +tag information. In other words, once the @command{git} +@option{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: + +@example +git clone git://git.code.sf.net/p/hamlib/code hamlib +@end example + +Odds are that you will want to run the above command in a sub +directory of your home directory. The @file{hamlib} directory will be +created by Git and the @dfn{master} branch will be checked out for you +as the @dfn{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. + +@xref{Working with Git}. @node Building from source @section Building from source @cindex Building from source @cindex Source, building from -Building from source will be required for various reasons including an -older version provided by your distribution, you'd like to test recent -changes to Hamlib---either a specific back end or API changes---and offer -a report to the developers, or you'd like to take part in development -and offer your contribution to the project, of you'd just like to learn -how to build a relatively comprehensive package from source. Let's get -started. +Building from source will be required for various reasons. Perhaps +only an older release is provided by your distribution, or you'd like +to test recent changes to Hamlib---either a specific back end or API +changes---and offer a report to the developers, or you'd like to take +part in development and offer your contribution to the project, or +you'd just like to learn how to build a relatively comprehensive +package from source. Any is a good reason to build from the source +code. +Before going further, this manual assumes familiarity with working +from the command prompt in a Linux/BSD/Unix like system's @dfn{shell} +environment, either in a @dfn{virtual console} (a text only screen +with no graphics) or in a @dfn{terminal} in a desktop environment +(@command{xterm}, @command{rxvt}, @command{konsole}, +@command{gnome-terminal}, @command{xfce4-terminal}, +@command{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 +@url{http://linuxcommand.org/, 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. + +@menu +* Compiling source tarballs:: +* Bootstrapping from a Git clone:: +* Other make targets:: +* Parallel build trees:: +* Adding debugging symbols:: +* Compiling MS Windows 32:: +@end menu + +@node Compiling source tarballs +@subsection Compiling source tarballs +@cindex Compiling source tarballs +@cindex Source tarballs, compiling + +Before proceeding, it is essential to read the information in the +files, @file{README}, @file{INSTALL}, and @file{README.betatester} +supplied in the Hamlib @dfn{top-level} directory which will be named +something like @file{hamlib-3.0~git} where the latter part is +the release version. In this case the @samp{3.0~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 @dfn{three step} which are each run from the top-level +directory: + +@example +./configure +make +sudo make install +@end example + +@menu +* configure:: +* make:: +* make install:: +* ldconfig:: +@end menu + +@node configure +@subsubsection @command{configure} +@cindex configure + +The @command{./configure} command examines your system and checks it +for any packages that are required or good to have options for +compiling Hamlib. The leading @file{./} tells the shell to only run +the @command{configure} command found in the current directory. It's +always possible that a @command{configure} command could be lurking +elsewhere and we don't want to run that! + +Run: + +@example +@command{./configure} +@end example + +from the top-level directory. + +@quotation Note +Some distributions are configured so commands can only be run from +directories listed in the @env{PATH} environment variable. The +@file{./} is necessary or the @command{configure} command will not be +run as the @dfn{current directory} (defined as @file{.}) is not in the +@env{PATH}. This is considered a default security feature so that +only programs provided by the distribution are run. @env{PATH} can be +modified for your own session, but that is a topic for the +LinuxCommand.org reference above. +@end quotation + +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 @file{INSTALL}, and @file{README.betatester} +files in the Hamlib top-level directory will have details on the +options available for that release. + +A useful option is @samp{--prefix} which tells @command{configure} +where in the file system hierarchy Hamlib should be installed. If it +is not given, Hamlib will be installed in the @file{/usr/local} file +system hierarchy. Perhaps you want to install to your home directory +instead: + +@example +@command{./configure --prefix=~/local} +@end example + +All of the files will be installed in the @file{local} directory of +your home directory. @file{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 @dfn{root}, or superuser +(administrator) privileges are not required when running @command{make +install}. On the other hand, some extra work will need to be done so +other programs can use the library. (TODO: describe this in an +appendix). + +Another useful option is @samp{--help} which will give a few screens +full of options for @command{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 +@key{Shift-PageUp} key combination to scroll back up. As luck would +have it, @key{Shift-PageDown} can be used to scroll down toward the +end of the output and the shell prompt. + +After a fair amount of time, depending on your computer, and a lot of +screen output, @command{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 +@file{README.betatester} have been installed, please ask for help on +the @email{hamlib-developer@@lists.sourceforge.net, hamlib-developer +mailing list}. + +@node make +@subsubsection @command{make} +@cindex make + +The @command{make} command is responsible for running the +@dfn{compiler} which reads the source files and from the instructions +it finds in them writes @dfn{object} files which are the binary +instructions the @acronym{CPU} of a computer can execute. +@command{make} then calls the @dfn{linker} which puts the object files +together in the correct order to create the Hamlib library files and +its executable programs. + +Run: + +@example +@command{make} +@end example + +from the top-level directory. + +Any error that causes @command{make} to stop early is cause for a +question to the @email{hamlib-developer@@lists.sourceforge.net, +hamlib-developer mailing list}. + +In general @command{make} will take longer than @command{configure} to +complete its run. As it is a system command and therefore found in +the @env{PATH}, prefixing @command{make} with @file{./} will cause a +@samp{command not found} error from the shell. + +@node make install +@subsubsection @command{make install} +@cindex 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, @command{su} and @command{sudo}. +@command{sudo} is probably the most popular these days, particularly +when using the @url{http://www.ubuntu.com, Ubuntu} family of +distributions. + +Run: + +@example +@command{sudo make install} +@end example + +as root from the top-level directory. + +Running @command{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 @samp{--prefix} option to +@command{configure} in the directory hierarchy (yes, this is by design +and @command{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 +@var{username} not having write permissions in the system directory +structure. + +@node ldconfig +@subsubsection @command{ldconfig} +@cindex ldconfig + +Once the installation is complete one more step is required if Hamlib +has never been installed from a local build before. The +@command{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: + +@example +@command{sudo ldconfig} +@end example + +as root from any directory. + +@quotation Note +Subsequent installations of Hamlib will not need to have +@command{ldconfig} run after each installation so long as no new +backend libraries nor a newer major version of Hamlib were installed. + +A developer adding a new backend (see @file{README.developer}) will +need to run @command{ldconfig} for the new back end library to be +found by the library loader (this refers a new back end, i.e. a +sibling to the existing Icom, Kenwood, Yaesu, etc.@: back ends, not a +new model in an existing back end). + +Likewise, any time a new back end appears in a source tarball, +@command{ldconfig} will need to be run for the library loader to find +it. There is no harm running @command{ldconfig} after each run of +@command{make install}. +@end quotation + +On some distributions a bit of configuration will be needed before +@command{ldconfig} will add locally compiled software to its database. +Please consult your distribution's documentation. + +@node Bootstrapping from a Git clone +@subsection Bootstrapping from a @command{git clone} +@cindex Bootstrapping from a Git clone +@cindex Git clone, bootsrapping + +Choosing to build from from a @command{git clone} requires a few more +development tools (notice a theme here?) as detailed in +@file{README.developer}. The most critical will be the GNU Autotools +(@command{autoconf}, @command{automake}, @command{libtool}, and more) +from which the build system consisting of @file{configure}, the +various @file{Makefile.in}s throughout the directory structure, and +the final @file{Makefile}s are generated. + +In the top-level directory is the @command{autogen.sh} script from +which the build system is @dfn{bootsrapped}---the process of building +the Hamlib build system. At its completion @command{autogen.sh} will +run @command{configure} and will pass any command line arguments it +receives to @command{configure}. Environment variables intended for +the compiler may also be set on the @command{autogen.sh} command line. + +After the configuration is complete, the build may proceed with the +@command{make} step as for the source tarballs above. Or +@command{configure --help} may be run, and @command{configure} run +again with specific options in which case the @file{Makefile}s will be +regenerated and the build will proceed. + +@node Other make targets +@subsection Other @command{make} targets +@cindex Other @command{make} targets +@cindex @command{make}, other targets + +Besides @command{make install}, other @dfn{targets} exist when running +@command{make}. Running @command{make clean} from the top-level +directory removes all of the generated object and executable files +generated by running @command{make} freeing up considerable disk +space. + +@quotation Note +During development of individual source files, it is not necessary to +run @command{make clean} each time before @command{make}. Simply run +@command{make} and only the modified file(s) and any objects that +depend on them will be recompiled. This speeds up development time +considerably. +@end quotation + +To remove even the generated @file{Makefile}s, run @command{make +distclean} from the top-level directory. After this target is run, +@command{configure} will need to be run again to regenerate the +@file{Makefile}s. This command may not be as useful as the +@file{Makefile}s do not take up much space. + +@node Parallel build trees +@subsection Parallel build trees +@cindex Parallel build trees +@cindex Build, parallel 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 @command{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 +@file{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 @command{configure} +from each directory. The generated @file{Makefile}s are unique to +each build directory and will not interfere with each other. + +@node Adding debugging symbols +@subsection Adding debugging symbols +@cindex Adding debugging symbols + +When additional debugging symbols are needed with, for example, the +GNU Debugger, @command{gdb}, the needed compiler and linker options +are passed as environment variables. + +Run: +@example +@command{../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"} +@end example + +from a build directory intended for a debugging build. + +The @samp{-ggdb3} option tells the C compiler, this case the GNU C +Compiler, @command{gcc}, to add special symbols useful for +@command{gdb}. The @samp{-O0} option tells @command{gcc} to turn off +all optimizations which will make it easier to follow some variables +that might otherwise be optimized away. @samp{CFLAGS} and +@samp{CXXFLAGS} may be set independently for each compiler (sadly, a +bug in the build system source file in Hamlib 1.2.15.3 and earlier did +not preserve @samp{CXXFLAGS}). + +@quotation 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. +@end quotation + +@node Compiling MS Windows 32 +@subsection Compiling for MS Windows 32 bit architectures +@cindex Compiling for MS Windows 32 +@cindex MS Windows 32, compiling + +Currently compiling is done on an Xubuntu 10.10 virtual machine using +@url{http://www.mingw.org/, MinGW32}. @file{README.build-win32} in +the @file{scripts} directory has details on how this is accomplished. + +Work is ongoing to correct build issues in the +@url{http://www.cygwin.com/, Cygwin} environment running on MS +Windows. + +@node MS Windows 32 binaries +@section Pre-compiled binaries for MS Windows 32 bit architectures +@cindex Pre-compiled binaries for MS Windows 32 +@cindex MS Windows 32, compiled binaries +@cindex MS Windows 32, pre-compiled binaries + +Pre-compiled binaries for MS Windows 32 bit architectures (Windows NT +and newer) are available for both official releases and daily +development snapshots. Official releases are available through the +@url{http://sourceforge.net/projects/hamlib/files/hamlib/, +SourceForge.net file download service}. Daily development snapshots +are available from @url{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 @env{PATH} environment variable will need +to be set manually per the included @file{README.win32-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 +@email{hamlib-developer@@lists.sourceforge.net, hamlib-developer +mailing list}. @c ----------------- Appendixes start here ------------------