landley / toybox

toybox
http://landley.net/toybox
BSD Zero Clause License
2.33k stars 328 forks source link

When I call any applet with the --help option, please show this general information first #50

Closed unforgettableid closed 3 years ago

unforgettableid commented 7 years ago

Hi! When I call any applet with the --help option, it would be good if you could please start the output with the following lines, then a newline.

Toybox multi-call binary $(git describe) Web page: http://landley.net/toybox/ Bug reports: https://github.com/landley/toybox/issues Feedback: http://lists.landley.net/listinfo.cgi/toybox-landley.net Contributors, see: https://landley.net/toybox/cleanup.html#intro

Some users have Toybox because it came preinstalled on their device. The above information will make it easier for such users to figure out where and how to submit bug reports and patches.

git describe looks at tag names and commits, and hopefully outputs a version number like "0.7.1-106-g409a8e0" or "0.7.2".

d4rken commented 7 years ago

Toybox multi-call binary $(git describe)

Why not reorder and make it

Toybox $(git describe) multi-call binary.

which would be analog to

BusyBox ...... multi-call binary.

and allow nice parsing of binary type and version.

unforgettableid commented 7 years ago

The GNU standards point out that putting the version number at the very end of the line (with no trailing period) is easier to parse. BusyBox also prefixes their version numbers with an unnecessary letter 'v' (as in "BusyBox v1.21.0.git (2012-10-17 00:34:21 PDT) multi-call binary.") which makes their version numbers even harder to parse.

The GNU coreutils follow this standard, and so does GNU Emacs, though GNU Bash doesn't.

Someone should contact the BusyBox folks, either in their Bugzilla or on their mailing list. @d4rken, you could do it if you like. :)

landley commented 3 years ago

Does efb8060a591b cover it?

enh-google commented 3 years ago

anyone wanting more specifics on Android in particular should see the commentary on https://github.com/landley/toybox/issues/230 to learn why this is probably as good as it gets. (TL;DR: Android prohibits that kind of thing across the tree to minimize incremental OTA package sizes.)

unforgettableid commented 3 years ago

Dear @landley:

efb8060 covers this issue partially but not fully.

Dear @enh-google:

Once the 250 bytes or so of enhanced help roll out to a device once, they need never roll out again, thanks to binary diffs. It's true that every rewritten page of flash is wear and tear, but I don't think that eMMC failure is very common.

The majority of individuals connect to Wi-Fi regularly. I'm not sure that such individuals need to receive OTA updates over mobile data. They can generally use Wi-Fi instead.

If your closing affects Android only, I wonder if you could please reopen this so that it might perhaps be implemented on other Toybox builds?

enh-google commented 3 years ago

Dear @enh-google:

Once the 250 bytes or so of enhanced help roll out to a device once, they need never roll out again, thanks to binary diffs.

it was specifically the idea of including a date or SHA or whatever -- something that does change because its purpose is to uniquely identify which version you're running -- on the other bug that was merged into this that i was talking about. just adding a website link or whatever is fine.

If your closing affects Android only, I wonder if you could please reopen this so that it might perhaps be implemented on other Toybox builds?

the default toybox build already does include details of the git revision and how many changes past the last release you are. it's only Android that turns that off.

unforgettableid commented 3 years ago

I've created pull request #236, which fixes this issue partially but not fully.

For a more-complete fix, we'd also need to prepend all four web links to the help for each individual applet.

enh-google commented 3 years ago

For a more-complete fix, we'd also need to prepend all four web links to the help for each individual applet.

that seems like a bad idea... even the FSF only have two lines of spam in --help! busybox seems to manage with zero.

unforgettableid commented 3 years ago

Fair point. OK; let's prepend just one line to every applet's --help text:

This is part of Toybox <http://landley.net/toybox/>.

This will help Android users to realize that they're using Toybox. This knowledge, in turn, will help them figure out where bug reports and patches should go.

Makes sense?

landley commented 3 years ago

Hmmm, that is a thing busybox does, true. I was thinking "ls -l $(which ls)" shows it's toybox, but that may be a bit "inside baseball" for a wider audience?

In fact that's where busybox sticks their --version info, ala "BusyBox v1.31.0 (2019-08-13 06:54:37 CDT) multi-call binary." which seems like it would conflict with the above android policy except on my "android 10, August 5, 2020 security update" phone typing "bzip2 --help" says "bzip2, a block-sorting file compressor. Version 1.0.6, 6-sept-2010" so I don't understand what this policy prohibits?

Anyway, I could move the "Toybox multicall binary URL" line currently in toybox --help to above the "usage" line and just have the help plumbing emit that (plus a blank line so usage: still stands out) for everybody.

Elliott: what's your opinion here? Leave it alone, make the existing line common as-is, or add the line and have the plumbing stick --version into it as seems to be the common case elsewhere? Either would be a fairly small source change...

landley commented 3 years ago

And now that I try to reproduce this the next day, I'm not seeing most commands having something before the usage: line. (Huh?) more --help, kmod --help, ss --help, pwd --help... less --help grabs the terminal and waits (of course it does),,,

enh-google commented 3 years ago

Is it only if you explicitly say busybox as argv[0]? I've never actually installed links to busybox.

On Wed, Aug 19, 2020, 11:35 Rob Landley notifications@github.com wrote:

And now that I try to reproduce this the next day, I'm not seeing most commands having something before the usage: line. (Huh?) more --help, kmod --help, ss --help, pwd --help... less --help grabs the terminal and waits (of course it does),,,

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/landley/toybox/issues/50#issuecomment-676592104, or unsubscribe https://github.com/notifications/unsubscribe-auth/AMVLEWAW6RTXVGD5PHMDGTLSBQLP3ANCNFSM4CQYQGAA .

landley commented 3 years ago

Oh busybox is consistently saying it for all commands, which does raise the question of if "toybox sed --help" and "make sed; ./sed --help" standalone should behave differently which I WANT to say know but the word "multiplexer" in the standalone version... blah.

No, when I first did this I was running lots of random commands out of debian's $PATH and seeing them stick ID lines before usage: in their --help output, and the random sample I ran the NEXT day was all commands that didn't. (Random samples: fun for the whole family.)

Unfortunately, a loop trying to run all the commands in the $PATH with --help to get actual statistics hits "blueman-adapters --help" ignoring the --help and popping up a GUI window, or "less --help" displaying its output through less and waiting for you to press a key. (The blueman one seems to be a failure of regression testing, blueman-browse --help merely spits a screenful of gtk init messages to stderr and THEN outputs help text. Of course the Defective Annoying SHell doesn't understand that "--help" is even an option, and that's got to be a design decision from those guys. Who cares WHAT everyone everywhere else does, this one standards document does not require it there for we can't do it!)

unforgettableid commented 3 years ago

@landley: Dunno.

For me, all the BusyBox commands I've tried always show an information line before the usage statement.

For example:

$ busybox less --help
BusyBox v1.27.2 (Ubuntu 1:1.27.2-2ubuntu3.2) multi-call binary.

Usage: less [-EIMmNSh~] [FILE]...

View FILE (or stdin) one screenful at a time

        -E      Quit once the end of a file is reached
        -I      Ignore case in all searches
        -M,-m   Display status line with line numbers
                and percentage through the file
        -N      Prefix line number to each line
        -S      Truncate long lines
        -~      Suppress ~s displayed past EOF
unforgettableid commented 3 years ago

@landley: I'm using an old version of BusyBox, though.

landley commented 3 years ago

You know that line in the busybox faq about "work is underway on new options such as make standalone to build separate binaries for each applet"? (In https://busybox.net/FAQ.html#design ?) Yeah, I added that in 2006: https://git.busybox.net/busybox/commit/?id=aaffef4d33 and it was referring to http://lists.busybox.net/pipermail/busybox/2005-March/013939.html which kinda went away when I left.

"Should standalone busybox commands do this" is not a question the busybox developers I handed the project off to ever really asked because they didn't bother to finish/maintain the capability. Toybox can, so I have new questions to ask.

unforgettableid commented 3 years ago

@landley:

Should standalone Toybox commands announce that they're part of Toybox?

Definitely. People want to know where to send feedback to.

The --help text could start with:

This is a Toybox standalone applet. Website: <http://landley.net/toybox/>.

Makes sense?

landley commented 3 years ago

1) Toybox commands have never been java applets, they're "commands".

2) If you type "insmod --help" you just get usage and options, no contact info. Same for mount, fdisk, route, git... Not obscure commands?

The "identify yourself" thing seems to have at least started as FSF self-promotion, which would argue against it being useful.

unforgettableid commented 3 years ago

1.

You could instead say:

This is a standalone Toybox tool. Website: <http://landley.net/toybox/>.

Or:

This is a standalone Toybox utility. Website: <http://landley.net/toybox/>.

2.

You mentioned insmod, mount, fdisk, route, and git. In their man pages, all five tools mention a website URL and/or developer contact information. On Android, there's no man command, so that won't work.

Most of these tools do identify what package they came from, though, at least in their ‑‑version output.

I think that it would be wise for you, too, to mention Toybox by name, in each command's ‑‑version output.

You've now raised doubts in my mind. If you also mention Toybox by name in your ‑‑help output too, is that useful, or is it spam? I'm no longer sure.

Maybe @enh-google, @d4rken, and/or someone else will weigh in. If they don't, maybe it'd indeed be best to leave it out of the ‑‑help output.

It's probably true that more people know about ‑‑help than ‑‑version. But I'm not convinced that this is a good-enough reason to spam all ‑‑help users with mention of Toybox.

enh-google commented 3 years ago

i don't have a strong opinion on this. i'm not super convinced there's a problem here, but i also admit that by definition we don't know about those people who don't find us.

a link in --version seems completely fine, if only because it helps put something like "0.8.1" into context. is that new or old? a couple of years old or a decade old?

the top-level --help seems fine too, though by the time you're typing toybox --help you're 99% of the way there on your own anyway.

as long as it's at the top of the individual toy --help, i think that's fine too. i'm less keen on the GNU style of putting it at the bottom --- on a terminal, the last lines are the most precious. and busybox is precedent for putting it at the top of every command's --help. i assume rob would know if that had caused any upset over the years (and can't imagine that it would have).