Automatically generate blender.1 man page during build process #40418

New Issue

Lawrence D'Oliveiro · 2014-05-29T07:39:11+02:00

2014-05-29 07:39:11 +02:00

The blender.1 manpage is automatically generated by the script blender.1.py by postprocessing the output from the --help and --version commands from the Blender executable. Having such automatically-generated output in the source tree means that any changes to the relevant help text require a separate manual step to update this file.

This patch gets rid of the blender.1 file from the source tree, and adds CMake commands to automatically generate it at build time. This saves the separate manual steps for keeping it up to date.

autogen-manpage.patch

The `blender.1` manpage is automatically generated by the script `blender.1.py` by postprocessing the output from the `--help` and `--version` commands from the Blender executable. Having such automatically-generated output in the source tree means that any changes to the relevant help text require a separate manual step to update this file. This patch gets rid of the `blender.1` file from the source tree, and adds CMake commands to automatically generate it at build time. This saves the separate manual steps for keeping it up to date. [autogen-manpage.patch](https://archive.blender.org/developer/F91797/autogen-manpage.patch)

Lawrence D'Oliveiro commented

2014-05-29 07:39:11 +02:00

Changed status to: 'Open'

Campbell Barton was assigned by Lawrence D'Oliveiro

2014-05-29 07:39:11 +02:00

Lawrence D'Oliveiro commented

2014-05-29 07:39:11 +02:00

Added subscriber: @ldo

Campbell Barton commented

2014-05-29 08:33:45 +02:00

In general I think this is OK, but things to consider.

Currently we don't depend on having Python binary available for building blender. (but seems OK, worst case is man page fails to generate, blender is still usable)
Currently also there is no requirement that the resulting binary be able to execute on the system it builds on. (for cross compiling this won't work).

Also looks like autogen-manpage.patch is reversed?

In general I think this is OK, but things to consider. - Currently we don't depend on having Python binary available for building blender. (but seems OK, worst case is man page fails to generate, blender is still usable) - Currently also there is no requirement that the resulting binary be able to execute on the system it builds on. (for cross compiling this won't work). Also looks like `autogen-manpage.patch` is reversed?

Lawrence D'Oliveiro commented

2014-05-29 08:55:24 +02:00

Oops, yes, patch looks reversed.

Python binary needed: surely any reasonable system would have that. :)

Thinking about cross-compiling: good point. Perhaps the answer is to move that help text into a separate file, and have it included from there into the Blender code and man page at build time.

Oops, yes, patch looks reversed. Python binary needed: surely any reasonable system would have that. :) Thinking about cross-compiling: good point. Perhaps the answer is to move that help text into a separate file, and have it included from there into the Blender code and man page at build time.

Lawrence D'Oliveiro commented

2014-05-29 08:57:59 +02:00

Just thought i should point this out, in the current source tree, blender.1.py is not marked as executable. My Git patch marks it as executable (note the “old mode” and “new mode” lines); don’t know if that would automatically happen if you were to apply the patch.

Lawrence D'Oliveiro commented

2014-05-29 09:00:37 +02:00

Moving the help text to a separate file would make it easier to generate the man page directly from CMake without needing Python, similar to the way my makesdna patch #37228 generates dna_list.c.

Moving the help text to a separate file would make it easier to generate the man page directly from CMake without needing Python, similar to the way my makesdna patch #37228 generates `dna_list.c`.

Campbell Barton commented

2014-05-29 09:28:39 +02:00

@ldo, the issue with having a separate file is args are documented in creator.c via calls to BLI_argsAdd.

Having Python available seems reasonable ... but! - OSX for example doesn't have python3 in the $PATH, windows also.
For Linux now, having some Python3 in the $PATH is reasonable to expect, but when Blender first moved to Python3 this definitely wasn't the case.

Another way to resolve this could be to move the responsibility of making the man page to the packagers.

So for example, dep, rpm, pacman... etc... would have to run the script as apart of installing the package.

@ldo, the issue with having a separate file is args are documented in `creator.c` via calls to `BLI_argsAdd`. Having Python available seems reasonable ... but! - OSX for example doesn't have python3 in the $PATH, windows also. For Linux now, having some Python3 in the $PATH is reasonable to expect, but when Blender first moved to Python3 this definitely wasn't the case. Another way to resolve this could be to move the responsibility of making the man page to the packagers. So for example, dep, rpm, pacman... etc... would have to run the script as apart of installing the package.

Lawrence D'Oliveiro commented

2014-05-29 09:46:56 +02:00

Yes, the way the options docs are generated is an issue. The script currently runs with Python2, not Python3.

By the way, the SCons build scripts don’t even install the man page, as far as I can make out. So perhaps its absence in certain cases is not such a calamity. :)

Yes, the way the options docs are generated is an issue. The script currently runs with Python2, not Python3. By the way, the SCons build scripts don’t even install the man page, as far as I can make out. So perhaps its absence in certain cases is not such a calamity. :)

Lawrence D'Oliveiro commented

2014-05-29 09:50:57 +02:00

Re your point about Python3: was the script meant to be invoked as “python3 blender.1.py ...” rather than “blender.1.py ...”? Seems to run OK with Python2. :)

Campbell Barton commented

2014-05-29 11:11:37 +02:00

@ldo, right, this is mostly for linux packages which expect a man page. (and most/all currently use cmake).

doc/manpage/blender.1.py - runs with python2.6+ & 3.
In this case its no problem to support both, but in general we may want to depend on an exact python version for some scripts.

Just stuff to keep in mind, in this case its not really a problem.

@ldo, right, this is mostly for linux packages which expect a man page. (and most/all currently use cmake). `doc/manpage/blender.1.py ` - runs with python2.6+ & 3. In this case its no problem to support both, but in general we may want to depend on an exact python version for some scripts. Just stuff to keep in mind, in this case its not really a problem.

Lawrence D'Oliveiro commented

2014-05-29 11:59:19 +02:00

I don’t think Linux packaging uses cross-platform builds. I believe Debian doesn’t support this.

Lawrence D'Oliveiro commented

2014-05-29 23:32:46 +02:00

Also it seems to me Blender cannot be cross-compiled anyway, since the makesdna and makesrna executables need to run as part of the build process. I don’t see anything to build them with different platform flags from the Blender executable itself.

Lawrence D'Oliveiro commented

2014-05-30 00:17:49 +02:00

Here’s a resubmitted patch, the right way round this time. :)

autogen-manpage.patch

Here’s a resubmitted patch, the right way round this time. :) [autogen-manpage.patch](https://archive.blender.org/developer/F91907/autogen-manpage.patch)

Campbell Barton commented

2014-05-30 03:42:01 +02:00

Mostly LGTM, noticed some issues.

Best keep license at the top, add comments as python style doc docstring.
rather keep man_format as is, function allows for easier extending if needed.
no need to flush() before closing, closing implies flush.
The version text includes a " at the end.

Mostly LGTM, noticed some issues. - Best keep license at the top, add comments as python style __doc__ docstring. - rather keep `man_format` as is, function allows for easier extending if needed. - no need to `flush()` before closing, closing implies flush. - The version text includes a `"` at the end.

Campbell Barton commented

2014-05-30 03:42:52 +02:00

regarding cross compiling, we had this working for linux, windows at one point, but needed to run makesdna through wine. But this isnt supported anymore.

Lawrence D'Oliveiro commented

2014-05-31 11:25:20 +02:00

OK, changes made as requested. But I can’t see anywhere that a leftover quotation mark appears.

autogen-manpage-20140531.patch

OK, changes made as requested. But I can’t see anywhere that a leftover quotation mark appears. [autogen-manpage-20140531.patch](https://archive.blender.org/developer/F92092/autogen-manpage-20140531.patch)

Campbell Barton commented

2014-05-31 12:07:13 +02:00

Attached a cleaned up patch: autogen-manpage-20140531.diff

The extra " I'm getting because I build with color management disabled.

So I get the message

    Blender Color management: using fallback mode for management

Attached a cleaned up patch: [autogen-manpage-20140531.diff](https://archive.blender.org/developer/F92094/autogen-manpage-20140531.diff) The extra `"` I'm getting because I build with color management disabled. So I get the message ``` Blender Color management: using fallback mode for management ```

Campbell Barton commented

2014-06-13 17:22:08 +02:00

Changed status from 'Open' to: 'Resolved'

Campbell Barton closed this issue

2014-06-13 17:22:08 +02:00

Campbell Barton commented

2014-06-13 17:22:08 +02:00

Committed cb7915fc60 thanks for working on this issue (was silly to manually regenerate).

Committed cb7915fc60 thanks for working on this issue (was silly to manually regenerate).

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Automatically generate blender.1 man page during build process #40418