hamlib.texi: Chapter 2 draft

Initial draft of chapter 2 of the Hamlib manual.

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 ------------------