Re: [Hamlib-developer] Hamlib backend file structure for large backends

[Mikael N. <mik...@fa...>]

Hi George,

Thanks for your input, please see my comments below!

On Sun, Dec 21, 2025, at 20:55, George Baltz wrote:
> [Sorry, personal/ham time is in short supply this time of year, so this 
> is a bit rushed. More may follow]
>
> On 12/20/25 12:07 PM, Mikael Nousiainen wrote:
>> Hello Hamlib developers!
>>
>> There's been some recent discussion in Hamlib PR #1961 (see https://github.com/Hamlib/Hamlib/pull/1961) about the device backend file structure. Some backend, such as the new Yaesu FTX-1 backend have grown rather complex and with the upcoming addition of Icom network protocol support and full-featured FlexRadio backend (with audio and I/Q data streaming!) are only likely to make the backend sizes larger (these will be part of the ARDC Hamlib improvement project, also announced recently on this mailing list and in the GitHub PRs).
>>
>> Traditionally, most of the backends (for a single device type - or its variants) has been placed in a single source file. However, as these files grow up to several thousand lines long - or possibly even larger, to over 10k lines - it can be argued that managing the source code becomes more difficult. Additionally, splitting backend code into logical parts might make sharing common code across similar backends easier.
> Missing one very important detail - backends for most rigs are made up 
> of *two* files; one specifically for the rig and one for the 
> vendor(e.g., rigs/icom/icom.c, rigs/yaesu/newcat.c, etc) that is shared 
> by all rigs from that manufacturer. AFAICT the previous development 
> would start with the common file and add replacements for any of the 
> common routines necessary to handle the new rig. Checking if a similar 
> function existed in another rig file may not have happened.

Agreed - though there are some significant inconsistencies here: in some cases the "common routines" simply contain huge if-else blocks to handle each specific rig, which is not really optimal regarding what I think a clean backend implementation would be. In an optimal case, the "common routines" would only contain code that can be directly re-used by the individual backends (or somehow parameterized, e.g. with custom subcommand numbers as parameters - like a Yaesu EX-menu command could work) - and it wouldn't handle any specific model, maybe unless there are only a handful of variations to a command.

>> As potential alternatives to single-file backends, there is already one proposal in the FTX-1 backend PR and I personally added another one.
>>
>> Here are all of the 3 options that have been discussed so far:
>>
>> 1) Traditional, single-file backend - no matter the size of the file
>>
>> 2) The current PR # structure (files split in two directories): main backend files (ftx1.c and ftx1.h) + README are in rigs/yaesu directory and the rest of the files are in rigs/yaesu/ftx1 directory
>>
>> 3) Similar multi-file backend as in PR #1961, but all of the files (including ftx1.c, ftx1.h and README) are placed in a backend-specific subdirectory, e,.g. rigs/yaesu/ftx1.
>>
>> Personally, I'd prefer option 3 - but *only* for multi-file backends.
> Personally, I'd prefer option 1.  Putting these files into a 
> subdirectory means the chances of reusing them (or even looking at them) 
> drops to about zero.
>>
>> For a single-file backend, we could still use the current convention (of not having a separate subdirectory for the backend). So as a summary, this is a question of adding subdirectory for multi-file backend. And IMO there's definitely no point in starting to convert any of the existing backends - unless changes are being made to them and they grow significantly larger.
>>
>> Since there's already the FTX-1 backend PR under review that would benefit from this discussion, I think everyone would appreciate if we can make a decision reasonably quickly :)
>>
>> Please share your thoughts!
> You asked for it :-)
>
> Part of the problem with the size of backends is that although Hamlib 
> has data structures to describe the capabilities of the rig, there is no 
> table-driven description of the command structure/syntax to actually do 
> anything.  So it all is done by individual code paths.  Tie together the 
> Hamlib function, the rig model and the command, and a lot of that code 
> could go away.

True - there's a lot of simple refactoring that could be done.

>
> Case in point: PR #1952.  Replaces almost all of the logic that computes 
> which command to send with preset templates ready to apply the function 
> values to and ship out to the rig; uses data already in the rig 
> capabilities to define those templates.  And I noticed (after the fact) 
> that 3 of the 4 voice_mem() functions in the Elecraft backend can now be 
> removed by adding a few more lines to kenwood_init() and using the 
> common code in kenwood.c.

Exactly. There is indeed a lot of cleanup to be done.

However, what I'm after with my file structure proposal (option 3) is that, even WITH your points considered (clear separation between common and model-specific code + refactoring of repetitive code constructs done), more complex transceivers end up having complex backends with usually plenty of model-specific code (no manufacturer seems to case about consistency, there will be lots of exceptions to "rules"). In this case, I think having multiple files for a single backend will help maintainability and readability.

I'm already seeing this is the case with FTX-1 - lots of the commands are FTX-1-specific (although some smaller parts of the FTX-1 backend could probably made more generic, e.g. the EX menu command routines).

What I'm after here is to establish a guideline for larger backends: what's the convention we should follow with more complex backends. Most backends would do just fine with a single file!

Additionally, we could document some of the backend development process rules where what you've stated in your message are top priority: making sure the "common routines" are used to full extent and that the code doesn't use repetitive constructs (that are also prone to bugs).

We could certainly extend the existing developer docs with these guidelines: https://github.com/Hamlib/Hamlib/blob/master/README.developer

73,
Mikael OH3BHX