1Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com) 2 (C) Stephane Fillod 2000-2011 3 (C) The Hamlib Group 2000-2013 4 5Take a look at http://sourceforge.net/projects/hamlib/ 6Here you will find a mail list, and the latest releases. 7 8See README for frontend/backend outline. 9See README.betatester for background on testing Hamlib. 10 11 12The library provides functions for both radio, rotator, and amplifier control, 13and data retrieval from the radio, rotator, or amplifier. A number of functions useful 14for calculating distance and bearing and grid square conversion are included. 15 16libhamlib.so - library that provides generic API for all RIG types. 17 This is what Application programmers will "see". Will have different 18 names on other platforms, e.g. libhamlib-2.dll on MS windows. Also 19 contains all radio, rotator, and amplifier "backends" (formerly in their own 20 dlopen'ed libraries) provided by Hamlib. 21 22Backend Examples are: 23--------------------- 24 251. yaesu will provide connectivity to Yaesu FT 747GX Transceiver, FT 847 26 "Earth Station", etc. via a standard API. 27 282. xxxx. will provide connectivity to the Wiz-bang moon-melter 101A (yikes..) 29 30Hamlib also enables developers to develop professional looking 31GUI's towards a standard control library API, and they would not have 32to worry about the underlying connection towards physical hardware. 33 34Serial (RS232) connectivity is built in as are RPC, IP (also via a socket 35utility), and USB. Other connectivity will follow afterwards. 36 37 38General Guidelines. 39------------------- 40 410. The top level directory looks like this as of 2020-01-18 42 43$ tree -d -I .git 44. 45├── amplifiers 46│ └── elecraft 47├── android 48├── autom4te.cache 49├── bindings 50├── build-aux 51├── c++ 52├── doc 53│ ├── man1 54│ └── man7 55├── dummy 56├── extra 57│ ├── gnuradio 58│ └── kylix 59│ └── tests 60├── include 61│ └── hamlib 62├── lib 63├── macros 64├── perl 65├── rigs 66│ ├── adat 67│ ├── alinco 68│ ├── aor 69│ ├── barrett 70│ ├── dorji 71│ ├── drake 72│ ├── elad 73│ ├── flexradio 74│ ├── icmarine 75│ ├── icom 76│ ├── jrc 77│ ├── kachina 78│ ├── kenwood 79│ ├── kit 80│ ├── lowe 81│ ├── pcr 82│ ├── prm80 83│ ├── racal 84│ ├── rft 85│ ├── rs 86│ ├── skanti 87│ ├── tapr 88│ ├── tentec 89│ ├── tuner 90│ ├── uniden 91│ ├── winradio 92│ │ └── linradio 93│ ├── wj 94│ └── yaesu 95├── rotators 96│ ├── amsat 97│ ├── ars 98│ ├── celestron 99│ ├── cnctrk 100│ ├── easycomm 101│ ├── ether6 102│ ├── fodtrack 103│ ├── gs232a 104│ ├── heathkit 105│ ├── ioptron 106│ ├── m2 107│ ├── meade 108│ ├── prosistel 109│ ├── rotorez 110│ ├── sartek 111│ ├── spid 112│ └── ts7400 113│ └── include 114├── scripts 115├── src 116└── tests 117 ├── config 118 ├── rigctl.test 119 ├── testbcd.test 120 ├── testfreq.test 121 └── testloc.test 122 12377 directories 124 1251. Building 126 127If you just want to recompile the library, please refer to the INSTALL 128file. This document introduces hacking the code of Hamlib. 129 130 1311.1 Obtaining sources: git clone 132 133 git clone git://git.code.sf.net/p/hamlib/code hamlib 134 135The clone has to only be done the first time. 136 137After the initial clone, whenever you want to update your local 138repository, issue the following command in the root directory of Hamlib: 139 140 git pull 141 142This will download and merge any changes from the canonical Hamlib Git 143repository (what Git calls origin by default). This command actually 144combines two Git commands, fetch and merge into one that will first check 145for conflicting changes between your local repository and the remote 146(origin) repository and will not apply any changes if conflicts are found. 147 148A pull can be restricted to just a single branch if desired: 149 150 git pull origin master 151 152 1531.1.1 Obtaining more info on Git 154 155Check out the Source Forge page at 156https://sourceforge.net/scm/?type=git&group_id=8305 for more information 157about how to use the Git repository of Hamlib. 158 159Much documentation on Git exists. A good starting point is: 160 161http://git-scm.com/documentation 162 163From this page are links to tutorials, books (Pro Git proved useful for me), 164and references (http://gitref.org/ is another good resource). 165 166Another site: 167 168http://www-cs-students.stanford.edu/~blynn/gitmagic/ 169 170 1711.1.2 Providing patches with Git 172 173Git provides tools to generate patches and submit them to the Hamlib developers 174via email. Use of these tools is preferred as Git allows credit to be given 175to the author and submitter of the patches. Please submit the patches to 176the hamlib-developer mailing list. See section 8.3. 177 178 1791.1.3 Git and branches 180 181One of the most powerful features of Git is its ability to make working with 182branches easy. It also allows the developers to "cherry pick" patches from 183the master development branch into stable release branches. In this manner 184we can accommodate patches submitted against a stable release and merge them 185into master as well. Such parallel development is a new feature for our 186project and there will be a learning curve! 187 188After cloning the repository as above, the repository is synchronized with 189the "master" branch. This can be confirmed by 'git branch'. A new branch 190can be created by providing a name, 'git branch n0nb_k3_level' which will 191now exist as a branch in your local repository. This is a good way to work 192on new features as Git keeps changes to files in each branch separate. 193 194As you can see: 195 196$ git branch 197 Hamlib-1.2.13 198 Hamlib-1.2.13.1 199* master 200 n0nb_k3 201 202there are a number of branches in my local repository. Most, such as 203"Hamlib-1.2.13", exist in the canonical repository as well. They can be 204seen by 'git branch -r' and you can switch to any of them using the 'git 205checkout BRANCH_NAME' command. 206 207Finally, once your changes are ready for inclusion in Hamlib, commit your 208changes to the branch you are working in, checkout the master branch, and 209use 'git merge' to synchronize your changes into the master branch. Lastly, 210push your changes to the canonical repository (developer write access and 211checkout using the SSH protocol required. See 212https://sourceforge.net/scm/?type=git&group_id=8305) or email them to 213hamlib-developer@lists.sourceforge.net for inclusion into Hamlib. 214 215 2161.1.4 Summary 217 218This is a very brief introduction to Git for Hamlib developers. Day-to-day 219Git usage involves a handful of commands--clone, status, commit, pull, 220branch, checkout, merge, and push are probably the most common. Other 221useful commands are log and diff to see changes (especially when color 222output is enabled in your Git configuration). See the references above 223to learn about setting up Git to your preference. 224 225If you like a GUI tool several exist. Gitk and Gitg are similar with the 226former being written with the Tk toolkit and the latter in GTK+. Another is 227Giggle with its own interface. All allow looking at the complete history of 228the repository and changes made to any file. 229 230 2311.2. Requirements 232 233Hamlib is entirely developed using GNU tools, under various Linux systems. 234Note that Hamlib is not restricted to Linux systems. We welcome anyone who 235has access to a POSIXish system to port Hamlib. Contact us for help. 236 237That is, if you want to take part in the development of Hamlib, 238you'll need the following tools. Make sure you have at least the required 239version or you won't even be able to build from the Git clone. 240 241N.B. The Debian and derivatives (Ubuntu and friends) 'build-essentials' 242package will install a number of tools and minimize the number of packages 243that need to be installed manually (Debian package names are listed, other 244distributions may differ). 245 246* Gnu C or any C99 compliant compiler # gcc --version 247* Gnu make (or any modern one, BSD okay) # make --version 248* autoconf 2.67 # autoconf --version 249* automake 1.11 # automake --version 250* libtool 2.2.6b+ # libtool --version 251* Git for connection to git.code.sf.net/p/hamlib/code 252 253N.B. Hamlib requires libtool >= 2.2.6b in compliance with CVE-2009-3736. 254 255Optional, but highly recommended: 256* GNU C++ # g++ --version 257* swig (for bindings) 1.3.14 # swig -version 258* perl devel # h2xs 259* tcl devel # tcltk-depends 260* python devel # python-config 261* libxml2 devel # xml2-config --version 262* libgd2 devel # gdlib-config --version 263* libusb-1.0 devel # 1.0.0 or newer 264* libreadline devel # ver 5.2 or newer 265* pkg-config 0.9.0 # pkg-config --version (libxml and USRP) 266 267N.B.: The libusb-1.0 package is required for building most of the 'kit' 268backend. The older version of libusb 0.1.x is no longer supported. 269 270N.B.: Some systems can have several versions of the autotools installed. In 271that case, autoconf may be called "autoconf2.59", autoheader 272"autoheader2.59", and automake "automake-1.9", aclocal "aclocal-1.9" or a 273newer version. 274 275IMPORTANT: If autoconf or automake are installed on your system, 276make sure they are matching *at least* the version shown above. 277 278 2791.3. configure and build stage 280 281It is important to note that the Git repository holds no Autotools 282generated files, i.e. configure, config.guess, Makefile, etc. Hence 283after a fresh checkout, you'll have to generate those files. 284 285To proceed, first edit the bootstrap script, and set appropriately the 286AUTORECONF, AUTOMAKE, and LIBTOOLIZE variables with the required versions seen 287in the previous section (most systems will be fine with the default names, 288only do this if a problem arises and please let us know). 289 290 cd hamlib 291 ./bootstrap 292 ./configure [CFLAGS="-g -O0"] 293 make 294 make install 295 296Note: Depending on the value of '--prefix' passed to 'configure', superuser 297(root) privileges may be needed for 'make install'. 298 299If you don't want the build files cluttering the source directories, do the 300following in the same parent directory of hamlib: 301 302 mkdir build && cd build 303 ../hamlib/bootstrap 304 ../hamlib/configure [CFLAGS="-g -O0"] 305 make 306 make install 307 308Note: In the examples above, passing the CFLAGS environment variable is 309optional as shown using the square brackets.. 310 311This will keep the binary output files separate from the source tree and aid 312in development by reducing clutter in the source tree. 313 314Once you've run 'bootstrap', make sure you've got some recent config.guess 315and config.sub (needed to guess your system type). Anything of at least 316year 2004 should be fine, unless you run some exotic hardware/software system 317(modern Linux distributions and Cygwin keep these up to date): 318 319 ./config.guess --version 320 ./config.sub --version 321 322The '--prefix' option to 'configure' is optional and not shown as it defaults 323to /usr/local. Convention is that locally built packages be installed in 324/usr/local away from distribution installed packages. The 'CFLAGS="-g -O0"' 325environment variable generates less optimized binaries with the '-O0' while the 326'-g' option adds debugging info which can be changed to -ggdb to generate 327debugging info for gdb. 328 329Additionally, you may want to add the '--with-perl-binding' or 330'--with-python-binding' or '--with-tcl-binding' or '--with-lua-binding' if you are 331interested in SWIG binding support for those scripting languages. 332 333For LUA bindinds if you run "lua luatest.lua" and see this error message: 334luatest.lua:44: Error in Rig::set_mode (arg 2), expected 'rmode_t' got 'string' 335This means you need to upgrade both swig and lua for 64-bit lua support 336This is known to work on swig 4.0.1 and lua 5.3.5 337 338NOTE: The bootstrap script has only to be run the first time after a fresh 339checkout or when a Makefile.am or other build file is modified or added. 340 341For a Tcl build, add this if needed: 342 343 --with-tcl=/usr/lib/tcl8.2 344 345Note: C-shell users may have to run bootstrap and make through a bourne 346shell instead, or pass "SHELL=bash" as a parameter to make. 347 348Some basic testing is accomplished with the 'make check' target which will 349run a few predetermined tests using the 'dummy' (rig model 1) backend and 350some other Hamlib functions in the build tree. This is a basic sanity check 351and cannot test all backends. 352 353Likewise, a complete test of the build system is accomplished with 354'make distcheck' which exercises a complete build sequence from creating 355a distribution tarball, building, installing, uninstalling, and cleaning 356Hamlib. All packages listed above except for Swig and Doxygen are required 357for this target as neither the bindings or old documentation are generated 358in a default build. 359 360NOTE! If Hamlib has not been previously installed as a locally built 361package you will need to make sure that 'ldconfig' is configured correctly 362and run periodically after 'make install'. Most modern distributions have 363an /etc/ld.so.conf.d/ directory where local configuration can be made. 364Later versions of Debian and derivatives have a file named 'libc.conf' in 365this directory. The contents of libc.conf are: 366 367# libc default configuration 368/usr/local/lib 369 370If your system does not have such a file, one will need to be created and 371then 'ldconfig' will need to be run as the root user so that applications 372using the Hamlib libraries can find them. 373 374 3751.3.1 Doxygen generated reference manual 376 377The following packages need to be installed: 378* Doxygen 379* GNU Source-highlight 380 3811.3.1.1 HTML manual 382 383In the top level of the build directory: 384 385 cd doc 386 make doc 387 388will build the HTML manual. The resulting 'doc/html' directory contains all 389of the files needed for the HTML manual. The 'index.html' file is the entry 390point to the manual. 391 3921.3.1.2 PDF manual 393 394To generate the PDF version of the reference manual the following texlive 395packages are required (Debian package names shown): 396* texlive-latex-base 397* texlive-latex-recommended 398* texlive-latex-extra 399 400Set GENERATE_LATEX in 'doc/hamlib.cfg.in' to 'YES' which will enable the LaTEX 401build. Then run: 402 403 make doc 404 405as above and once the run is complete: 406 407 cd latex 408 make 409 410The resulting generated document in the 'latex' directory is 'refman.pdf'. 411 412 4131.4. Feedback 414 415The Hamlib team is very interested to hear from you, how Hamlib builds and 416works on your system, especially on non-Linux or non-PC systems. We are 417trying to make Hamlib as portable as possible. Please report problems to our 418developer mailing list, hamlib-developer@lists.sourceforge.net 419 420Patches are welcome too! Just send them to the mailing list. Git formatted 421patches are preferred. Unified diff format (diff -u) is also welcome. 422Patches should apply to the current Git master branch or a testing branch, 423if possible. If you're patching against an older released version of 424Hamlib, we can take those as well but please document the release the diff 425is generated against. 426 427So far, Hamlib has been tested successfully under the following systems: 428(if your system is not present, please report to the mailing list) 429 430 * Debian i386 (plus derivatives--Ubuntu, etc.) 431 * Debian sid mipsel 432 * Raspbian armhf (Raspberry Pi Debian derivative) 433 * RedHat i386 434 * Linux ppc 435 * Slackware i386 436 * FreeBSD & NetBSD 437 * Solaris 2.6 438 * Mac OS X 439 * MS Windows: Cygwin, Mingw 440 441 4422. How to add a new backend 443 444 The rule is one backend per protocol family. 445 Try to share code between rigs of the same family, if applicable. 446 The steps in Section 3 below will need to be followed as well. 447 Version numbers used are in the form YYYYMMDD.N where the .N is 448 intended for multiple versions in one day....so typically would be .0 449 450 2.1. mkdir mybackend 451 Create a new subdir, of the name of the protocol backend. 452 NB: the directory MUST be the same as the backend name. 453 454 2.2. Add <mybackend> to the DIST_SUBDIRS variable in the topdir 455 Makefile.am (not needed for rotators) 456 457 2.3. Add the backend name to the BACKEND_LIST variable (add to 458 ROT_BACKEND_LIST for a new rotor backend or to AMP_BACKEND_LIST for 459 a new amplifier) in configure.ac. 460 461 2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom 462 of configure.ac. 463 464 2.5. Add DEFINE_INITRIG_BACKEND(mybackend); to the end of the existing list 465 in src/register.c or, for a new rotor backend, add 466 DEFINE_INITROT_BACKEND(myrotbackend); to src/rot_reg.c. 467 468 2.6. Add { RIG_MYBACKEND, RIG_BACKEND_MYBACKEND, RIG_FUNCNAM(mybackend) }, to 469 the rig_backend_list structure in src/register.c or, add 470 { ROT_MYROTBACKEND, ROT_BACKEND_MYROTBACKEND, ROT_FUNCNAMA(myrotbackend) }, 471 to the rot_backend_list structure in src/rot_reg.c. 472 { AMP_MYAMPBACKEND, AMP_BACKEND_MYAMPBACKEND, AMP_FUNCNAMA(myaotbackend) }, 473 to the aot_backend_list structure in src/amp_reg.c. 474 475 2.7. Add the new backend to include/hamlib/riglist.h or include/hamlib/rotlist.h or include/hamlib/amplist.h 476 by selecting the next higher backend ID number. 477 478 2.8. Create mybackend/Makefile.am, mybackend.c mybackend.h 479 Use 'dummy' backend as a template. 480 Here are commands for the bourne shell: 481 482 $ automake mybackend/Makefile 483 $ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status 484 485 make in topdir to rebuild all 486 487 2.9. Commit your work to your local repository. (developer access to 488 Hamlib Git required for pushing to the canonical Hamlib repository 489 (origin)) Provide patches to the mailing list: 490 (Please let N0NB know if the commands below are incorrect) 491 492 $ git status # Show uncommitted/staged/unstaged files 493 $ git add mybackend 494 $ cd mybackend 495 (The following command might not be necessary) 496 $ git add Makefile.am mybackend.c mybackend.h 497 498 While specifying each file individually as above allows for fine- 499 grained control, git offers a wildcard shortcut to add all new files: 500 501 $ git add . 502 503 Be careful! If you have other files that were created as part of the 504 build process, this command will add them too unless they match a 505 pattern in .gitignore. Always check with 'git status' first! 506 507 $ git commit -m "Initial release" Makefile.am mybackend.c mybackend.h 508 509 Note: The '-m' switch passes a short message to the Git repository 510 upon a commit. If a longer message is desired, do not use the '-m' 511 option. The editor specified in the EDITOR or VISUAL environment 512 variables will be started where a more detailed message may be 513 composed. 514 515 2.10 If you have developer access to the Git repository hosted at Source 516 Forge, you can do the following: 517 $ git push origin 518 519 Your changes will now be available to others. 520 521 5223. How to add a new model to an existing backend 523 524 3.1. make sure there's already a (unique) ID for the model to be added 525 in include/hamlib/riglist.h or include/hamlib/rotlist.h or include/hamlib/amplist.h 526 527 3.2. locate the existing backend 528 3.3. Clone the most similar model in the backend 529 3.4. Add the new C file to the _SOURCES variable 530 of the backend's Makefile.am 531 532 3.5. Add "extern const struct rig_caps <mymodel>_caps;" to mybackend.h 533 3.6. In initrigs_<mybackend> of mybackend.c, 534 add "rig_register(&<mymodel>_caps);" 535 536 3.7. Run 'make' if you have dependencies, or the following to regenerate 537 the makefile: 538 $ automake mybackend/Makefile 539 $ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status 540 541 Run 'make' in topdir to rebuild all. 542 543 3.8. Commit your work (once tests are satisfactory): 544 $ git add . 545 $ git commit -m "added <mymodel> to <mybackend>". 546 547 Note: See Note in section 2.6 above. 548 Note: The '.' character is a Git wildcard that includes all new and 549 modified files in your working tree. 550 551 The '-m' option may be omitted, in which case Git will start 552 your default editor for a longer commit message. Commit 553 messages generally have the form of a short subject line, then 554 a blank line, and then as much text (broken into paragraphs as 555 needed) as needed for a good description of the commit. 556 557 Assuming your working tree was cloned from the SF.net repository 558 or N0NB's GitHub repository, you can now issue a pull request 559 inclusion of your new model into Hamlib. 560 561 5624. Read README.betatester to test the new backend/model. 563 Report to mailing list. 564 565 5665. Basic functions: set/get_freq, set/get_mode, and set/get_vfo would be a 567good starting point for your new backend. 568 569 5706. C code examples. 571 572A C code snippet to connect to a FT847 and set the frequency of the main VFO 573to 439,700,000 Hz, using FM as the required mode, would look something like 574this. The error checking is removed for simplicity. 575 576 See tests/testrig.c 577 578 5797. Where are the GUI's? 580 581"Build it and they will come ..." 582 583Seriously, I am hoping the API's will provide a solid framework for some 584cool GUI development. I would like to see some GTK or Qt apps that use the 585hamlib API's so they can be used by end users as a nice part of the Ham shack. 586 587Starting points (not exhaustive): 588 Fldigi, CQRlog, gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog 589 590 5918. Contributing code 592 5938.1 License 594 595Contributed code to the Hamlib frontend must be released under the LGPL. 596Contributed code to Hamlib backends must follow backend current license. 597Needless to say, the LGPL is the license of choice. 598 599End user applications like rigctl, rotctl, ampctl and networked daemons should be 600released under the GPL, so any contributed code must follow the license. 601 602 6038.2 Coding guidelines and style 604 605For specific requirements for formatting the C source code, see 606README.coding_style. 607 608Any header files included from the hamlib/ directory should be enclosed in '<>': 609 610#include <hamlib/rig.h> # Per GNU GCC documentation 611 612Other included header files (backend and rig specific headers) should be 613enclosed in "": 614 615#include "yaesu.h" 616 617Contributed code should always keep the source base in a compilable state, 618and not regress unless stated otherwise. 619 620There's no need to tag the source in a patch with your name in comments 621behind each modification, we already know the culprit from commit logs 622(also see "git blame"). :-) 623 624Patches should take portability issues into account. 625Keep in mind Hamlib has to run under: 626 627 * various Linux's 628 * NetBSD, FreeBSD 629 * MacOS X 630 * Windows: MinGW/Cygwin, and VisualC++ support for rig.h 631 632Hamlib should also compile with the following common compilers: 633 634 * gcc-3.0 and gcc-3.2+ (nearly deprecated?) 635 * gcc-4.x and newer 636 * in shared and static 637 * C++ compiler against rig.h, riglist.h, rotator.h, amplifier.h 638 * clang compiler 639 640Portability issues to watch: 641 642 * C99 is probably (in 2016) a reasonable target 643 * little vs. big endian systems (use shifts or adhoc functions) 644 * 64 bit int: avoid them in API 645 * printf/scanf of 64bit int: use PRIll (cast value to int64_t) and SCNll 646 * printf/scanf of freq_t: use PRIfreq and SCNfreq 647 648Testing: 649 650 * The acid test for the build system is 'make distcheck' which will 651 make a distribution tarball, extract, configure, and build it in a 652 subdirectory, run 'make check', install it, uninstall it, and clean 653 it up. When all those tests pass, the GNU build system declares the 654 package ready for distribution. This is a good test if you have 655 touched the build system files or added a backend. 656 657 6588.2.1 Use of rig_debug() function 659 660Hamlib provides a debugging aid in the form of the rig_debug() function, It 661is essentially a wrapper around printf() and takes many of the same flags 662and conversion specifiers as the C library's various printf() functions. It 663adds an additional parameter for specifying the desired debug level for the 664output string. Six levels of debugging are defined in include/hamlib/rig.h 665and they are: 666 667 NONE No bug reporting 668 BUG Serious bug 669 ERR Error case (e.g. protocol, memory allocation) 670 WARN Warning 671 VERBOSE Verbose 672 TRACE Tracing 673 674They correspond to the use of the -v switch (from no -v switch to -vvvvv) 675to rigctl's command line. Hamlib applications can also set the debug level 676via the Hamlib API. From an application's perspective, setting a specific 677level includes all messages at that level and all at any lower level. 678 679In the library, passing RIG_DEBUG_ERR to rig_debug() limits display of that 680message to a level setting of ERR or any higher level. In this case if the 681application sets the message level to RIG_DEBUG_INFO, the message will not 682be seen. Use of a given level can show the value of a critical variable 683without the need of a TRACE level message where it can get lost in the 684stream of output produced by low-level Hamlib functions. 685 686Here are my (N0NB's) suggested use of rig_debug() levels in backends. 687 688* Many backend functions should have an initial call to rig_debug() as follows: 689 690 rig_debug(RIG_DEBUG_VERBOSE, "%s() entered\n", __func__); 691 692 The use of RIG_DEBUG_VERBOSE allows tracking the chain of function calls 693 through the backend while still keeping rigctl's output mostly 694 uncluttered by use of the -vvvv switch. 695 696* Developers will want to call rig_debug() to display values of critical 697 variable(s) in a backend function. For this RIG_DEBUG_VERBOSE 698 (rigctl -vvvv) should be a good choice as the output won't be lost in the 699 stream of RIG_DEBUG_TRACE (rigctl -vvvvv) level output by various 700 low-level Hamlib functions. It will also match the display of the values 701 of critical variable(s) with the function calls as above. 702 703* Use RIG_DEBUG_TRACE when it makes sense to see the variable(s) in the 704 context of a lot of low-level debugging output (rigctl -vvvvv). 705 706* Lower levels (BUG, ERR, and WARN) should be used where it makes sense that 707 information be printed when the user selects less verbosity. Use sparingly. 708 709Many backends do not conform to this suggestion at the moment. The use of 710the RIG_DEBUG_LEVEL values has been somewhat haphazard (at least by this 711scribe) so fixing these when working in a given backend is encouraged. 712 713If an application sets the debugging level to RIG_DEBUG_NONE, then 714rig_debug() functions will produce no output. Therefore rig_debug() cannot 715be counted on to output a message in all runtime cases. 716 717The debugging levels may be an area for consideration in Hamlib 3. 718 719 7208.3 Submitting patches 721 722Git provides tools to generate patches and submit them to the Hamlib 723developers via email. Use of these tools is preferred as Git allows credit 724to be given to the author and submitter of the patches. Alternately, 725patches can be submitted in unified format (diff -u), against the Git master 726branch or a given release (please note well which one!). Both formats make 727patches easily readable. The patches are to be sent to the hamlib-developer 728mailing list (hamlib-developer@lists.sourceforge.net). If the file is too 729big, you can send it as a compressed attachment. 730 731 7328.3.1 Changelog 733 734A ChangeLog file is no longer manually maintained. At some point it may be 735automatically generated from the Git commit log for source tarballs. 736 737Simply summarize your changes when the files are committed to Git or, if 738providing patches to the mailing list, provide a summary so the uploader can 739include it in the commit message which will show in the commit log (Git 740formatted emails will include this already). 741 742 7438.4 Git commit access 744 745Generally, volunteers can get commit access to the SourceForge Hamlib Git 746repository upon asking one of the project administrators. Sometimes we'll 747ask you! 748 749However, before your start committing, the project admins would like first 750to have a look at your "style", just to make sure you grok the Hamlib 751approach (c.f. previous section on submitting a patch). Then you'll be able 752to commit by yourself to the backend you chose to maintain. Please follow 753the rules hereunder: 754 755 * Always keep the Git repository (all branches) in a compilable state. 756 * Follow the coding guidelines 757 * Touching the frontend (files in src/ and include/hamlib) always 758 requires discussion beforehand on the hamlib-developer list. 759 * Announce on the hamlib-developer list if you're about to do serious 760 maintenance work 761 762Thanks for contributing and have fun! 763 764 765 766Stephane Fillod f8cfe and The Hamlib Group 767