Document elf2tag script

[ndim]

This aims to add documentation to the elf2tag script (installed to $(bindir) by default):

• Add -h and --help argument handling to print the usage information.

• Add a very basic man page elf2tag.1.

  Some distributions encourage having man pages (e.g. Fedora), some other distributions require a man page for each executable in $(bindir) (e.g. Debian).

  It makes sense to concentrate this documentation effort at the place common to all distributions, i.e. upstream, i.e. here.

TODO:

• Build elf2tag.1 from elf2tag.1.adoc using the update-elf2tag-manpage script as git precommit hook, CI command, or buildsystem command, or just commit elf2tag.1 without elf2tag.1.adoc and update-elf2tag-manpage (like the avrdude.1 file)?

• Is the example command with avrdude disasm accurate?

[stefanrueger]

Cool idea!

[ndim]

Does this need any additions?

ELF2TAG(1)                     avrdude Manual                     ELF2TAG(1)

NAME
       elf2tag - output a tagfile for the avrdude disasm command

SYNOPSIS
       elf2tag <file.elf>

       elf2tag [-h | --help]

DESCRIPTION
       elf2tag generates a tagfile for use with the avrdude disasm command.

OPTIONS
       -h --help
           Prints the help message and exits.

EXAMPLES
           $ elf2tag file.elf > file.tag
           $ avrdude -t ...
           avrdude> ...
           avrdude> disasm -t=file.tag ...

AUTHORS
       elf2tag was written by Johannes Bauer with small modifications by
       Stefan Rueger.

SEE ALSO
       avrdude(1), avr-nm(1), avr-objdump(1)

avrdude                          2024-09-04                       ELF2TAG(1)

[stefanrueger]

Is the example command with avrdude disasm accurate?

@ndim Here a more extensive example using blink.elf compiled for ATmega328P as input:

$ elf2tag blink.elf  >blink.tag
$ avrdude -qq -c dryrun -p m328p -U blink.elf -t
avrdude> disasm -t=blink.tag flash 0 512

[ndim]

I have updated the example in the elf2tag.1 man page.

ELF2TAG(1)                      avrdude Manual                     ELF2TAG(1)

NAME
       elf2tag - output a tagfile for the avrdude disasm command

SYNOPSIS
       elf2tag <file.elf>

       elf2tag [-h | --help]

DESCRIPTION
       elf2tag generates a tagfile for use with the avrdude disasm command.

OPTIONS
       -h --help
           Prints the help message and exits.

EXAMPLES
           $ elf2tag blink.elf > blink.tag
           $ avrdude -qq -c dryrun -p m328p -U blink.elf -t
           avrdude> disasm -t=file.tag flash 0 512

AUTHORS
       elf2tag was written by Johannes Bauer with small modifications by
       Stefan Rueger.

SEE ALSO
       avrdude(1), avr-nm(1), avr-objdump(1)

avrdude                           2024-11-20                       ELF2TAG(1)

[ndim]

Still TODO: Whether and possibly how to hook updating src/elf2tag.1 from src/elf2tag.1.adoc into pre-commit, CI, builds, and whether to commit src/elf2tag.1.adoc at all.

This is a matter of running the src/update-elf2tag-manpage script in a git clone (can be shallow) and then reacting if the src/elf2tag.1 file now has changes.

[ndim]

BTW, the "Build / macos-x86_64" CI fail is fixed in 8fc665f which is part of #1934.

[stefanrueger]

\-t=blink.tag

[ndim]

Fixed.

[ndim]

And the CI has caught me forgetting to fix the generated src/elf2tag.1 file. Fixed. This time, really.

[ndim]

The comment on the macos CI builds failing from still applies, but now for both the cmake and the automake build. Still both issues are fixed or worked around by b8594d1 from the #1934 PR.

[ndim]

@stefanrueger Do you have any preferences on hooking the src/update-elf2tag-manpage script into something? I can think of a few options to do that to help ensure that src/elf2tag.1 and src/elf2tag.1.adoc are always committed in sync with each other:

• CI rejecting pushes (looks the easiest to implement and most comprehensive in catching mismatches). Either as part of build.yml or as part of check-sourcecode.yml or as a separate github workflow which would just clone avrdude, install asciidoctor, run the update script and then fail if that has changed src/elf2tag.1.
• CI fixing commits on push (I would not want to implement giving CI jobs the power to change commits)
• cmake/automake build running src/update-elf2tag-manpage on developer machine. Only runs on builds.
• git pre-commit hook to run on developer machine. Depends on on developer setting that up.

[ndim]

Haha. The CI check just caught me forgetting to run the update script after the quick fix changing file.tag to blink.tag.

I hereby formally suggest the CI check as a way to hook up the update script.

[stefanrueger]

Cool work @ndim! I don't really have an opinion on how to deal with the workflows here (principally, b/c I have very little understanding about the ramifictions that the suggested CI/Cmake/automake changes have). So, yes, please feel free to implement a sensible solution.

[ndim]

Checking this in CI adds no requirement to install asciidoctor to everybody who clones and works with the avrdude repo, just for people editing src/elf2tag.1.adoc which should be rare.

However, it still catches all pull requests which either

• modify src/elf2tag.1.adoc without running src/update-elf2tag-manpage to propagate their changes to src/elf2tag.1
• modify the generated src/elf2tag.1 without editing the sources in src/elf2tag.1.adoc

therefore ensuring consistency between the partially redundant information in src/elf2tag.1.adoc and src/elf2tag.1.

This principle could be applied to other generated files as well.

[ndim]

AFAICT, this is ready to merge.