kopia lustrzana https://github.com/Hamlib/Hamlib
767 wiersze
28 KiB
Plaintext
767 wiersze
28 KiB
Plaintext
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, rotator, and amplifier control,
|
|
and data retrieval from the radio, rotator, or amplifier. 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, rotator, and amplifier "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 2020-01-18
|
|
|
|
$ tree -d -I .git
|
|
.
|
|
├── amplifiers
|
|
│ └── elecraft
|
|
├── android
|
|
├── autom4te.cache
|
|
├── bindings
|
|
├── build-aux
|
|
├── c++
|
|
├── doc
|
|
│ ├── man1
|
|
│ └── man7
|
|
├── dummy
|
|
├── extra
|
|
│ ├── gnuradio
|
|
│ └── kylix
|
|
│ └── tests
|
|
├── include
|
|
│ └── hamlib
|
|
├── lib
|
|
├── macros
|
|
├── perl
|
|
├── rigs
|
|
│ ├── adat
|
|
│ ├── alinco
|
|
│ ├── aor
|
|
│ ├── barrett
|
|
│ ├── dorji
|
|
│ ├── drake
|
|
│ ├── elad
|
|
│ ├── flexradio
|
|
│ ├── icmarine
|
|
│ ├── icom
|
|
│ ├── jrc
|
|
│ ├── kachina
|
|
│ ├── kenwood
|
|
│ ├── kit
|
|
│ ├── lowe
|
|
│ ├── pcr
|
|
│ ├── prm80
|
|
│ ├── racal
|
|
│ ├── rft
|
|
│ ├── rs
|
|
│ ├── skanti
|
|
│ ├── tapr
|
|
│ ├── tentec
|
|
│ ├── tuner
|
|
│ ├── uniden
|
|
│ ├── winradio
|
|
│ │ └── linradio
|
|
│ ├── wj
|
|
│ └── yaesu
|
|
├── rotators
|
|
│ ├── amsat
|
|
│ ├── ars
|
|
│ ├── celestron
|
|
│ ├── cnctrk
|
|
│ ├── easycomm
|
|
│ ├── ether6
|
|
│ ├── fodtrack
|
|
│ ├── gs232a
|
|
│ ├── heathkit
|
|
│ ├── ioptron
|
|
│ ├── m2
|
|
│ ├── meade
|
|
│ ├── prosistel
|
|
│ ├── rotorez
|
|
│ ├── sartek
|
|
│ ├── spid
|
|
│ └── ts7400
|
|
│ └── include
|
|
├── scripts
|
|
├── src
|
|
└── tests
|
|
├── config
|
|
├── rigctl.test
|
|
├── testbcd.test
|
|
├── testfreq.test
|
|
└── testloc.test
|
|
|
|
77 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 accommodate 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
|
|
|
|
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
|
|
* 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.
|
|
|
|
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.
|
|
|
|
For LUA bindinds if you run "lua luatest.lua" and see this error message:
|
|
luatest.lua:44: Error in Rig::set_mode (arg 2), expected 'rmode_t' got 'string'
|
|
This means you need to upgrade both swig and lua for 64-bit lua support
|
|
This is known to work on swig 4.0.1 and lua 5.3.5
|
|
|
|
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.3.1 Doxygen generated reference manual
|
|
|
|
The following packages need to be installed:
|
|
* Doxygen
|
|
* GNU Source-highlight
|
|
|
|
1.3.1.1 HTML manual
|
|
|
|
In the top level of the build directory:
|
|
|
|
cd doc
|
|
make doc
|
|
|
|
will build the HTML manual. The resulting 'doc/html' directory contains all
|
|
of the files needed for the HTML manual. The 'index.html' file is the entry
|
|
point to the manual.
|
|
|
|
1.3.1.2 PDF manual
|
|
|
|
To generate the PDF version of the reference manual the following texlive
|
|
packages are required (Debian package names shown):
|
|
* texlive-latex-base
|
|
* texlive-latex-recommended
|
|
* texlive-latex-extra
|
|
|
|
Set GENERATE_LATEX in 'doc/hamlib.cfg.in' to 'YES' which will enable the LaTEX
|
|
build. Then run:
|
|
|
|
make doc
|
|
|
|
as above and once the run is complete:
|
|
|
|
cd latex
|
|
make
|
|
|
|
The resulting generated document in the 'latex' directory is 'refman.pdf'.
|
|
|
|
|
|
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.
|
|
Version numbers used are in the form YYYYMMDD.N where the .N is
|
|
intended for multiple versions in one day....so typically would be .0
|
|
|
|
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 or to AMP_BACKEND_LIST for
|
|
a new amplifier) 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.
|
|
{ AMP_MYAMPBACKEND, AMP_BACKEND_MYAMPBACKEND, AMP_FUNCNAMA(myaotbackend) },
|
|
to the aot_backend_list structure in src/amp_reg.c.
|
|
|
|
2.7. Add the new backend to include/hamlib/riglist.h or include/hamlib/rotlist.h or include/hamlib/amplist.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 or include/hamlib/amplist.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 omitted, 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 description 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, ampctl 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, amplifier.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
|
|
maintenance work
|
|
|
|
Thanks for contributing and have fun!
|
|
|
|
|
|
|
|
Stephane Fillod f8cfe and The Hamlib Group
|