Loading...
Searching...
No Matches
README.developer

    Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
             (C) Stephane Fillod 2000-2011
             (C) The Hamlib Group 2000-2026

    Primary site for the latest development version of Hamlib is
    https://github.com/Hamlib/Hamlib

    Also take a look at http://sourceforge.net/projects/hamlib/
    Here you will find a mail list, and the latest releases.

    See README.md for frontend/backend outline.
    See README.betatester for background on testing Hamlib.

    The library provides functions for 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
    unified control library API, and they would not have to worry about the
    underlying connection towards physical hardware.

    Serial (RS-232) 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 2025-08-27

    $ tree -L 1
    .
    ├── amplifiers
    ├── android
    ├── Android.mk
    ├── astyle.sh
    ├── AUTHORS
    ├── bindings
    ├── bootstrap
    ├── c++
    ├── ChangeLog
    ├── CODE_OF_CONDUCT.md
    ├── configure.ac
    ├── CONTRIBUTING.md
    ├── COPYING
    ├── COPYING.LIB
    ├── cppcheck.sh
    ├── doc
    ├── docker-build
    ├── extra
    ├── hamlib.m4
    ├── hamlib.pc.in
    ├── include
    ├── INSTALL
    ├── lib
    ├── LICENSE
    ├── macros
    ├── Makefile.am
    ├── NEWS
    ├── PLAN
    ├── README
    ├── README.betatester
    ├── README.coding_style
    ├── README.developer
    ├── README.freqranges
    ├── README.macos
    ├── README.md
    ├── README.multicast
    ├── README.release
    ├── README.win32
    ├── rigs
    ├── rotators
    ├── scripts
    ├── security
    ├── SECURITY.md
    ├── Segfault-award
    ├── simulators
    ├── src
    ├── tests
    ├── THANKS
    └── VFOs.txt

    18 directories, 32 files

    1. Building

    If you just want to compile the library, please refer to the INSTALL file.  This
    document introduces hacking the code of Hamlib.

    As your objective is development, either GitHub or SourceForge (hereinafter
    "forges") offer similar work flows where a "fork" of the main repository is
    created that is your private copy.  Proposed changes that you wish to be added
    to Hamlib will be "pushed" to your repository after which the Web site (GitHub,
    at least) will offer a link to create a "pull request" that is done through the
    Web site's UI.  Once the pull request is created on GitHub, Continuous
    Integration will check your changes and then compile Hamlib on various systems
    with various configurations.  This is the main work flow of the Hamlib project.

    1.1 Obtaining sources: git clone

    Each forge offers secure methods of authentication and encryption through SSH
    and provide a special link that is used to "pull" and "push" to your fork.

    Otherwise, if you just want to clone the Git repository anonymously, each offer
    HTTPS links (SourceForge link shown):

      git clone https://git.code.sf.net/p/hamlib/code hamlib

    The clone only has to 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 either 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 SourceForge page at
    https://sourceforge.net/p/forge/documentation/Git/ for more information about
    how to use the Git repository of Hamlib hosted by SourceForge.

    GitHub has much documentation on using its platform.  Using either forge is the
    same from your working directory on your computer.  Only the "remote" name is
    different (your choosing).

    Much documentation on Git exists.  A good starting point is:

    https://git-scm.com/doc

    From this page are links to tutorials, books (Pro Git proved useful), and
    references.

    Another useful site:

    http://www-cs-students.stanford.edu/~blynn/gitmagic/

    1.1.2 Providing patches with Git outside of the forges

    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.

    Even without Git email tooling, every effort will be made to properly credit all
    contributions.

    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 or vice versa.  In this
    manner we can accommodate patches submitted against a stable release and merge
    them into master as well.

    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_level

    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 and "push" the commits to the forge.

    GitHub, at least, will return a URL that can be opened in your Web browser to
    create the Pull Request (PR).  SourceForge may offer similar capability.

    Unlike previously stated in this document, there is no need to merge your
    commits into the "master" branch before pushing.  In fact, it is preferred that
    PRs remain as a separate branch.

    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+ and both supplied by
    the Git project.  Many more are available as are many ways to integrate Git into
    your favorite editor (this crusty author prefers to work with Git in a separate
    terminal window, although "git blame" in the Vim editor is handy).  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 operating systems
    include Microsoft Windows.  Note that Hamlib is not restricted to Linux or Unix
    type systems, MS Windows is well supported.

    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-essential' 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.69                        # autoconf --version
    * automake      1.16                        # automake --version
    * libtool       2.4.6                       # libtool --version
    * Git           2.30                        # git --version
    * pkg-config    0.29.2                      # pkg-config --version (libusb)

    As of Hamlib 4.7.0 (commit e09007a), POSIX thread support (pthreads) is
    required to compile or run Hamlib.

    As of Hamlib 4.7.0 (commit d04364e), pkg-config (replaced by pkgconf for the
    most part) is required for bootstrap to install the pkg.m4 file which enables
    the pkg-config facility (bootstrap will now fail if some version of pkg-config
    is not found; its version will be checked during the autoreconf stage).

    Optional, but highly recommended:
    * GNU C++                           # Build C++ binding and INDI backend
    * swig (for bindings)               # Generate wrappers for the bindings
    * perl devel                        # For Perl binding
    * tcl devel                         # For tcl binding
    * python devel                      # For Python binding
    * pytest
    * lua devel                         # For Lua binding
    * libxml2 devel                     # xml2-config --version
    * libgd2 devel                      # gdlib-config --version (rigmatrix)
    * libindi devel                     # INDI rotators
    * libnova devel
    * libusb-1.0 devel                  # 1.0.24 or newer
    * libreadline devel                 # ver 5.2 or newer
    * zlib1g devel                      # (rigmatrix)

    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.69", autoheader "autoheader2.69",
    and automake "automake-1.16" aclocal "aclocal-1.16" 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.

    !!!BEWARE!!!  Some systems have the "Autoconf Macro Archive" package installed.
    These newer macros will conflict with similarly named macros in the 'macros'
    directory.  See GitHub issue #1746 for the gory details
    (https://github.com/Hamlib/Hamlib/issues/1746).

    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 bindings 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 (usually
    this is not the case as the build system will automatically generate itself when
    it detects its source has been modified, but once in a while...).

    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 (not recently tested)

    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.3.2 Automated tests

    Automated tests are executed running:

        make check

    The makefiles run the simple tests with automake.

    The make variable TESTS contains the tests to be run and the variables
    check_PROGRAMS and check_SCRIPTS contain the executables needed to run the tests
    that aren't built by make all.

    For more information see the automake manual at
    https://www.gnu.org/software/automake/manual/html_node/Scripts_002dbased-Testsuites.html

    1.3.2.1 C tests

    Tests written in C are available in the tests/ directory. They are run with:

        make -C tests/ check

    1.3.2.2 Python tests with pytest

    Tests written in Python are available in the bindings/python directory if Hamlib
    is configured to build the Python bindings and if pytest is installed, e.g.:

        ./configure --with-python-binding --enable-pytest

    They are run with:

        make -C bindings/ check

    The Python scripts consist in handwritten tests, meant to test realistic use
    cases, and auto-generated tests, meant to detect unwanted changes in the
    bindings. When a public symbol is added to the bindings or removed, the
    auto-generated tests must be updated:

        make -C bindings/ generate-pytests

    And the handwritten tests should be updated to reflect the change.

    The Python tests can also be run against a simulator or an actual rig, but they
    aren't guaranteed to succeed because the CI only tests the dummy rig.  To
    execute the tests from the build tree, add the path to the libraries that you
    built, using the PYTHONPATH environment variable, eg:

        PYTHONPATH=bindings/:bindings/.libs/ bindings/python/test_rig.py \
        --model 1035 --rig-file /dev/ttyUSB0 --serial-speed 4800

    Only the following long arguments are supported:

        --model ID
        --rig-file DEVICE
        --serial-speed BAUD
        --hamlib-verbose

    The argument --hamlib-verbose can be repeated as many times as the --verbose
    argument accepted by rigctl.

    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            (plus derivatives--Ubuntu, etc.)
        * Raspberry Pi OS   (Raspberry Pi Debian derivative)
        * Fedora
        * openSUSE (Leap & Tumbleweed)
        * Slackware
        * FreeBSD & NetBSD
        * MacOS
        * MS Windows: Cygwin, Mingw, can be imported into MSVC

    1.5. A word about AI

    Over the past several years the latest rage is so-called Artificial
    Intelligence, a.k.a. Large-language Learning Models (LLM).  Companies are
    pushing using AI for development.  GitHub (owned by Microsoft) seems to be
    pushing "Copilot" at every turn.  Many thoughts about this technology exist
    among Free Software developers.

    Perhaps the most questionable aspect of LLM generated code is licensing--can
    such code be licensed under the GPL/LGPL?  It's not an easy question to answer.
    Code that is written by a developer is copyrighted by that developer, presuming
    it is original work.  That does not change even when code is collaboratively
    developed and held in a common repository.  Ostensibly, the developer has
    written the code and not plagiarized that of someone else without due credit
    (certainly, it is fine to "borrow" code from compatibly licensed projects, just
    credit the project/authors and disclaim it is your original work).

    The question leads to another question, did the LLM have access to sources that
    were licensed under an incompatible license?  Could this lead to a copyright
    infringement issue?  At this time LLMs don't seem to reveal their learning
    sources and Copilot likely has access to closed sources that are hosted at
    GitHub.

    The Hamlib project accepts contributions on the "honor system".  It is implied
    that contributions are the original works of their respective authors and
    offered under the license terms of the GPL 2.0 or LGPL 2.1.  Use of LLM
    generated code breaks this model.  The contributors of such code cannot claim it
    as their own original work.

    Finally, Hamlib is a hobby project for hobbyists and as such all contributors
    should take pride in having their original work included for the benefit of many
    other radio hobbyists.  Against that backdrop, using LLM generated code seems
    like cheating.

    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
    APIs 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, Not1MM, 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 include/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
        * 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--C11/C17 will be the
          requirement for Hamlib 5.
        * little vs. big endian systems (use shifts or adhoc functions)
        * printf/scanf of 64bit int: use PRIll (cast value to int64_t) and SCNll
        * printf/scanf of freq_t: use PRIfreq and SCNfreq

    Note that 32 bit support is fading across all sectors of computing.  At some
    point limitations regarding 32 bit support will fade away.  Hamlib 5 may
    eliminate 32 bit support entirely.

    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.

    Simulators:
        * The 'simulators' directory contains programs to simulate the protocol
          of many devices.  They are built invoking "make -C simulators/ check"
          or "make check" from topdir.  While simulators are made to test Hamlib
          with rigctl and rigctld, you should be able to guess the model number
          that corresponds to a given simulator and configure an application such
          as wsjtx to use that model and the port name printed by the simulator,
          as shown in the examples below.

          To use a simulator on *nix-like systems, run its executable and take
          note of the port name:

            $ ./simulators/simft991
            name=/dev/pts/6

          Then from another terminal run rigctl/rigctld using that port and a
          matching model number (see rigctl --list):

            $ ./tests/rigctl --model=1035 --rig-file=/dev/pts/6 \get_freq
            14074000

          To use a simulator on Windows, first install a virtual COM port, then
          run the simulator passing the port name as first and only argument:

            > simulators\simft991 COM1234

          Then from another command prompt run rigctl/rigctld or your
          application.

          The COM port argument is currently ignored on *nix but it can be
          handled if there is a need to test a low level issue with RS-232
          and/or USB communication, if your machine has the needed hardware.

    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

    The forges have their own methods of submitting patches as outlined in Section 1
    above.

    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 committer 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

    The work flow of the forges greatly diminishes the need for multiple developers
    having "push" access to the main repository.  In practice this works well as it
    gives an opportunity for manual code review before being merged into "master".

    We do have simple rules that need to be followed:

        * 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