diff --git a/doc/Makefile.am b/doc/Makefile.am index 1a2e16b32..bee60783b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,5 @@ -EXTRA_DIST = hamlib.cfg index.doxygen hamlib.css footer.html +EXTRA_DIST = nutshell.texi getting_started.texi fdl.texi \ + hamlib.cfg index.doxygen hamlib.css footer.html dist_doc_DATA = Hamlib_design.png hamlib.html hamlib.pdf diff --git a/doc/getting_started.texi b/doc/getting_started.texi new file mode 100644 index 000000000..c55b5bf73 --- /dev/null +++ b/doc/getting_started.texi @@ -0,0 +1,497 @@ +There are several ways to obtain a working installation of Hamlib. In +the following sections discuss installing from a package manager, +building from source, and installing Hamlib project supplied binaries on +Microsoft Windows@registeredsymbol{}. + +@menu +* Unix binary packages:: +* Source options:: +* Building from source:: +* MS Windows 32 binaries:: +@end menu + +@node Unix binary packages +@section Installing binary packages on Linux and BSD +@cindex Binary packages, Linux, BSD +@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 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 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, +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 +@subsection Getting released source +@cindex Getting released source +@cindex Source, getting released +@cindex Source, obtaining releases + +Official Hamlib source releases, commonly called @dfn{tarballs} can be +found on the @url{http://sourceforge.net/projects/hamlib/files/hamlib/, +SourceForge.net Hamlib files} Web page. The most recent release is +listed first. + +@node Source snapshots +@subsection Getting source snapshots +@cindex Getting source snapshots +@cindex Source, getting snapshots +@cindex Source, obtaining snapshots +@cindex Source, daily snapshots + +Testing release candidates and daily snapshots of the development +repository are available via the World Wide Web from +@url{http://n0nb.users.sourceforge.net/, Hamlib Git daily snapshots}. +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. 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}. diff --git a/doc/hamlib.texi b/doc/hamlib.texi index bbeb6267f..79bed1ea2 100644 --- a/doc/hamlib.texi +++ b/doc/hamlib.texi @@ -127,727 +127,13 @@ release(s). @chapter Hamlib in a Nutshell @cindex Nutshell -The @dfn{Ham Radio Control Libraries}, @dfn{Hamlib} for short, is a -development effort to provide a consistent interface for programmers -wanting to incorporate radio control in their programs. - -Hamlib is not a complete user application, rather, it is a software -layer intended to make controlling various radios and other shack -hardware much easier. Hamlib will allow authors of such software as -logging programs, digital communications programs, or those wanting to -develop the ultimate radio control software to concentrate on the user -interface and the basic function of the program rather than radio -control. Hamlib consists of several parts, the programming library, -utility programs, and library interfaces to other programming languages. - -Most recent amateur radio transceivers allow external control of their -functions through a serial interface. Unfortunately, control commands -are not always consistent across a manufacturer's product line and each -manufacturer's product line differs greatly from its competitors. - -Hamlib attempts to solve this problem by presenting a "virtual radio" to -the programmer by providing an interface to actions such as setting a -given VFO's frequency, setting the operating mode, querying the radio of -its current status and settings, and giving the application a list of a -given radio's capabilities. Unfortunately, what can be accomplished by -Hamlib is limited by the radios themselves and some offer very limited -capability. - -Other devices, such as antenna rotors, can be placed into the Hamlib -control scheme. Other recent developments include network interface -servers and a USB interface capability. Language bindings are provided -for C, C++, Perl, Python, and TCL (more to come). - -@menu -* Overview:: -* The Hamlib project:: -* Applications using Hamlib:: -* Licensing implications:: -* Radio cloning:: -* Pronunciation:: -@end menu - -@node Overview -@section A view from the top of the tower -@cindex Overview - -@cindex Front end library -@cindex Virtual radio -@cindex Virtual rotor -Hamlib is a @dfn{front end} library providing a @emph{C} language -Application Programming Interface @acronym{API} to programmers wishing -to integrate radio or rotor control in their applications. Hamlib -presents a @dfn{virtual radio} or @dfn{virtual rotor} that is a -consistent interface to an application despite wide differences in radio -and rotor interfaces and capabilities. - -@cindex Back end library -The front end library uses a number of @dfn{back end} libraries to -translate from the front end to the various individual radio and -rotor models. A back end library handles conversion of the -front end variables to the format needed by the radio or rotor -device it controls. The back end libraries are generally grouped by -manufacturer and in some cases by a common control protocol. - -@quotation -Since a picture is worth quite a few words, here is a visual representation -of Hamlib's design. -@ifhtml -@*@* -@end ifhtml -@float Figure, fig:img1 -@image{Hamlib_design,,,Hamlib Design} -@caption{Hamlib design---@i{courtesy of Martin Ewing, AA6E}.} -@shortcaption{Hamlib design} -@end float -@* -@end quotation - -@cindex Scripting languages -@cindex Languages, scripting -@cindex Interface, languages -Hamlib also provides an interface library for each of several common -@dfn{scripting} languages such as @url{http://www.perl.org, Perl, Perl}, -@url{http://www.python.org, Python, Python}, and @url{http://www.tcl.tk, -TCL, TCL}. These language @dfn{bindings} are generated through the use -of @url{http://www.swig.org, SWIG, SWIG} a parser/generator for multiple -language interfaces to a C library. A native generated @emph{C++} -language interface is also provided. - -@cindex Daemon, network -@cindex Network, daemon -Besides the C and supplemental APIs, Hamlib also provides a pair of -network daemons that provide a text command based API for controlling -an attached radio or rotor through a @emph{TCP/IP} network connection. -The daemons then handle the interface to the Hamlib C API. - -More than one type of device, radio or rotor, may be controlled at a -time, however, there is generally a limit of one device per serial port -or other port. - -@node The Hamlib project -@section Hamlib project information -@cindex Hamlib project -@cindex Project, Hamlib - -The Hamlib Project was founded by Frank Singleton,VK3FCS/KM5WS in July -2000. Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib -project and the API and implementation development led to a reasonable -level of maturity in a few years. A major milestone was reached when -Hamlib 1.2.0 was released in March 2004. The API and Application -Binary Interface (@acronym{ABI}) interfaces have remained stable since -that time up to the latest release of 1.2.15.3 in late 2012. - -Development continues with a bump of the public version number to 3.0 -(essentially simply dropping the ``1.'' of previous releases). While some -API tweaks are planned, ABI compatibility with the prior 1.2.@i{x} -releases remains a priority. Other goals include streamlining the -build system (done), improving the SWIG generated language bindings -(in progress), improving the overall documentation (this manual, in -progress), and other updates as warranted. - -The Project is hosted by @url{https://sourceforge.net/, -SourceForge.net} at the @url{https://sourceforge.net/projects/hamlib/, -Hamlib project page} and the -@url{http://sourceforge.net/apps/mediawiki/hamlib/index.php, Hamlib -Wiki}. - -Development discussion and most user support take place on the -@url{https://sourceforge.net/p/hamlib/mailman/, hamlib-developer mailing -list}. While there are -@url{https://sourceforge.net/p/hamlib/discussion/, SourceForge.net -discussion forums}, they are rarely used and not as closely read by the -developers as the mailing list. - -For @dfn{source code management}, the project uses -@url{http://git-scm.com/, Git}, a fast, distributed content tracker. -Among its features is that every developer has the complete Hamlib -development history available locally. While a canonical Git -repository is hosted as SourceForge, its availability is not essential to -continued development, although development work flows would change -temporarily. For more information on using Git, @pxref{Working with -Git}. - -@quotation Note -The SourceForge.net Web interface to the Hamlib Git repository is -currently broken (a ticket is pending) as of late February, 2013. A -mirror exists at @url{https://github.com/N0NB/hamlib, GitHub} which -supports browsing via the Web and other Git commands. Access of the -SF.net repository by other means (SSH or Git protocols) is unaffected -by this issue. -@end quotation - -@node Applications using Hamlib -@section Applications using Hamlib -@cindex Hamlib applications -@cindex Applications, using Hamlib - -A number of application developers have taken advantage of Hamlib's -capabilities to implement radio and/or rotor control. While not -exhaustive, a list is maintained at the Hamlib Wiki, -@url{https://sourceforge.net/apps/mediawiki/hamlib/, -Applications/Screenshots}. Developers are encouraged to request their -applications be added to the gallery by way of the hamlib-developer -mailing list. - -@node Licensing implications -@section Using Hamlib with your program -@cindex Hamlib licensing -@cindex Licensing, Hamlib - -As with other Free Software projects, Hamlib relies heavily on copyleft -licensing to encourage development contributions and provide an open -atmosphere for development. Hamlib's source code is released under two -licenses, the @acronym{LGPL} for the library portion, and the -@acronym{GPL} for the utility programs. - -The LGPL allows the library to be used (linked) by programs regardless -of their individual license. However, any contributions to the library -source remain under copyleft which means that the library source code -may not be used in violation of the terms of the LGPL. - -The utility program source files are released under the GPL. Any direct -use of these sources must be in a form that complies with the terms of -the GPL. Concepts learned by studying these sources for the purpose of -understanding the Hamlib API is not covered nor prohibited by the GPL, -however, directly copying GPL sources into any work that is incompatible -with the terms of the GPL is prohibited. - -@xref{Copying and Redistribution}. - -@node Radio cloning -@section Radios with a clone capability -@cindex Radio cloning -@cindex Cloning, radio - -Hamlib's focus is on controlling rigs that employ a port and command -protocol for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF -transceivers do not employ such control capability but do provide for -cloning the memory contents from radio to another of the same model. A -related project, @url{http://chirp.danplanet.com/, CHIRP}, aims to -support rigs with such a clone capability. Please contact the CHIRP -project for support of such rigs. - -@node Pronunciation -@section Pronouncing Hamlib -@cindex Pronouncing Hamlib -@cindex Hamlib, pronouncing - -English speakers seem to have two alternate pronunciations for our -project: - -@itemize @bullet -@item Hamlib (Ham - lib, long "i", as in library.) IPA style: /'ham læb/ -@item Hamlib (Ham - lib, short "i", as in liberty.) IPA style: /'ham lɪb/ -@end itemize - -Then again, we have people who say Linux "L-eye-nux" and those who say -"L-in-nux"... - -If you're French, the above does not apply! :-) - +@include nutshell.texi @c ------------ Chapter ------------ @node Getting started @chapter Getting started -There are several ways to obtain a working installation of Hamlib. In -the following sections discuss installing from a package manager, -building from source, and installing Hamlib project supplied binaries on -Microsoft Windows@registeredsymbol{}. - -@menu -* Unix binary packages:: -* Source options:: -* Building from source:: -* MS Windows 32 binaries:: -@end menu - -@node Unix binary packages -@section Installing binary packages on Linux and BSD -@cindex Binary packages, Linux, BSD -@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 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 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, -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 -@subsection Getting released source -@cindex Getting released source -@cindex Source, getting released -@cindex Source, obtaining releases - -Official Hamlib source releases, commonly called @dfn{tarballs} can be -found on the @url{http://sourceforge.net/projects/hamlib/files/hamlib/, -SourceForge.net Hamlib files} Web page. The most recent release is -listed first. - -@node Source snapshots -@subsection Getting source snapshots -@cindex Getting source snapshots -@cindex Source, getting snapshots -@cindex Source, obtaining snapshots -@cindex Source, daily snapshots - -Testing release candidates and daily snapshots of the development -repository are available via the World Wide Web from -@url{http://n0nb.users.sourceforge.net/, Hamlib Git daily snapshots}. -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. 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}. +@include getting_started.texi @c ----------------- Appendixes start here ------------------ diff --git a/doc/nutshell.texi b/doc/nutshell.texi new file mode 100644 index 000000000..53b7264f5 --- /dev/null +++ b/doc/nutshell.texi @@ -0,0 +1,218 @@ +The @dfn{Ham Radio Control Libraries}, @dfn{Hamlib} for short, is a +development effort to provide a consistent interface for programmers +wanting to incorporate radio control in their programs. + +Hamlib is not a complete user application, rather, it is a software +layer intended to make controlling various radios and other shack +hardware much easier. Hamlib will allow authors of such software as +logging programs, digital communications programs, or those wanting to +develop the ultimate radio control software to concentrate on the user +interface and the basic function of the program rather than radio +control. Hamlib consists of several parts, the programming library, +utility programs, and library interfaces to other programming languages. + +Most recent amateur radio transceivers allow external control of their +functions through a serial interface. Unfortunately, control commands +are not always consistent across a manufacturer's product line and each +manufacturer's product line differs greatly from its competitors. + +Hamlib attempts to solve this problem by presenting a "virtual radio" to +the programmer by providing an interface to actions such as setting a +given VFO's frequency, setting the operating mode, querying the radio of +its current status and settings, and giving the application a list of a +given radio's capabilities. Unfortunately, what can be accomplished by +Hamlib is limited by the radios themselves and some offer very limited +capability. + +Other devices, such as antenna rotors, can be placed into the Hamlib +control scheme. Other recent developments include network interface +servers and a USB interface capability. Language bindings are provided +for C, C++, Perl, Python, and TCL (more to come). + +@menu +* Overview:: +* The Hamlib project:: +* Applications using Hamlib:: +* Licensing implications:: +* Radio cloning:: +* Pronunciation:: +@end menu + +@node Overview +@section A view from the top of the tower +@cindex Overview + +@cindex Front end library +@cindex Virtual radio +@cindex Virtual rotor +Hamlib is a @dfn{front end} library providing a @emph{C} language +Application Programming Interface @acronym{API} to programmers wishing +to integrate radio or rotor control in their applications. Hamlib +presents a @dfn{virtual radio} or @dfn{virtual rotor} that is a +consistent interface to an application despite wide differences in radio +and rotor interfaces and capabilities. + +@cindex Back end library +The front end library uses a number of @dfn{back end} libraries to +translate from the front end to the various individual radio and +rotor models. A back end library handles conversion of the +front end variables to the format needed by the radio or rotor +device it controls. The back end libraries are generally grouped by +manufacturer and in some cases by a common control protocol. + +@quotation +Since a picture is worth quite a few words, here is a visual representation +of Hamlib's design. +@ifhtml +@*@* +@end ifhtml +@float Figure, fig:img1 +@image{Hamlib_design,,,Hamlib Design} +@caption{Hamlib design---@i{courtesy of Martin Ewing, AA6E}.} +@shortcaption{Hamlib design} +@end float +@* +@end quotation + +@cindex Scripting languages +@cindex Languages, scripting +@cindex Interface, languages +Hamlib also provides an interface library for each of several common +@dfn{scripting} languages such as @url{http://www.perl.org, Perl, Perl}, +@url{http://www.python.org, Python, Python}, and @url{http://www.tcl.tk, +TCL, TCL}. These language @dfn{bindings} are generated through the use +of @url{http://www.swig.org, SWIG, SWIG} a parser/generator for multiple +language interfaces to a C library. A native generated @emph{C++} +language interface is also provided. + +@cindex Daemon, network +@cindex Network, daemon +Besides the C and supplemental APIs, Hamlib also provides a pair of +network daemons that provide a text command based API for controlling +an attached radio or rotor through a @emph{TCP/IP} network connection. +The daemons then handle the interface to the Hamlib C API. + +More than one type of device, radio or rotor, may be controlled at a +time, however, there is generally a limit of one device per serial port +or other port. + +@node The Hamlib project +@section Hamlib project information +@cindex Hamlib project +@cindex Project, Hamlib + +The Hamlib Project was founded by Frank Singleton,VK3FCS/KM5WS in July +2000. Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib +project and the API and implementation development led to a reasonable +level of maturity in a few years. A major milestone was reached when +Hamlib 1.2.0 was released in March 2004. The API and Application +Binary Interface (@acronym{ABI}) interfaces have remained stable since +that time up to the latest release of 1.2.15.3 in late 2012. + +Development continues with a bump of the public version number to 3.0 +(essentially simply dropping the ``1.'' of previous releases). While some +API tweaks are planned, ABI compatibility with the prior 1.2.@i{x} +releases remains a priority. Other goals include streamlining the +build system (done), improving the SWIG generated language bindings +(in progress), improving the overall documentation (this manual, in +progress), and other updates as warranted. + +The Project is hosted by @url{https://sourceforge.net/, +SourceForge.net} at the @url{https://sourceforge.net/projects/hamlib/, +Hamlib project page} and the +@url{http://sourceforge.net/apps/mediawiki/hamlib/index.php, Hamlib +Wiki}. + +Development discussion and most user support take place on the +@url{https://sourceforge.net/p/hamlib/mailman/, hamlib-developer mailing +list}. While there are +@url{https://sourceforge.net/p/hamlib/discussion/, SourceForge.net +discussion forums}, they are rarely used and not as closely read by the +developers as the mailing list. + +For @dfn{source code management}, the project uses +@url{http://git-scm.com/, Git}, a fast, distributed content tracker. +Among its features is that every developer has the complete Hamlib +development history available locally. While a canonical Git +repository is hosted as SourceForge, its availability is not essential to +continued development, although development work flows would change +temporarily. For more information on using Git, @pxref{Working with +Git}. + +@quotation Note +The SourceForge.net Web interface to the Hamlib Git repository is +currently broken (a ticket is pending) as of late February, 2013. A +mirror exists at @url{https://github.com/N0NB/hamlib, GitHub} which +supports browsing via the Web and other Git commands. Access of the +SF.net repository by other means (SSH or Git protocols) is unaffected +by this issue. +@end quotation + +@node Applications using Hamlib +@section Applications using Hamlib +@cindex Hamlib applications +@cindex Applications, using Hamlib + +A number of application developers have taken advantage of Hamlib's +capabilities to implement radio and/or rotor control. While not +exhaustive, a list is maintained at the Hamlib Wiki, +@url{https://sourceforge.net/apps/mediawiki/hamlib/, +Applications/Screenshots}. Developers are encouraged to request their +applications be added to the gallery by way of the hamlib-developer +mailing list. + +@node Licensing implications +@section Using Hamlib with your program +@cindex Hamlib licensing +@cindex Licensing, Hamlib + +As with other Free Software projects, Hamlib relies heavily on copyleft +licensing to encourage development contributions and provide an open +atmosphere for development. Hamlib's source code is released under two +licenses, the @acronym{LGPL} for the library portion, and the +@acronym{GPL} for the utility programs. + +The LGPL allows the library to be used (linked) by programs regardless +of their individual license. However, any contributions to the library +source remain under copyleft which means that the library source code +may not be used in violation of the terms of the LGPL. + +The utility program source files are released under the GPL. Any direct +use of these sources must be in a form that complies with the terms of +the GPL. Concepts learned by studying these sources for the purpose of +understanding the Hamlib API is not covered nor prohibited by the GPL, +however, directly copying GPL sources into any work that is incompatible +with the terms of the GPL is prohibited. + +@xref{Copying and Redistribution}. + +@node Radio cloning +@section Radios with a clone capability +@cindex Radio cloning +@cindex Cloning, radio + +Hamlib's focus is on controlling rigs that employ a port and command +protocol for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF +transceivers do not employ such control capability but do provide for +cloning the memory contents from radio to another of the same model. A +related project, @url{http://chirp.danplanet.com/, CHIRP}, aims to +support rigs with such a clone capability. Please contact the CHIRP +project for support of such rigs. + +@node Pronunciation +@section Pronouncing Hamlib +@cindex Pronouncing Hamlib +@cindex Hamlib, pronouncing + +English speakers seem to have two alternate pronunciations for our +project: + +@itemize @bullet +@item Hamlib (Ham - lib, long "i", as in library.) IPA style: /'ham læb/ +@item Hamlib (Ham - lib, short "i", as in liberty.) IPA style: /'ham lɪb/ +@end itemize + +Then again, we have people who say Linux "L-eye-nux" and those who say +"L-in-nux"... + +If you're French, the above does not apply! :-)