Install manpages via make install, also add some autogenerated manpages by nomnombtc · Pull Request #8608 · bitcoin/bitcoin

nomnombtc · 2016-08-27T00:44:27Z

This adds a new option --enable-man to configure, so manpages can be installed via make install.
This option defaults to yes, but opt out of the manpage installation is possible by running ./configure --disable-man (or --enable-man=no)

As the license situation of the contrib/debian manpages is that most of them are GPL it was not 100% clear if they can be included here, also they are incomplete anyway so I let help2man create a few manpages from the 0.13.0 binaries and included them.

The script used to generate them has also been added to contrib/devtools.

This targets #7626 but was also briefly discussed in #8568

luke-jr · 2016-08-27T02:22:22Z

configure.ac


+# Enable manpages
+AC_ARG_ENABLE(man,
+    [AS_HELP_STRING([--enable-man],


Normally we use --disable-* for the help for options which are enabled by default.

Makes sense after looking at the other configure options. Would this be better:

+ [AS_HELP_STRING([--disable-man], + [do not install man pages (default is to install)])],,

And should I remove "# Enable manpages" comment? only --disable-wallet and --debug has a comment everything else doesn't.

Sounds good to me

luke-jr · 2016-08-27T02:27:35Z

Why include generated files (the manpages in this case) in the git repo, rather than just building them during make? (configure can disable man by default if help2man isn't found)

laanwj · 2016-08-27T06:30:58Z

Why include generated files (the manpages in this case) in the git repo, rather than just building them during make? (configure can disable man by default if help2man isn't found)

Because this (now manual) step requires actually executing the built executables to get their help output. I disagree with making that a default step in the build process. It will also not work with cross-compilation, and besides that it's an ugly thing that build systems simply should not do.

It would also introduce an extra (build-time) dependency on help2man, which we don't want.

There's a similar situation for some other generated files which are 'expensive' to produce, such as the built-in seeds list, the translation files, etc. This should be part of the release process but not automatic in the build.

laanwj · 2016-08-27T06:34:52Z

utACK, will test.

maflcko · 2016-08-27T09:19:45Z

Agree with @laanwj that it is helpful to differentiate between generation of the man pages and installation. Keep in mind that this allows to fiddle with the output, in case help2man is not perfect.

jonasschnelli · 2016-08-29T11:41:14Z

Concept ACK

laanwj · 2016-08-31T13:57:57Z

Nits:

can we avoid the commit id being included in the generated manpages? This will generate diff noise every time they're regenerated for no good reason.
Bitcoin Core RPC client version v0.13.0.0-ga402396
doc/release-process.md should contain instructions to generate these pages (after bumping the version!)
bitcoin-tx has no man page.

Apart from that, tested ACK.

theuni · 2016-08-31T15:21:48Z

Concept ACK.

Agreed with the points above. Though, if we're pre-generating the pages and keeping them in-repo, we need to be careful about #ifdefs in help output.

For example: https://github.com/bitcoin/bitcoin/blob/master/src/init.cpp#L317

Also, I'd much rather use a makefile target for generating, similar to the way the other generated files are produced. That helps to keep everything in sync since the vars are shared around.

laanwj · 2016-09-01T12:03:41Z

Though, if we're pre-generating the pages and keeping them in-repo, we need to be careful about #ifdefs in help output.

I just don't like the alternative. If this could be parsed from the C source without executing, I'd be fine with doing generation during build process.
In any case that can be done in the future, this is strictly an improvement to how things currently are.

…now also runs binaries from build dir by default, added variables for more control

nomnombtc · 2016-09-01T16:20:09Z

can we avoid the commit id being included in the generated manpages? This will generate diff noise every time they're regenerated for no good reason. Bitcoin Core RPC client version v0.13.0.0-ga402396

Yes I have updated the script somewhat to strip the commit id from the help2man output. It now also has some variables like BITCOIND BITCOINCLI and so on, as luke-jr suggested above somewhere and it now runs the binaries from the build dir, not from $PATH anymore.

doc/release-process.md should contain instructions to generate these pages (after bumping the version!)

Okay. Should I just write that it needs to be regenerated prior to release, like this?

[...]
Before every minor and major release:

Update bips.md to account for changes since the last release.
Update version in sources (see below)
Write release notes (see below)
Regenerate manpages with script in contrib/devtools
[...]

bitcoin-tx has no man page.

Oops. Thanks for noticing this, somehow I forgot about bitcoin-tx. It is included now :)

I also noticed another annoyance:
When build with --with-gui=no it still installs the bitcoin-qt manpage...
If we want to prevent this, the Makefile.am in doc/man needs a check for this :(

nomnombtc · 2016-09-02T18:56:06Z

here is something which is probably better.
It uses a Makefile target instead of a shellscript to run help2man and a few other small improvements.

master...nomnombtc:man_automake4

Changes compared to this here (8608):

Shellscript replaced by Makefile target "update-man" - many thanks to @theuni

DISTCHECK_CONFIGURE_FLAGS has been removed from Makefile.am, it seems not needed.

AC_ARG_ENABLE and AM_CONDITIONAL in configure.ac was modified to match the look of other options.

The Makefile in doc/man now only installs bitcoin-qt.1 if ENABLE_QT is set.

Added notes about updating man pages to release-process.md

Please tell me if you guys like this one better :) ~~If this is ok then only the text for release-process.md is missing. I have something here but it is not ready yet, the formatting is weird of the whole section.~~

laanwj · 2016-09-13T08:25:50Z

Thanks for sticking with this, ACK d19583f

…erated manpages d19583f improved gen-manpages.sh, includes bitcoin-tx and strips commit tag, now also runs binaries from build dir by default, added variables for more control (nomnombtc) 09546ca regenerated all manpages with commit tag stripped, also add bitcoin-tx (nomnombtc) ae6e754 change help string --enable-man to --disable-man (nomnombtc) a32c102 add conditional for --enable-man, default is yes (nomnombtc) dc84b6f add doc/man to subdir if configure flag --enable-man is set (nomnombtc) 00dba72 add doc/man/Makefile.am to include manpages (nomnombtc) eb5643b add autogenerated manpages by help2man (nomnombtc) 6edf2fd add gen-manpages.sh description to README.md (nomnombtc) d2cd9c0 add script to generate manpages with help2man (nomnombtc)

Improve autogenerated manpages Cherry-picked from bitcoin/bitcoin#8608. Closes #2086.

…autogenerated manpages d19583f improved gen-manpages.sh, includes bitcoin-tx and strips commit tag, now also runs binaries from build dir by default, added variables for more control (nomnombtc) 09546ca regenerated all manpages with commit tag stripped, also add bitcoin-tx (nomnombtc) ae6e754 change help string --enable-man to --disable-man (nomnombtc) a32c102 add conditional for --enable-man, default is yes (nomnombtc) dc84b6f add doc/man to subdir if configure flag --enable-man is set (nomnombtc) 00dba72 add doc/man/Makefile.am to include manpages (nomnombtc) eb5643b add autogenerated manpages by help2man (nomnombtc) 6edf2fd add gen-manpages.sh description to README.md (nomnombtc) d2cd9c0 add script to generate manpages with help2man (nomnombtc)

nomnombtc added 6 commits August 27, 2016 00:59

add script to generate manpages with help2man

d2cd9c0

add gen-manpages.sh description to README.md

6edf2fd

add autogenerated manpages by help2man

eb5643b

add doc/man/Makefile.am to include manpages

00dba72

add doc/man to subdir if configure flag --enable-man is set

dc84b6f

add conditional for --enable-man, default is yes

a32c102

luke-jr reviewed Aug 27, 2016
View reviewed changes

laanwj assigned theuni Aug 27, 2016

change help string --enable-man to --disable-man

ae6e754

jonasschnelli added the Build system label Aug 29, 2016

nomnombtc added 2 commits September 1, 2016 16:36

regenerated all manpages with commit tag stripped, also add bitcoin-tx

09546ca

improved gen-manpages.sh, includes bitcoin-tx and strips commit tag, …

d19583f

…now also runs binaries from build dir by default, added variables for more control

laanwj merged commit d19583f into bitcoin:master Sep 13, 2016

laanwj mentioned this pull request Sep 13, 2016

Install man pages + possibly install bitcoind into sbin #7626

Closed

TheBlueMatt mentioned this pull request Sep 13, 2016

Duplicate man pages #8711

Closed

str4d mentioned this pull request Feb 23, 2017

Help2man step creates incorrect titles as part of release process zcash/zcash#2086

Closed

str4d mentioned this pull request Feb 23, 2017

Improve autogenerated manpages zcash/zcash#2124

Merged

zkbot added a commit to zcash/zcash that referenced this pull request Mar 2, 2017

Auto merge of #2124 - str4d:2086-help2man, r=str4d

b75b2de

Improve autogenerated manpages Cherry-picked from bitcoin/bitcoin#8608. Closes #2086.

laanwj mentioned this pull request Jul 14, 2017

have proper manpages for bitcoin*(1) #10805

Closed

nomnombtc deleted the man_automake2 branch July 22, 2017 06:12

maflcko mentioned this pull request Nov 18, 2018

doc: Indicate -rpcauth option password hashing alg #14741

Merged

bitcoin locked as resolved and limited conversation to collaborators Sep 8, 2021

Conversation

nomnombtc commented Aug 27, 2016

Uh oh!

luke-jr Aug 27, 2016

Choose a reason for hiding this comment

Uh oh!

nomnombtc Aug 27, 2016

Choose a reason for hiding this comment

Uh oh!

luke-jr Aug 28, 2016

Choose a reason for hiding this comment

Uh oh!

luke-jr commented Aug 27, 2016

Uh oh!

laanwj commented Aug 27, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

laanwj commented Aug 27, 2016

Uh oh!

maflcko commented Aug 27, 2016

Uh oh!

jonasschnelli commented Aug 29, 2016

Uh oh!

laanwj commented Aug 31, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theuni commented Aug 31, 2016

Uh oh!

laanwj commented Sep 1, 2016

Uh oh!

nomnombtc commented Sep 1, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nomnombtc commented Sep 2, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

laanwj commented Sep 13, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

laanwj commented Aug 27, 2016 •

edited

Loading

laanwj commented Aug 31, 2016 •

edited

Loading

nomnombtc commented Sep 1, 2016 •

edited

Loading

nomnombtc commented Sep 2, 2016 •

edited

Loading