Add long options like --part #1936

ndim · 2024-11-27T01:34:34Z

Switch from getopt(3) to getopt_long(3) and add a few long options as aliases to existing short options, e.g. "--help" and "--part" being aliases for "-?" and "-p", respectively.

The getopt_long(3) function is available on GNU, BSD, and the existing msvc/getopt.[ch] already implements getopt_long() on Windows. This should cover all systems avrdude supports.

Use getopt_long(3) instead of getopt(3)
Add long options from @WestfW Support options like --config --part and --port #1922 (comment)
Adapt the avrdude usage message shown by "-?" or "--help" to show the new long options.
Refine, review and finalize the set of new long options
Adapt the man page to reflect the long options
Adapt the texi manual to reflect the long options

Closes: #1922

Switch the command line argument parser from getopt(3) to getopt_long(3) and add a few long options as aliases to existing short options, e.g. "--help" and "--part" being aliases for "-?" and "-p", respectively. The getopt_long(3) function is available on GNU, BSD, and the existing msvc/getopt.[ch] already implements getopt_long() on Windows. This should cover all systems avrdude supports. Adapt the avrdude usage message shown by "-?" or "--help" to show the new long options. TODO: Adapt man page and texi manual reflecting the long options. Closes: avrdudes#1922

stefanrueger · 2024-11-27T13:41:19Z

src/main.c

+    {"quiet",      no_argument,       NULL, 'q'},
+    {"reconnect",  no_argument,       NULL, 'r'},
+    {"terminal",   no_argument,       NULL, 't'},
+    {"tty",        no_argument,       NULL, 't'},


Now that I look at the list carefully, I don't think tty is a good long option name to signify -t for the principal reason that tty describes a communication method (teletype), which is orthogonal to what -t does. Terminal input can come from a file, from a pipe, via a USB connection etc and not necessarily from a tty. I'd prefer to either have no second long option for -t, but if there is an appetite for a second option, I'd much rather have one of --interactive, --console, --avr-console, --shell or similar. We normally use the wording terminal or interactive terminal in the documentation for -t, so --terminal might be sufficient.

Could we add --terminal-command for -T (note capital T), which like -U is not interactive?

"shell" implies turing completeness. "interactive" captures the spirit well.

stefanrueger · 2024-11-27T13:42:41Z

src/main.c

+    {"reconnect",  no_argument,       NULL, 'r'},
+    {"terminal",   no_argument,       NULL, 't'},
+    {"tty",        no_argument,       NULL, 't'},
+    {"memory",     required_argument, NULL, 'U'},


--memory is a good long option name b/c it puts the focus correctly: the operations r, w and v all refer to memory and, crucially, not the corresponding file; originally -U got its name from the generic update operations it might describe, so I would also allow the mnemonic --update or, alternatively, --update-memory. I have an ever so slight preference for the latter: personally, I think long options are good in shell scripts to improve readability, so I am less worried about the length of long options. If we go with the latter, we wouldn't need --memory.

I would argue that --memory would be sufficient. The help test will get awfully long if we have tons of long options that to the same thing. And the -U flag doesn't necessary updates the memory.

IMO, --memory flash:r:myfile.hex makes way more sense than --update-memory flash:r:myfile.hex.

stefanrueger · 2024-11-27T13:44:15Z

src/main.c

+    {"noerase",    no_argument,       NULL, 'D'},
+    {"erase",      no_argument,       NULL, 'e'},
+    {"logfile",    required_argument, NULL, 'l'},
+    {"test",       no_argument,       NULL, 'n'},


-n meant originally don't write to the AVR part for -U operations, where -n would write the file to stdout instead of the AVR memory. When other ways to write to the AVR were implemented (-t, -T, ...) there was no way to test these in a dryrun as it were until the -c programmer dryrun was implemented. I now wonder whether --test should be --test-U or rather --test-update to clarify the role of that option.

stefanrueger · 2024-11-27T13:48:03Z

Cool improvement! I like this PR

MCUdude · 2024-11-28T19:03:54Z

I'm happy with the PR, but I have a few suggestions, based on my personal opinions:

The -? --help text should print all long options. Right now we're missing --config.
-O, the oscillator calibration command could have a long option --osccal.
Maybe use --interactive instead of --tty
In general, I don't see much need for lots of duplicate long options as long as the long name is descriptive.

ndim · 2024-11-29T06:07:37Z

I wonder whether -U should even get a direct 1:1 replacement long option.

A set of --read-memory and --verify-memory and --write-memory long opts with suitably adapted arguments could make more sense. And get rid of the colon problems on Windows while the argument is redefined.

I guess --(read|verify|write)-(eeprom|flash) is not flexible enough to accommodate for complex parts' memory layouts?

MCUdude · 2024-11-29T07:52:33Z

I wonder whether -U should even get a direct 1:1 replacement long option.
A set of --read-memory and --verify-memory and --write-memory long opts with suitably adapted arguments could make more sense. And get rid of the colon problems on Windows while the argument is redefined.

Good idea! But how would we let the user specify the format ( :i, :r, :m etc.)?

-read-memory flash:myfile.hex:i

ndim · 2024-11-29T14:51:27Z

I wonder whether -U should even get a direct 1:1 replacement long option.
A set of --read-memory and --verify-memory and --write-memory long opts with suitably adapted arguments could make more sense. And get rid of the colon problems on Windows while the argument is redefined.

Good idea! But how would we let the user specify the format ( :i, :r, :m etc.)?

--read-memory flash:myfile.hex:i

There are other characters which can be used as separators. Or --read-memory (i|hex)? flash:c:/foobar/myfile.hex. Or --read-from flash --write-hex myfile.hex. Or --read-from flash --write myfile.hex --format hex. Or something entirely different.

With long options, we are not constrained by the idiosyncrasies of the past.

stefanrueger · 2024-11-29T23:24:18Z

I guess --(read|verify|write)-(eeprom|flash) is not flexible enough to accommodate for complex parts' memory layouts?

Correct. Avrdude knows three operations, some 48 memories and 12 file formats. Is the suggestion for main.c to entertain some 144 long options for all (op, memory) combos? Or 1728 long options to expand the space to all (op, memory, file format) combos? There is the added difficulty that a new part in a custom config file may well introduce a new memory, which requires new long options to automatically spring up in that case.

Or --read-from flash --write myfile.hex --format hex

Projecting the -U parameter space onto these axes is a neat idea but complicates parsing, which would need to be aware that a list of more than one -U operations can be specified. Given that the format used to be optional (there are defaults depending on r/w/v) which file has the default format and which one the octal format in --read-from flash --write file1.hex --format oct --write file2.hex --read-from eeprom?

And how should the command line express -U sketch, which updates flash from the file sketch?

(i|hex)

That's another pitfall: i signifies Intel Hex files, and h a simple comma-separated ASCII list of hexadecimal numbers in the format 0x.., so hex as a long name for the format can be misleading. As would be binary or bin which could either imply raw data or a list of 0b.... binary numbers.

Also note that allowing a different way than appending :x to the file name for expressing the file format will invariably draw demands on doing that for files in the terminal syntax, too (verify flash sketch:d). So, even simple ideas will require a lot of implementation work.

All of above can be done and done well, but should it? I believe the best thing for now is to have a one-to-one long replacement option for -U and deal with novel ways to express a series of -U memory manipulations in a separate PR that can be independently implemented, critiqued and tested...

MCUdude · 2024-12-01T21:37:25Z

I think we should wrap it up and merge this PR.
We got long options, and if we can print a small help message if the user got the -U / --memory flag wrong, that could resolve most issues I think. If we also can mention the long options in error messages that mentions short options (like "clock speed too high, use -B 125kHz"), that would be really neat!

ndim · 2024-12-03T14:13:20Z

Note to self: The usage message should mention e.g. --part and possibly other long options.

ndim mentioned this pull request Nov 27, 2024

Add build information to libavrdude and avrdude and display it #1698

Draft

ndim changed the title ~~Add support for long options like --part~~ Add long options like --part Nov 27, 2024

ndim force-pushed the add-long-options-using-getopt_long branch from c012638 to 818e0e8 Compare November 27, 2024 01:45

mcuee added the enhancement New feature or request label Nov 27, 2024

stefanrueger reviewed Nov 27, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add long options like --part #1936

Add long options like --part #1936

ndim commented Nov 27, 2024 •

edited

Loading

stefanrueger Nov 27, 2024

ndim Nov 27, 2024 •

edited

Loading

stefanrueger Nov 27, 2024

MCUdude Nov 28, 2024

stefanrueger Nov 27, 2024

stefanrueger commented Nov 27, 2024

MCUdude commented Nov 28, 2024

ndim commented Nov 29, 2024 •

edited

Loading

MCUdude commented Nov 29, 2024

ndim commented Nov 29, 2024 •

edited

Loading

stefanrueger commented Nov 29, 2024 •

edited

Loading

MCUdude commented Dec 1, 2024

ndim commented Dec 3, 2024

Add long options like --part #1936

Are you sure you want to change the base?

Add long options like --part #1936

Conversation

ndim commented Nov 27, 2024 • edited Loading

stefanrueger Nov 27, 2024

Choose a reason for hiding this comment

ndim Nov 27, 2024 • edited Loading

Choose a reason for hiding this comment

stefanrueger Nov 27, 2024

Choose a reason for hiding this comment

MCUdude Nov 28, 2024

Choose a reason for hiding this comment

stefanrueger Nov 27, 2024

Choose a reason for hiding this comment

stefanrueger commented Nov 27, 2024

MCUdude commented Nov 28, 2024

ndim commented Nov 29, 2024 • edited Loading

MCUdude commented Nov 29, 2024

ndim commented Nov 29, 2024 • edited Loading

stefanrueger commented Nov 29, 2024 • edited Loading

MCUdude commented Dec 1, 2024

ndim commented Dec 3, 2024

ndim commented Nov 27, 2024 •

edited

Loading

ndim Nov 27, 2024 •

edited

Loading

ndim commented Nov 29, 2024 •

edited

Loading

ndim commented Nov 29, 2024 •

edited

Loading

stefanrueger commented Nov 29, 2024 •

edited

Loading