Easily configurable license information

[epage]

Issue by Dantali0n
Friday Mar 27, 2020 at 15:01 GMT
Originally opened as clap-rs/clap#1768

---

Describe your use case

Some types of software licenses, in particular GPL and friends, require licensing information to be displayed by the program upon request. Naturally this can already be configured with clap by creating a flag similar to -h/--help, however, I think this can be improved

Describe the solution you'd like

A more seamlessly integrated solution similar to .author() would improve this. The license() function could take sufficient arguments to automatically generate the licensing excerpt. for instance: .license(gplv3, 'MyNiceCompany.inc').

Calling the program with --license could generate the following:

Copyright (C) 2020 MyNiceCompany.inc
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

[epage]

Comment by CreepySkeleton
Friday Mar 27, 2020 at 15:06 GMT

---

Sounds good to me. @pksunkara @Dylan-DPC @TeXitoi what do you think?

[epage]

Comment by pksunkara
Friday Mar 27, 2020 at 17:08 GMT

---

This is more similar to version flag and setting.

[epage]

Comment by Dylan-DPC
Wednesday Apr 01, 2020 at 22:10 GMT

---

@Dantali0n thanks for the request. In this case it is better we make it a separate crate and see how it goes and then later merge it into clap if needed. Would you like to volunteer to write it? (we can mentor). Else will try myself or get someone to write it

[epage]

Comment by Dantali0n
Thursday Apr 02, 2020 at 17:48 GMT

---

@Dantali0n thanks for the request. In this case it is better we make it a separate crate and see how it goes and then later merge it into clap if needed. Would you like to volunteer to write it? (we can mentor). Else will try myself or get someone to write it

Hi, In terms of experience I don't think I am there yet as I am written my very first rust program atm. Currently I am still struggling with a lot of construct in rust, in addition, I tend not to have a lot of free time. Therefor, I think it is better if someone else tries to implement this, assuming someone has time and feels motivated to do so ofcourse.

[epage]

Comment by TheAlgorythm
Monday Nov 08, 2021 at 17:44 GMT

---

I did a bit of research on the UX of displaying the license. There are mainly 2 options:

A separate version subcommand

• Most modern CLIs support a --version flag and a version command, where --version is a short, one-line machine-readable output and version is more detailed (and optionally machine readable).
• The version command can include more detailed information, such as the backing API version or server version, git commit, build date/host, dependency versions, links to legal information, release notes, etc. It’s sort of like an “About” page on installed software.

Opinion of Cody Ray

$ mycli version # multi only
$ mycli --version
$ mycli -V

Unless it’s a single-command CLI that also has a -v,--verbose flag, $ mycli -v should also just display the CLI version. It’s frustrating to run 3 different commands to get the version for a CLI until you find the right one.
The version command is a main place you’ll ask users for debugging information so it’s a good place to add any helpful extra information aside from just the version number that might help you diagnose issues.

Jeff Dickey

This is an elegant solution but has the downsides of possibly breaking compatibility and Imho the version subcommand isn't well known.

Additional information in version-flag

The standard --version option should direct the program to print information about its name, version, origin and legal status, all on standard output, and then exit successfully. [...]
The first line is meant to be easy for a program to parse; the version number proper starts after the last space. [...]
The following line, after the version number line or lines, should be a copyright notice. If more than one copyright notice is called for, put each on a separate line.
Next should follow a line stating the license, preferably using one of abbreviations below, and a brief statement that the program is free software, and that users are free to copy and change it. Also mention that there is no warranty, to the extent permitted by law. See recommended wording below.
It is ok to finish the output with a list of the major authors of the program, as a way of giving credit.
Here’s an example of output that follows these rules:

GNU hello 2.3
Copyright (C) 2007 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

You should adapt this to your program, of course, filling in the proper year, copyright holder, name of program, and the references to distribution terms, and changing the rest of the wording as necessary.
This copyright notice only needs to mention the most recent year in which changes were made—there’s no need to list the years for previous versions’ changes. You don’t have to mention the name of the program in these notices, if that is inconvenient, since it appeared in the first line. (The rules are different for copyright notices in source files; see Copyright Notices in Information for GNU Maintainers.)
Translations of the above lines must preserve the validity of the copyright notices (see Internationalization). If the translation’s character set supports it, the ‘(C)’ should be replaced with the copyright symbol, as follows: ©
Write the word “Copyright” exactly like that, in English. Do not translate it into another language. International treaties recognize the English word “Copyright”; translations into other languages do not have legal significance.

The GNU Standard which could be a bit too GNU specific and hard to implement in an generic way.
But I think that should be the ultimate goal.

[epage]

Comment by epage
Monday Nov 08, 2021 at 17:52 GMT

---

Do clap users need to list all of the legally relevant licenses and notices or just the license and attribution for their own program, leaving the rest to another file like with cargo-about?

[epage]

Comment by TheAlgorythm
Monday Nov 08, 2021 at 19:13 GMT

---

Idk, I'm not a lawyer.