Hamlib/README.developer

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

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

See README for frontend/backend outline.


The shared libs provide functions for both radio control,
and data retrieval from the radio.
 
The structure of the libraries is as follows.

(1)	There is one frontend library "libhamlib" that
	provides the generic API for user applications.

(2)	There are "n" backend libraries that "wrap" 
	rig specific communications inside frontend API.

(3)	Frontend lib loads (on demand) the appropriate
	backend lib as required. 

Frontend Library
----------------

libhamlib.so -  frontend lib that provides generic API
		for all RIG types. This is what Application
		programmers will "see".

Backend Examples are:
---------------------
 
1.hamlib-yaesu.so will provide connectivity to Yaesu
  FT 747GX Transceiver, FT 847 "Earth Station", etc. via a standard API.

2. hamlib-xxxx.so 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.
 
Initially serial (RS232) connectivity will be handled, but
I expect that IP, USB, and other connectivity will follow afterwards. 


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

0. The top level directory looks like this as of 06 Jan 2008
(Note, it has grown considerably).

~/test/hamlib $ tree -d -I CVS
.
|-- alinco
|-- aor
|-- bindings
|-- c++
|-- debian
|-- doc
|   `-- sgml
|-- drake
|-- dummy
|-- easycomm
|-- flexradio
|-- fodtrack
|-- gnuradio
|-- icom
|-- include
|   `-- hamlib
|-- jrc
|-- kachina
|-- kenwood
|-- kit
|-- kylix
|   `-- tests
|-- lib
|-- libltdl
|-- lowe
|-- macros
|-- microtune
|-- pcr
|-- perl
|-- racal
|-- rft
|-- rotorez
|-- rpcrig
|-- rpcrot
|-- sartek
|-- skanti
|-- src
|-- tapr
|-- tentec
|-- tests
|   |-- config
|   |-- rigctl.test
|   |-- testbcd.test
|   |-- testfreq.test
|   `-- testloc.test
|-- tuner
|-- uniden
|-- winradio
|   `-- linradio
|-- wj
`-- yaesu

51 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: anonymous (pserver) cvs checkout

  cvs -d:pserver:anonymous@hamlib.cvs.sourceforge.net:/cvsroot/hamlib login 
  cvs -z3 -d:pserver:anonymous@hamlib.cvs.sourceforge.net:/cvsroot/hamlib co -P hamlib

When prompted for a password for anonymous, simply press the Enter key.
The check out has only to be done the first time.

After the initial retrieval, whenever you want to update your local
version, issue the following command in the root directory of hamlib.

  cvs -z3 update -Pd

This provides a level of data compression (values are from 0, off, to 9, full,
feel free to experiment) deletes empty directories (yes some do exist :-) )
and adds any new directories added to the repository since your last
checkout.


1.1.1 Obtaining more info on CVS

Check out the sourceforge page at https://sourceforge.net/cvs/?group_id=8305
for more information about how to use the CVS repository of Hamlib.

A CVS manual is online at http://ximbiot.com/cvs/manual/


1.2. Requirements

Hamlib is entirely developed using GNU tools, under various Linux systems.
Note that it 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 cvs checkout.

* Gnu C or any C99 compliant compiler       # gcc --version
* Gnu make  (or any modern one, BSD okay)   # make --version
* autoconf      2.54                        # autoconf --version
* automake      1.7                         # automake --version
* libtool       1.5                         # libtool --version
* cvs and ssh for connection to cvs.sourceforge.net

Optional:
* GNU C++                           # g++ --version
* swig (for bindings)   1.3.14      # swig -version
* perl devel                        # h2xs
* tcl devel
* python devel
* libxml2 devel                     # xml2-config --version
* libgd devel
* libusb devel
* RPC devel (libc-dev)              # rpcgen --version

Documentation:
* doxygen
* DocBook

Note:  Some systems can have several versions of the autotools installed.
In that case, autoconf may be called "autoconf2.50", autoheader
"autoheader2.50", and automake "automake-1.7", aclocal "aclocal-1.7" 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.
Some people experience troubles with automake 1.5, if you're one of those,
it's recommended to upgrade to automake 1.7, which is a lot more stable.


1.3. configure and build stage

It has to be known the CVS repository holds no autogenerated files, i.e.
configure, config.guess, etc.  Hence after a fresh checkout, you'll have to
generate those files.

To proceed, first edit the autogen.sh, and set appropriately the AUTOCONF,
AUTOHEADER, AUTOHEADER, and ACLOCAL variables with the required versions
seen in the previous section (most systems will be fine with the default
names).

    sh ./autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
    make
    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
    sh ../hamlib/autogen.sh  --disable-static --prefix=/usr/local CFLAGS="-g -O0"
    make
    make install

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

Once you've run autogen.sh, 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:

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

The prefix argument is optional.  Convention is that local packages be placed
in /usr/local away from distribution installed packages.  The --disable-static
and CFLAGS="-g -O0" speeds up compilation if you don't plan to use static
libraries and can bear less optimized binaries while the -g option adds
debugging info which can be changed to -ggdb to generate debugging info for
gdb.

NOTE: autogen.sh 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.

The difference between building as a tester and a developer is in the 
'--enable-maintainer-mode' option passed to configure.  This option will add 
new Makefile targets and dependencies and not force a rebuild of the Makefiles
when make is executed.

For a Tcl build, add this if needed:

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

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


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.

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
    * Debian sid mipsel
    * RedHat i386
    * Linux ppc
    * Slackware i386
    * FreeBSD & NetBSD
    * Solaris 2.6
    * Mac OS X
    * win32: 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.

    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, 
    2.3. Add the backend name to the BACKEND_LIST variable in configure.ac 
	 (Add to ROT_BACKEND_LIST for a new rotor backend).
    2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom 
         of configure.ac

    2.5. 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.6. Commit your work (developer access to Hamlib CVS required):
         $ cvs add mybackend
         $ cd mybackend
         $ cvs add Makefile.am mybackend.c mybackend.h
         $ cvs commit -m "Initial release" Makefile.am mybackend.c mybackend.h

         Note: The `-m' switch passes a short message to the CVS 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.

         
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

    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):
         $ cd mybackend
         $ cvs add mymodel.c
         $ cvs commit -m "added <mymodel> to <mybackend>" Makefile.am mybackend.c mybackend.h mymodel.c

         Note:  See Note in section 2.6 above.
         

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): 
    gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog, xtlf


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 RPC daemons should be released
under the GPL, so any contributed code must follow the rule.

8.2 Coding guidelines and style

Try to keep current style of existing code. Improvements are welcome though.
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 :-)

Patches should take care of portability issues.
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-2.9x  (most likely deprecated)
    * 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

Portability issues to watch:

    * little vs. big endian systems (use shifts or adhoc functions)
    * 64 bit int: avoid them in API
    * printf/scanf of 64bit int: use PRIll and SCNll
    * printf/scanf of freq_t: use PRIfreq and SCNfreq

8.3 Submitting patches

Patches should be in unified format (diff -u), against CVS head or
latest release. This format makes it easily readable. 
The patches are to be sent to the hamlib-developer
mailing list. If the file is too big, you can send it as a compressed
attachement.
   
8.3.1 Changelog
   
Caveat: The cvs2cl.pl script is used before each release to generate
the Changelog file so any changes made directly to it WILL BE LOST!
Simply summarize your changes when the files are committed to CVS or,
if providing patches to the mailing list, provide a summary so the
uploader can include it in the commit message.

8.4 CVS commit access

Generally, volunteers can get access to SourceForge Hamlib CVS upon 
asking one of the project administrators.  Sometimes we'll ask you!
   
However, before your start commiting, the project admins would like 
first to have a look at your "style", just to make sure you have 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 have 
maintainance of. Please follow the rules hereunder:

    * Always keep the CVS repository 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