Hamlib/README.developer

Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
	and Stephane Fillod 2000-2003

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 (and other) connectivity will follow afterwards. 


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

0. The top level directory looks like this.

[fillods@charybde hamlib]$ tree -d
|-- alinco
|-- aor
|-- bindings
|-- c++
|-- debian
|-- doc
|   |-- html
|   |-- man
|   `-- sgml
|-- drake
|-- dummy
|-- easycomm
|-- fodtrack
|-- gnuradio
|-- icom
|   |-- lib
|   `-- test
|-- include
|   `-- hamlib
|-- jrc
|-- kachina
|-- kenwood
|-- kylix
|   `-- tests
|-- lib
|-- libltdl
|-- macros
|-- microtune
|-- pcr
|-- rotorez
|-- rpcrig
|-- rpcrot
|-- src
|-- tentec
|-- tests
|   `-- html
|-- uniden
|-- winradio
|   `-- linradio
`-- yaesu


1. Building

If you just want to recompile the library, please refer
to the INSTALL file. 

1.1 Obtaining sources: anonymous (pserver) cvs checkout

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

When prompted for a password for anonymous, simply press the Enter key.
The check out has only to be done the first time. In the case you don't
have cvs access through your firewall, but http gets through, daily
cvs snapshots are available. The previous commands can be replaced
by the following:

	wget http://cvs.sf.net/cvstarballs/hamlib-cvsroot.tar.gz
	tar zxvf hamlib-cvsroot.tar.gz
	mv hamlib hroot
	export CVSROOT=`pwd`/hroot
	cvs co -P hamlib

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

  cvs -z3 -d:pserver:anonymous@cvs.hamlib.sf.net:/cvsroot/hamlib update -d

Tip: 
I use the following alias:
alias hcvs='cvs -z3  -d:pserver:anonymous@cvs.hamlib.sf.net:/cvsroot/hamlib'
This way, I just have to do "hcvs update -d" whenever I want to keep to
date. Setting CVSROOT to ":pserver:anonymous@cvs.hamlib.sf.net:/cvsroot/hamlib"
works the same.


1.2. Requirements

Hamlib is entirely developped 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 to. 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.hamlib.sourceforge.net

Optional:
* GNU C++					# g++ --version
* swig (for bindings)	1.3.14  		# swig -version
* perl devel					# h2xs
* tcl devel
* libgd 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 upper 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 recommanded 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.
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,ACLOCAL variables with the required
versions seen in the previous section.

	chmod +x autogen.sh
	./autogen.sh --disable-static --prefix=/some/where
	make
	make install

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 2002 should be fine, unless you run
some exotic hardware/software system:

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

The prefix argument is optionnal. The --disable-static speeds up
compilation if you don't plan to use static libraries.

NOTE: autogen.sh has only to be run the first time after a fresh checkout.

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.


For Tcl build, add this if needed:
			--with-tcl=/usr/lib/tcl8.2

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


1.4. Feedback

The Hamlib team is very interrested to hear from you, how Hamlib
builds and works on your system, especially on non-Linux system or 
non-PC systems. We try to make Hamlib as portable as possible.
Please report in case of problems at hamlib-developer@lists.sourceforge.net
Patches are welcome too!

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

	* Debian potato/sarge/sid i386
	* Debian sid mipsel
	* RedHat i386
	* Linux ppc
	* Slackware i386
	* FreeBSD
	* Solaris 2.6
	* win32: Cygwin
	* should work under Darwin (untested lately)


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 SUBDIRS variable in the topdir Makefile.am, 
	2.3. Add the backend name to the BACKEND_LIST variable in configure.ac
	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:
		$ cvs add mybackend
		$ cd mybackend
		$ cvs add Makefile.am mybackend.c mybackend.h
		$ cvs commit -m "Initial release" Makefile.am mybackend.c mybackend.h


3. How to add a new model to and 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

		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


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

5. Basic functions: set_freq and set_mode. set_vfo would be great.

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 apps that use the hamlib API's
   so they can be used by end users as a nice part of the
   Ham shack.
   Starting point: kontakt, grig

8. Coding guidelines
   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.


Stephane Fillod f8cfe
Frank Singleton vk3fcs/km5ws