README.developer

Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
         (C) Stephane Fillod 2000-2011
         (C) The Hamlib Group 2000-2013

Take a look at http://sourceforge.net/projects/hamlib/
Here you will find a mail list, and the latest releases.

See README for frontend/backend outline.
See README.betatester for background on testing Hamlib.


The library provides functions for both radio and rotator control,
and data retrieval from the radio or rotator.  A number of functions useful
for calculating distance and bearing and grid square conversion are included.

libhamlib.so -  library that provides generic API for all RIG types.
    This is what Application programmers will "see".  Will have different
    names on other platforms, e.g. libhamlib-2.dll on MS windows.  Also
    contains all radio and rotator "backends" (formerly in their own
    dlopen'ed libraries) provided by Hamlib.

Backend Examples are:
---------------------

1. yaesu will provide connectivity to Yaesu FT 747GX Transceiver, FT 847
   "Earth Station", etc. via a standard API.

2. xxxx. will provide connectivity to the Wiz-bang moon-melter 101A (yikes..)

Hamlib also enables developers to develop professional looking
GUI's towards a standard control library API, and they would not have
to worry about the underlying connection towards physical hardware.

Serial (RS232) connectivity is built in as are RPC, IP (also via a socket
utility), and USB.  Other connectivity will follow afterwards.


General Guidelines.
-------------------

0. The top level directory looks like this as of 07 May 2013
(Note, it has grown considerably).

$ tree -d -I .git
.
├── adat
├── alinco
├── amsat
├── android
├── aor
├── ars
├── bindings
├── c++
├── celestron
├── doc
├── drake
├── dummy
├── easycomm
├── flexradio
├── fodtrack
├── gnuradio
├── gs232a
├── heathkit
├── icom
├── include
│   └── hamlib
├── jrc
├── kachina
├── kenwood
├── kit
├── kylix
│   └── tests
├── lib
├── lowe
├── m2
├── macros
├── microtune
├── miniVNA
├── pcr
├── perl
├── prm80
├── racal
├── rft
├── rotorez
├── rs
├── sartek
├── scripts
├── skanti
├── spid
├── src
├── tapr
├── tentec
├── tests
│   ├── config
│   ├── rigctl.test
│   ├── testbcd.test
│   ├── testfreq.test
│   └── testloc.test
├── ts7400
│   └── include
├── tuner
├── uniden
├── winradio
│   └── linradio
├── wj
└── yaesu

61 directories


1. Building

If you just want to recompile the library, please refer to the INSTALL
file.  This document introduces hacking the code of Hamlib.


1.1 Obtaining sources: git clone

  git clone git://git.code.sf.net/p/hamlib/code hamlib

The clone has to only be done the first time.

After the initial clone, whenever you want to update your local
repository, issue the following command in the root directory of Hamlib:

  git pull

This will download and merge any changes from the canonical Hamlib Git
repository (what Git calls origin by default).  This command actually
combines two Git commands, fetch and merge into one that will first check
for conflicting changes between your local repository and the remote
(origin) repository and will not apply any changes if conflicts are found.

A pull can be restricted to just a single branch if desired:

  git pull origin master


1.1.1 Obtaining more info on Git

Check out the Source Forge page at
https://sourceforge.net/scm/?type=git&group_id=8305 for more information
about how to use the Git repository of Hamlib.

Much documentation on Git exists.  A good starting point is:

http://git-scm.com/documentation

From this page are links to tutorials, books (Pro Git proved useful for me),
and references (http://gitref.org/ is another good resource).

Another site:

http://www-cs-students.stanford.edu/~blynn/gitmagic/


1.1.2 Providing patches with Git

Git provides tools to generate patches and submit them to the Hamlib developers
via email.  Use of these tools is preferred as Git allows credit to be given
to the author and submitter of the patches.  Please submit the patches to
the hamlib-developer mailing list.  See section 8.3.


1.1.3 Git and branches

One of the most powerful features of Git is its ability to make working with
branches easy.  It also allows the developers to "cherry pick" patches from
the master development branch into stable release branches.  In this manner
we can accomodate patches submitted against a stable release and merge them
into master as well.  Such parallel development is a new feature for our
project and there will be a learning curve!

After cloning the repository as above, the repository is synchronized with
the "master" branch.  This can be confirmed by 'git branch'.  A new branch
can be created by providing a name, 'git branch n0nb_k3_level' which will
now exist as a branch in your local repository.  This is a good way to work
on new features as Git keeps changes to files in each branch separate.

As you can see:

$ git branch
  Hamlib-1.2.13
  Hamlib-1.2.13.1
* master
  n0nb_k3

there are a number of branches in my local repository.  Most, such as
"Hamlib-1.2.13", exist in the canonical repository as well.  They can be
seen by 'git branch -r' and you can switch to any of them using the 'git
checkout BRANCH_NAME' command.

Finally, once your changes are ready for inclusion in Hamlib, commit your
changes to the branch you are working in, checkout the master branch, and
use 'git merge' to synchronize your changes into the master branch.  Lastly,
push your changes to the canonical repository (developer write access and
checkout using the SSH protocol required.  See
https://sourceforge.net/scm/?type=git&group_id=8305) or email them to
hamlib-developer@lists.sourceforge.net for inclusion into Hamlib.


1.1.4 Summary

This is a very brief introduction to Git for Hamlib developers.  Day-to-day
Git usage involves a handful of commands--clone, status, commit, pull,
branch, checkout, merge, and push are probably the most common.  Other
useful commands are log and diff to see changes (especially when color
output is enabled in your Git configuration).  See the references above
to learn about setting up Git to your preference.

If you like a GUI tool several exist.  Gitk and Gitg are similar with the
former being written with the Tk toolkit and the latter in GTK+.  Another is
Giggle with its own interface.  All allow looking at the complete history of
the repository and changes made to any file.


1.2. Requirements

Hamlib is entirely developed using GNU tools, under various Linux systems.
Note that Hamlib is not restricted to Linux systems. We welcome anyone who
has access to a POSIXish system to port Hamlib. Contact us for help.

That is, if you want to take part in the development of Hamlib,
you'll need the following tools. Make sure you have at least the required
version or you won't even be able to build from the Git clone.

N.B. The Debian and derivatives (Ubuntu and friends) 'build-essentials'
package will install a number of tools and minimize the number of packages
that need to be installed manually (Debian package names are listed, other
distributions may differ).

* Gnu C or any C99 compliant compiler       # gcc --version
* Gnu make  (or any modern one, BSD okay)   # make --version
* autoconf      2.67                        # autoconf --version
* automake      1.11                        # automake --version
* libtool       2.2.6b+                     # libtool --version
* Git for connection to git.code.sf.net/p/hamlib/code
* texinfo       4.13a                       # makeinfo --version

N.B. Hamlib requires libtool >= 2.2.6b in compliance with CVE-2009-3736.

Optional, but highly recommended:
* GNU C++                           # g++ --version
* swig (for bindings)   1.3.14      # swig -version
* perl devel                        # h2xs
* tcl devel                         # tcltk-depends
* python devel                      # python-config
* libxml2 devel                     # xml2-config --version
* libgd2 devel                      # gdlib-config --version
* libusb-1.0 devel                  # 1.0.0 or newer
* libreadline devel                 # ver 5.2 or newer
* texlive                           # 5.1 tested with 'make distcheck'
* pkg-config            0.9.0       # pkg-config --version (libxml and USRP)

N.B.:  The libusb-1.0 package is required for building most of the 'kit'
backend.  The older version of libusb 0.1.x is no longer supported.

Documentation:
* Doxygen

N.B.:  Some systems can have several versions of the autotools installed. In
that case, autoconf may be called "autoconf2.59", autoheader
"autoheader2.59", and automake "automake-1.9", aclocal "aclocal-1.9" or a
newer version.

IMPORTANT: If autoconf or automake are installed on your system,
make sure they are matching *at least* the version shown above.


1.3. configure and build stage

It is important to note that the Git repository holds no Autotools
generated files, i.e. configure, config.guess, Makefile, etc.  Hence
after a fresh checkout, you'll have to generate those files.

To proceed, first edit the bootstrap script, and set appropriately the
AUTORECONF, AUTOMAKE, and LIBTOOLIZE variables with the required versions seen
in the previous section (most systems will be fine with the default names,
only do this if a problem arises and please let us know).

    cd hamlib
    ./bootstrap
    ./configure [CFLAGS="-g -O0"]
    make
    make install

Note: Depending on the value of '--prefix' passed to 'configure', superuser
(root) privileges may be needed for 'make install'.

If you don't want the build files cluttering the source directories, do the
following in the same parent directory of hamlib:

    mkdir build && cd build
    ../hamlib/bootstrap
    ../hamlib/configure [CFLAGS="-g -O0"]
    make
    make install

Note: In the examples above, passing the CFLAGS environment variable is
optional as shown using the square brackets..

This will keep the binary output files separate from the source tree and aid
in development by reducing clutter in the source tree.

Once you've run `bootstrap', make sure you've got some recent config.guess
and config.sub (needed to guess your system type).  Anything of at least
year 2004 should be fine, unless you run some exotic hardware/software system
(modern Linux distributions and Cygwin keep these up to date):

    ./config.guess --version
    ./config.sub --version

The '--prefix' option to `configure' is optional and not shown as it defaults
to /usr/local.  Convention is that locally built packages be installed in
/usr/local away from distribution installed packages.  The 'CFLAGS="-g -O0"'
environment variable generates less optimized binaries with the '-O0'  while the
'-g' option adds debugging info which can be changed to -ggdb to generate
debugging info for gdb.

Additionally, you may want to add the '--with-perl-binding' or
'--with-python-binding' or '--with-tcl-binding' or '--with-lua-binding' if you are
interested in SWIG binding support for those scripting languages.

NOTE: The bootstrap script has only to be run the first time after a fresh
checkout or when a Makefile.am or other build file is modified or added.

For a Tcl build, add this if needed:

    --with-tcl=/usr/lib/tcl8.2

Note: C-shell users may have to run bootstrap and make through a bourne
shell instead, or pass "SHELL=bash" as a parameter to make.

Some basic testing is accomplished with the 'make check' target which will
run a few predetermined tests using the 'dummy' (rig model 1) backend and
some other Hamlib functions in the build tree. This is a basic sanity check
and cannot test all backends.

Likewise, a complete test of the build system is accomplished with
'make distcheck' which exercises a complete build sequence from creating
a distribution tarball, building, installing, uninstalling, and cleaning
Hamlib.  All packages listed above except for Swig and Doxygen are required
for this target as neither the bindings or old documentation are generated
in a default build.

NOTE!  If Hamlib has not been previously installed as a locally built
package you will need to make sure that `ldconfig' is configured correctly
and run periodically after `make install'.  Most modern distributions have
an /etc/ld.so.conf.d/ directory where local configuration can be made.
Later versions of Debian and derivatives have a file named 'libc.conf' in
this directory.  The contents of libc.conf are:

# libc default configuration
/usr/local/lib

If your system does not have such a file, one will need to be created and
then `ldconfig' will need to be run as the root user so that applications
using the Hamlib libraries can find them.


1.4. Feedback

The Hamlib team is very interested to hear from you, how Hamlib builds and
works on your system, especially on non-Linux or non-PC systems. We are
trying to make Hamlib as portable as possible. Please report problems to our
developer mailing list, hamlib-developer@lists.sourceforge.net

Patches are welcome too!  Just send them to the mailing list.  Git formatted
patches are preferred.  Unified diff format (diff -u) is also welcome.
Patches should apply to the current Git master branch or a testing branch,
if possible.  If you're patching against an older released version of
Hamlib, we can take those as well but please document the release the diff
is generated against.

So far, Hamlib has been tested successfully under the following systems:
(if your system is not present, please report to the mailing list)

    * Debian i386 (plus derivatives--Ubuntu, etc.)
    * Debian sid mipsel
    * Raspbian armhf (Raspberry Pi Debian derivative)
    * RedHat i386
    * Linux ppc
    * Slackware i386
    * FreeBSD & NetBSD
    * Solaris 2.6
    * Mac OS X
    * MS Windows: Cygwin, Mingw


2. How to add a new backend

    The rule is one backend per protocol family.
    Try to share code between rigs of the same family, if applicable.
    The steps in Section 3 below will need to be followed as well.

    2.1. mkdir mybackend
         Create a new subdir, of the name of the protocol backend.
         NB: the directory MUST be the same as the backend name.

    2.2. Add <mybackend> to the DIST_SUBDIRS variable in the topdir
         Makefile.am (not needed for rotators)

    2.3. Add the backend name to the BACKEND_LIST variable (add to
         ROT_BACKEND_LIST for a new rotor backend) in configure.ac.

    2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom
         of configure.ac.

    2.5. Add DEFINE_INITRIG_BACKEND(mybackend); to the end of the existing list
         in src/register.c or, for a new rotor backend, add
         DEFINE_INITROT_BACKEND(myrotbackend); to src/rot_reg.c.

    2.6. Add { RIG_MYBACKEND, RIG_BACKEND_MYBACKEND, RIG_FUNCNAM(mybackend) }, to
         the rig_backend_list structure in src/register.c or, add
         { ROT_MYROTBACKEND, ROT_BACKEND_MYROTBACKEND, ROT_FUNCNAMA(myrotbackend) },
         to the rot_backend_list structure in src/rot_reg.c.

    2.7. Add the new backend to include/hamlib/riglist.h or include/hamlib/rotlist.h
         by selecting the next higher backend ID number.

    2.8. Create mybackend/Makefile.am, mybackend.c mybackend.h
         Use 'dummy' backend as a template.
         Here are commands for the bourne shell:

            $ automake mybackend/Makefile
            $ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status

         make in topdir to rebuild all

    2.9. Commit your work to your local repository. (developer access to
         Hamlib Git required for pushing to the canonical Hamlib repository
         (origin))  Provide patches to the mailing list:
         (Please let N0NB know if the commands below are incorrect)

         $ git status   # Show uncommitted/staged/unstaged files
         $ git add mybackend
         $ cd mybackend
         (The following command might not be necessary)
         $ git add Makefile.am mybackend.c mybackend.h

         While specifying each file individually as above allows for fine-
         grained control, git offers a wildcard shortcut to add all new files:

         $ git add .

         Be careful!  If you have other files that were created as part of the
         build process, this command will add them too unless they match a
         pattern in .gitignore.  Always check with 'git status' first!

         $ git commit -m "Initial release" Makefile.am mybackend.c mybackend.h

         Note: The `-m' switch passes a short message to the Git repository
         upon a commit.  If a longer message is desired, do not use the `-m'
         option.  The editor specified in the EDITOR or VISUAL environment
         variables will be started where a more detailed message may be
         composed.

    2.10 If you have developer access to the Git repository hosted at Source
         Forge, you can do the following:
         $ git push origin

         Your changes will now be available to others.


3. How to add a new model to an existing backend

    3.1. make sure there's already a (unique) ID for the model to be added
         in include/hamlib/riglist.h or include/hamlib/rotlist.h

    3.2. locate the existing backend
    3.3. Clone the most similar model in the backend
    3.4. Add the new C file to the _SOURCES variable
         of the backend's Makefile.am

    3.5. Add "extern const struct rig_caps <mymodel>_caps;" to mybackend.h
    3.6. In initrigs_<mybackend> of mybackend.c,
         add "rig_register(&<mymodel>_caps);"

    3.7. Run `make' if you have dependencies, or the following to regenerate
         the makefile:
            $ automake mybackend/Makefile
            $ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status

            Run `make' in topdir to rebuild all.

    3.8. Commit your work (once tests are satisfactory):
         $ git add .
         $ git commit -m "added <mymodel> to <mybackend>".

         Note:  See Note in section 2.6 above.
         Note:  The '.' character is a Git wildcard that includes all new and
                modified files in your working tree.

                The '-m' option may be ommitted, in which case Git will start
                your default editor for a longer commit message.  Commit
                messages generally have the form of a short subject line, then
                a blank line, and then as much text (broken into paragraphs as
                needed) as needed for a good decription of the commit.

                Assuming your working tree was cloned from the SF.net repository
                or N0NB's GitHub repository, you can now issue a pull request
                inclusion of your new model into Hamlib.


4. Read README.betatester to test the new backend/model.
   Report to mailing list.


5. Basic functions: set/get_freq, set/get_mode, and set/get_vfo would be a
good starting point for your new backend.


6. C code examples.

A C code snippet to connect to a FT847 and set the frequency of the main VFO
to 439,700,000 Hz, using FM as the required mode, would look something like
this. The error checking is removed for simplicity.

    See tests/testrig.c


7. Where are the GUI's?

"Build it and they will come ..."

Seriously, I am hoping the API's will provide a solid framework for some
cool GUI development. I would like to see some GTK or Qt apps that use the
hamlib API's so they can be used by end users as a nice part of the Ham shack.

Starting points (not exhaustive):
    Fldigi, CQRlog, gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog


8. Contributing code

8.1 License

Contributed code to the Hamlib frontend must be released under the LGPL.
Contributed code to Hamlib backends must follow backend current license.
Needless to say, the LGPL is the license of choice.

End user applications like rigctl, rotctl and networked daemons should be
released under the GPL, so any contributed code must follow the license.


8.2 Coding guidelines and style

For specific requirements for formatting the C source code, see
README.coding_style.

Any header files included from the hamlib/ directory should be enclosed in '<>':

#include <hamlib/rig.h>         # Per GNU GCC documentation

Other included header files (backend and rig specific headers) should be
enclosed in "":

#include "yaesu.h"

Contributed code should always keep the source base in a compilable state,
and not regress unless stated otherwise.

There's no need to tag the source in a patch with your name in comments
behind each modification, we already know the culprit from commit logs
(also see "git blame"). :-)

Patches should take portability issues into account.
Keep in mind Hamlib has to run under:

    * various Linux's
    * NetBSD, FreeBSD
    * MacOS X
    * Windows: MinGW/Cygwin, and VisualC++ support for rig.h

Hamlib should also compile with the following common compilers:

    * gcc-3.0 and gcc-3.2+  (nearly deprecated?)
    * gcc-4.x and newer
    * in shared and static
    * C++ compiler against rig.h, riglist.h, rotator.h
    * clang compiler

Portability issues to watch:

    * C99 is probably (in 2016) a reasonable target
    * little vs. big endian systems (use shifts or adhoc functions)
    * 64 bit int: avoid them in API
    * printf/scanf of 64bit int: use PRIll (cast value to int64_t) and SCNll
    * printf/scanf of freq_t: use PRIfreq and SCNfreq

Testing:

    * The acid test for the build system is 'make distcheck' which will
      make a distribution tarball, extract, configure, and build it in a
      subdirectory, run 'make check', install it, uninstall it, and clean
      it up.  When all those tests pass, the GNU build system declares the
      package ready for distribution.  This is a good test if you have
      touched the build system files or added a backend.


8.2.1 Use of rig_debug() function

Hamlib provides a debugging aid in the form of the rig_debug() function,  It
is essentially a wrapper around printf() and takes many of the same flags
and conversion specifiers as the C library's various printf() functions.  It
adds an additional parameter for specifying the desired debug level for the
output string.  Six levels of debugging are defined in include/hamlib/rig.h
and they are:

  NONE          No bug reporting
  BUG           Serious bug
  ERR           Error case (e.g. protocol, memory allocation)
  WARN          Warning
  VERBOSE       Verbose
  TRACE         Tracing

They correspond to the use of the -v switch (from no -v switch to -vvvvv)
to rigctl's command line.  Hamlib applications can also set the debug level
via the Hamlib API.  From an application's perspective, setting a specific
level includes all messages at that level and all at any lower level.

In the library, passing RIG_DEBUG_ERR to rig_debug() limits display of that
message to a level setting of ERR or any higher level.  In this case if the
application sets the message level to RIG_DEBUG_INFO, the message will not
be seen.  Use of a given level can show the value of a critical variable
without the need of a TRACE level message where it can get lost in the
stream of output produced by low-level Hamlib functions.

Here are my (N0NB's) suggested use of rig_debug() levels in backends.

* Many backend functions should have an initial call to rig_debug() as follows:

    rig_debug(RIG_DEBUG_VERBOSE, "%s() entered\n", __func__);

  The use of RIG_DEBUG_VERBOSE allows tracking the chain of function calls
  through the backend while still keeping rigctl's output mostly
  uncluttered by use of the -vvvv switch.

* Developers will want to call rig_debug() to display values of critical
  variable(s) in a backend function.  For this RIG_DEBUG_VERBOSE
  (rigctl -vvvv) should be a good choice as the output won't be lost in the
  stream of RIG_DEBUG_TRACE (rigctl -vvvvv) level output by various
  low-level Hamlib functions.  It will also match the display of the values
  of critical variable(s) with the function calls as above.

* Use RIG_DEBUG_TRACE when it makes sense to see the variable(s) in the
  context of a lot of low-level debugging output (rigctl -vvvvv).

* Lower levels (BUG, ERR, and WARN) should be used where it makes sense that
 information be printed when the user selects less verbosity.  Use sparingly.

Many backends do not conform to this suggestion at the moment.  The use of
the RIG_DEBUG_LEVEL values has been somewhat haphazard (at least by this
scribe) so fixing these when working in a given backend is encouraged.

If an application sets the debugging level to RIG_DEBUG_NONE, then
rig_debug() functions will produce no output.  Therefore rig_debug() cannot
be counted on to output a message in all runtime cases.

The debugging levels may be an area for consideration in Hamlib 3.


8.3 Submitting patches

Git provides tools to generate patches and submit them to the Hamlib
developers via email.  Use of these tools is preferred as Git allows credit
to be given to the author and submitter of the patches.  Alternately,
patches can be submitted in unified format (diff -u), against the Git master
branch or a given release (please note well which one!). Both formats make
patches easily readable. The patches are to be sent to the hamlib-developer
mailing list (hamlib-developer@lists.sourceforge.net). If the file is too
big, you can send it as a compressed attachment.


8.3.1 Changelog

A ChangeLog file is no longer manually maintained.  At some point it may be
automatically generated from the Git commit log for source tarballs.

Simply summarize your changes when the files are committed to Git or, if
providing patches to the mailing list, provide a summary so the uploader can
include it in the commit message which will show in the commit log (Git
formatted emails will include this already).


8.4 Git commit access

Generally, volunteers can get commit access to the SourceForge Hamlib Git
repository upon asking one of the project administrators.  Sometimes we'll
ask you!

However, before your start committing, the project admins would like first
to have a look at your "style", just to make sure you grok the Hamlib
approach (c.f. previous section on submitting a patch). Then you'll be able
to commit by yourself to the backend you chose to maintain. Please follow
the rules hereunder:

    * Always keep the Git repository (all branches) in a compilable state.
    * Follow the coding guidelines
    * Touching the frontend (files in src/ and include/hamlib) always
      requires discussion beforehand on the hamlib-developer list.
    * Announce on the hamlib-developer list if you're about to do serious
      maintainance work

Thanks for contributing and have fun!



Stephane Fillod f8cfe and The Hamlib Group