kopia lustrzana https://github.com/Hamlib/Hamlib
675 wiersze
25 KiB
Plaintext
675 wiersze
25 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 releases.
|
|
|
|
See README for frontend/backend outline.
|
|
See README.betatester for background on testing Hamlib.
|
|
|
|
|
|
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 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 13 Feb 2011
|
|
(Note, it has grown considerably).
|
|
|
|
$ tree -d -I .git
|
|
.
|
|
├── alinco
|
|
├── aor
|
|
├── ars
|
|
├── bindings
|
|
├── c++
|
|
├── 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
|
|
├── 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
|
|
|
|
56 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://hamlib.git.sourceforge.net/gitroot/hamlib/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.
|
|
|
|
|
|
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 toturials, 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 prefered 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.59 # autoconf --version
|
|
* automake 1.7 # automake --version
|
|
* libtool 2.2.6b # libtool --version
|
|
* libltdl-dev 2.2.6b
|
|
* Git for connection to hamlib.git.sourceforge.net
|
|
|
|
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 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
|
|
|
|
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 Git repository holds no autogenerated
|
|
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 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 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 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 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
|
|
'--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.
|
|
|
|
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 Git master branch 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. 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
|
|
* 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 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.7 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
|
|
|
|
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):
|
|
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 RPC daemons should be released
|
|
under the GPL, so any contributed code must follow the license.
|
|
|
|
|
|
8.2 Coding guidelines and style
|
|
|
|
Try to keep current style of existing code. Improvements are welcome though.
|
|
When in doubt, follow the Linux kernel coding style guide:
|
|
|
|
http://www.kernel.org/doc/Documentation/CodingStyle
|
|
|
|
Hamlib is a code base from many contributors and a variety of styles have
|
|
been employed. If you work on a source file, go ahead and apply good
|
|
judgment and clean it up per the kernel style guide. Lining things up
|
|
nicely with 8 space tabs (use tabs, not spaces) is an excellent start.
|
|
Next, put spaces in assignments to aid readability. Align closing braces
|
|
with the opening block's keyword. In function definitions put the opening
|
|
brace on its own line under the definition's parameter line.
|
|
|
|
Hamlib source code is no place for an entry into the obsfucated C contest!
|
|
Many of us are hobbyists and write this for fun. Easy to read and
|
|
understand logic is preferred over a clever solution. If your solution must
|
|
be written in a clever fashion, please document it well in your comments.
|
|
|
|
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-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.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 API_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
|
|
|
|
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 inlcude 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
|