Hamlib/README.developer

517 wiersze
18 KiB
Plaintext

Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
(C) Stephane Fillod 2000-2011
(C) The Hamlib Group 2000-2011
Take a look at http://sourceforge.net/projects/hamlib/
Here you will find a mail list, and the latest SVN 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.
Serial (RS232) connectivity is built in as are 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 19 Jan 2011
(Note, it has grown considerably).
~/test/hamlib $ tree -d -I .svn
.
|-- alinco
|-- aor
|-- ars
|-- bindings
|-- c++
|-- doc
| `-- sgml
|-- drake
|-- dummy
|-- easycomm
|-- flexradio
|-- fodtrack
|-- gnuradio
|-- gs232a
|-- heathkit
|-- icom
|-- include
| `-- hamlib
|-- jrc
|-- kachina
|-- kenwood
|-- kit
|-- kylix
| `-- tests
|-- lib
|-- libltdl
| |-- config
| |-- libltdl
| |-- loaders
| `-- m4
|-- lowe
|-- m2
|-- macros
|-- microtune
|-- miniVNA
|-- pcr
|-- perl
|-- prm80
|-- racal
|-- rft
|-- rotorez
|-- rpcrig
|-- rpcrot
|-- rs
|-- sartek
|-- skanti
|-- spid
|-- src
|-- tapr
|-- tentec
|-- tests
| |-- config
| |-- rigctl.test
| |-- testbcd.test
| |-- testfreq.test
| `-- testloc.test
|-- tuner
|-- uniden
|-- winradio
| `-- linradio
|-- wj
`-- yaesu
62 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: SVN trunk checkout
svn co https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk hamlib
N.B.: If the "trunk" subdirectory is ommited then the entire SVN
reposity will be downloaded! This includes all branches and tags that
have ever been created in the history of Hamlib. That is quite large,
abut 22 MiB as of this writing (March 2009).
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.
svn update
1.1.1 Obtaining more info on SVN
Check out the sourceforge page at https://sourceforge.net/svn/?group_id=8305
for more information about how to use the SVN repository of Hamlib.
A SVN manual is online at http://svnbook.red-bean.com/
1.1.5 Experimental Git repository
An experimental Git repository has been set up. As of this moment it is
only tracking SVN trunk/* as its master branch. Commits are made first to
SVN (git svn dcommit) and then pushed to this repository to tie the SVN ID
to the Git commits. The hosting address for cloning is:
git://hamlib.git.sourceforge.net/gitroot/hamlib/hamlib
Nate, N0NB, will accept patches emailed from Git (they may be posted to the
hamlib-developer mailing list). Patches should apply to the current SVN
trunk/* tree. Keep in mind that with the SVN repository being the primary
repository that things like your local branching information will be lost.
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 SVN checkout.
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.
* 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 2.2.6b # libtool --version
* svn for connection to hamlib.svn.sourceforge.net
N.B. Hamlib no longer supports versions of libtool earlier than 2.2.6b in
compliance with CVE-2009-3736. If an older version is found, Hamlib will use
the bundled libtool 2.2.6b instead.
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 devel # libusb-config --version (not 1.0.0!)
* RPC devel (libc-dev) # rpcgen --version
N.B The libusb package is required for building most of the 'kit' backend.
The older version is needed, not 1.0.0 or higher. Debian and derivatives
package libusb 0.1.12 which is what is needed.
Documentation:
* Doxygen
* DocBook # Deprecated in favor of Doxygen
N.B.: 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 is important to note that the SVN repository holds no autogenerated
files, i.e. configure, config.guess, Makefile, etc. Hence after a fresh
checkout, you'll have to generate those files.
NOTE: Hamlib previously included a script 'autofixer.sh'. It has been
removed, as hamlib no longer supports the use of libtool 1.x versions in
compliance with CVE-2009-3736. The autogen.sh script will upgrade the
bundled libtool source only if a newer version is installed on the system.
To proceed, first edit the autogen.sh script, 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, only do this if a problem arises).
cd hamlib
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' option to `autogen.sh' is optional. Convention is that
locally built packages be installed 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.
Additionally, you may want to add the '--with-perl-binding' or
'--with-python-binding' or '--enable-tcl-binding' if you are interested in
Swig binding support for those scripting languages (This is a change as of
1.2.11svn revision 2882 where Swig generated bindings are no longer built by
default).
NOTE: The autogen.sh 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.
The difference between building as a beta tester and a developer is in the
'--enable-maintainer-mode' option passed to configure from autogen.sh. This
option will add new Makefile targets and dependencies and not force a
rebuild of the Makefiles when make is executed. This is why we recommend
that beta testers use the daily SVN snapshot from:
http://n0nb.users.sourceforge.net
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.
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. Unified diff
(diff -u) is the prefered format and patches should apply to the current SVN
trunk, if possible. If you're patching against an older released version of
Hamlib, we can take those as well.
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
* 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 (add to
ROT_BACKEND_LIST for a new rotor backend) in configure.ac.ltv1
and configure.ac.ltv2 (configure.ac is deprecated at the moment).
2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom
of configure.ac.ltv1 and configure.ac.ltv2 (configure.ac is deprecated
at the moment)
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 SVN required):
(Please let N0NB know if the commands below are incorrect)
$ svn add mybackend
$ cd mybackend
(The following command might not be necessary)
$ svn add Makefile.am mybackend.c mybackend.h
$ svn commit -m "Initial release" Makefile.am mybackend.c mybackend.h
Note: The `-m' switch passes a short message to the SVN 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):
$ svn add mybackend/mymodel.c
$ svn 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 from commit logs. :-)
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-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 SVN trunk/ 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 attachment.
8.3.1 Changelog
Caveat: The svn2cl program 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 SVN 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 Changelog.
8.4 SVN commit access
Generally, volunteers can get access to SourceForge Hamlib SVN 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 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 SVN trunk 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