avrintel.h missing from installation

[drmpjz]

Build environment: Linux openSUSE 15.5

Sorry, not a cmake expert, so I don't have a patch :-(

Problem:
libavrdude.h ist installed in the include directory of CMAKE_INSTALL_PREFIX:PATH (e.g. /usr/include or /usr/local/include)

In libavrdude.h you have since 7.3

#include "avrintel.h"

but this is not installed to the same path, so any compilations of programs using libavrdude.h will fail.

avrdude itself just works, because it is build in the full source tree.

I've found that after the build in build_linux there is a file named install_manifest.txt, which contains a list of the files and path of all the files that final install step will distribute on the system. I expect that avrintel.h just needs to be added there.

Unfortunately I did not find an (to me) obvious place in the build systems to do so.

[mcuee]

It seems to me we need to change the following file.
https://github.com/avrdudes/avrdude/blob/main/src/CMakeLists.txt

Unfortunately I also do not know much about CMake and I do not know how to fix it.

[drmpjz]

Maybe here?

set_target_properties(libavrdude PROPERTIES
    PREFIX ""
    PUBLIC_HEADER "libavrdude.h"
    VERSION 1.0.0
    SOVERSION 1
    )

PUBLIC_HEADER seems to be the keyword. Now this only needs to be a list.

P.S. I have tested that if I copy avrintel.h manually to /usr/include both compilation of the program works and the resulting binary also works as expected.

[drmpjz]

PUBLIC_HEADER "libavrdude.h;avrintel.h"

seems to do the trick (still no cmake expert, only stackoverflow knowledge...)

[mcuee]

@Youw

Sorry to disturb you. Just wondering if the work-around by @drmpjz is correct or not. Thanks.

[ndim]

So it appears that the header part of the API is for libavrdude users to #include <libavrdude.h>, and that libavrdude.h file then unfortunately does #include "avrintel.h" without libavrdude actually installing avrintel.h.

(I have not found any examples for a libavrdude user within the avrdude sources, or any libavrdude users for that matter. The avrdude utility is not easily separable from libavrdude in the current source code tree, with the code for both being mixed inside the same directory src/.)

The addition of #include "avrintel.h" to libavrdude.h is a relatively recent addition from the 2023-11-23 commit fd1c49e by @stefanrueger which also happens to remove #include "avrintel.h" from a number of compilation units which all #include <libavrdude.h>.

That patch adds three function prototypes to libavrdude.h, one of which actually use the Configitem_t type which is defined inside avrintel.h:

const Configitem_t *avr_locate_config(const Configitem_t *cfg, int nc, const char *name);
int avr_get_config_value(const PROGRAMMER *pgm, const AVRPART *p, const char *cname, int *valuep);
int avr_set_config_value(const PROGRAMMER *pgm, const AVRPART *p, const char *cname, int value);

The commit message only mentions the two _set_ and _get_ functions and makes no mention of the avr_locate_config function which actually requires the Configitem_t type and therefore the inclusion of avrintel.h from libavrdude.h.

So adding #include "avrintel.h" and the avr_locate_config function appears like an unintended change to the library API.

The quick workaround is to install avrintel.h, but that will expose a LOT of machine generated AVR part related constants as part of the libavrdude.h API, which looks like a future nightmare to maintain compatibility-wise. Besides, the point of APIs and ABIs is to be small.

The avrintel.h file contains a note that it is generated by mkavrintel.pl which is not part of the avrdude source code repository, and mkavrintel cannot be found on the internet with a search engine either. Perhaps mkavrintel.pl could be included in the avrdude repo and rewritten to split off the typedef for Configitem_t from the avrintel.h with all the parts related constants? Or, if mkavrintel.pl has disappeared and avrintel.h now must be maintained by hand, split off the public types part from a private types part and private constants part?

BTW, I do not see any changes to library symbol versioning or soname or similar corresponding to adding these three functions to the ABI. That might be due to my eyes being unused to cmake after 20+ years of working with automake+libtool in the libgphoto2 buildsystem, but the ABI related definitions inside src/CMakeLists.txt appear to originate from 2022-01-11 commit 8be18c7 by @yegorich and have not been changed since.

If the libavrdude library is intended as a serious way to use the avrdude code, it might be interesting for the future to separate the source code for the libavrdude library and the avrdude utility by keeping it in separate subdirectories, e.g. inc/ for the public library headers, lib/ for the library code and src/ for the utility code. Then avrintel.h would have been inside the lib/ subdir for all its library internal constants, and compiling the avrdude utility would have failed due to it not having access to avrintel.h.

From my experience with libgphoto2 + libgphoto2_port + gphoto2 I would recommend keeping everything one source code repository avrdude with one buildsystem, but separating the library and the utility within that one source code repo's build system (inc/, lib/, src/). Splitting things into different buildsystems and splitting into different repos when all you are doing is coordinated releases causes a lot of extra work for very close to no benefits, so I would refrain from that.

BTW, where is the libavrdude library API and ABI documented, and how are library users supposed to find the library? Just try the default include and linker path? Some modern library allow themselves flexibility for future incompatible API changes by installing their header files into PREFIX/include/foo-1/foo.h. So library users would use -IPREFIX/include/foo-1.0 and then use #include <foo.h>, as discovered by a foo-1.pc pkgconfig file. The corresponding library soname would then be something like libfoo.so.1.

Not sure how far you can get with symbol versioning when targeting Linux, BSDs, OSX, Windows, so classical library soname and header location is probably the way to go.

[ndim]

As we only need a pointer to that type in libavrdude.h, we could use an incomplete type in libavrdude.h, without needing to include avrintel.h from libavrdude.h.

That would be my proposed resolution to this issue.

[drmpjz]

Thanks a lot for your serious consideration of this issue!
As for the "are there users of libavrdude out there part", I know of at least one and that is actually the reason why I am building avrdude :-)
My wife is working in STEM/MINT education and one of the systems they use is the Bob-3 microcontroller (https://www.bob3.org/en/) which uses bobdude (https://www.bob3.org/de/details/software) to transfer the Hex code to the microcontroller. Currently this is sitting on-top of a very old version of avrdude and I am trying to submit a patch to the maintainer of bobdude to bring it up to a modern version. It worked with 7.2 after I submitted a patch earlier. Unfortunately I had an accident and was delayed in sending the patch after 7.2 was released. So I was just about to enter "send" on the patch submission (literally!) when I noticed 7.3 was out and decided to double check for new issues before submitting a problematic patch.

[ndim]

For completeness' sake: My role here is that I have been involved with Fedora's avrdude packages since about 2011, and that I have recently contributed a few simple fixes around building avrdude, mostly with the autotools based buildsystem. So I lack the institutial knowledge a seasoned member of the avrdude development team would know, such as e.g. libavrdude users - and I want to learn more.

[ndim]

As we only need a pointer to that type in libavrdude.h, we could use an incomplete type in libavrdude.h, without needing to include avrintel.h from libavrdude.h.

That would be my proposed resolution to this issue.

Is the avr_locate_config() function even supposed to be part of the public API? The only use of the avr_locate_config() function appears to be in src/avrpart.c, which is part of libavrdude itself, but not the avrdude utility. I do not see any other compilation unit using avr_locate_config()... so this might be just a library internal function?

In that case, we could remove avr_locate_config() from libavrdude.h completely, and therefore the #include "avrintel.h" as well.

[dl8dtl]

PUBLIC_HEADER "libavrdude.h;avrintel.h"

seems to do the trick (still no cmake expert, only stackoverflow knowledge...)

The idea behind libavrdude.h was that it's exactly one public header file that is needed and needs to be published.

There used to be a dozen (or more) files in the past, and we once cooked the public part into a single file.

So the correct method would be ndim's proposed solution to use a pointer to an incomplete struct.

[dl8dtl]

Is the avr_locate_config() function even supposed to be part of the public API?

Good question. ;-)

[Youw]

@mcuee yes, from CMake perspective, updating PUBLIC_HEADER would do the trick.

But @ndim is right. No need to actually include the header. Forward-declare some types for the API function will be enough.

[stefanrueger]

TLDR; I think it's best to install avrintel.h as sibling file to libavrdude.h.

The long of it.

As AVRDUDE obtained a better model of the 350+ parts, 150+ programmers and their interaction, it needed to know more about the parts than was reasonable to put into the user-modifiable avrdude.conf file; amongst the new things were interrupt vector names (needed by urclock), bit-level fuse configuration (needed by the terminal config command) and register file info (needed by terminal regfile). These tables and some access functions ended up in avrintel.[ch]. At some point there was a request to put avrintel into libavrdude, which makes sense, as avrintel.c contains stuff that might be useful for projects that roll their own programmer interface.

While libavrdude.h brought together a dozen or so individual header files that the AVRDUDE project used to have, it looked impractical to put the contents of avrintel.h into it because both avrintel.c and avrintel.h are generated by an ugly meta-program that sources and consolidates intelligence from avr-libc, the .atdf files, avrdude.conf, errata files and some hand-inserted errata from data sheets. When a new .atdf comes out or new errata become known, the meta-program generates a new avrintel.h file.

Maintenance-wise the easiest is to break the rule that there is only one header file for libavrdude and put a second header file as a sibling into the directory wherever libavrdude.h lives. Other solutions are possible, but forward-declaring some types for the API won't give the libavrdude user the same functionality as the full header file.