Summary

Adds new verbose pseudo-target to ./GNUMakefile to propagate VERBOSE to cmake and generated build Makefile. This is intended purely as a developer convenience and troubleshooting aid.

Background:

When a build fails, especially when it doesn't fail immediately, it is often very helpful to execute the failing build command by itself on the command line so the problem can be identified, fixed and verified quickly, possibly multiple times, to ensure most effective use of developers time correcting this issue.

By default, traditional Makefiles echo all build commands to STDERR before executing them, to make this troubleshooting easier. Unfortunately, with large systems like Blender, this would litter the terminal with hundreds of pages of output, of very little value, when everything is building correctly. To limit confusion, and reassure developers that the build is progressing as expected, Blender has opted (via cmake) to hide this flood of long cryptic commands, and replace it with progress percentages and file names. This can make how to reproduce a failing build command on the command line non-obvious. Cmake includes a VERBOSE mode, to expose the build commands for easier troubleshooting of failed builds.

Description of the problem that is addressed in the patch:

Because GNU make is so much more ubiquitous and familiar to many developers, compared to cmake, Blender also includes a "wrapper Makefile", for "users who like to configure & build blender with a single command".

GNUMakefile:6: # This is for users who like to configure & build blender with a single command.

This wrapper Makefile does not currently respect the VERBOSE option used by the rest of the build system.

Description of the proposed solution, and a motivation as to why this is the best solution:

This patch adds support for VERBOSE mode to the wrapper Makefile, and causes it to invoke Cmake, and the nested make invocations to run in VERBOSE mode.

This is intended as part of a larger solution:

1. The build process should make it obvious what directory each build command is running from, so it is easy for a developer to execute it from the command line. (This may simply require not hiding the "now entering"/"now leaving" banners in VERBOSE mode, when executing nested makes.)
2. The invocations of cmake within the nested build process should be echoed to STDERR before being executed within generated Makefile. (As these are generated by cmake, this requires additional research, and may be out of scope.)
3. Currently the Makefile dependency tree is not being correctly generated, included or utilized; causing incomplete or over-long non-clean builds. (I will issue a Task for this specific issue: make test does not always update the test executables, before running tests.)
4. This Patch: the wrapper Makefile should echo commands before running them in VERBOSE mode.
5. Also This Patch: the wrapper Makefile should propigate VERBOSE mode to nested make (and nested cmake) build steps.

As for why this is "the best" solution to this issue:

It provides visibility to developers of what build commands are actually being executed.

List of alternative solutions, and a motivation as to why these are undesirable:

• We can leave the status quo
  • I know I had search google and cmake forums to learn how to enable VERBOSE mode, and I still remained confused about how persistent the verbosity is.
• We can get rid of the wrapper Makefile, to eliminate it as a source of confusion, and move these "recipes" to the documentation
  • I think this would simply cause developers to get lost in more RTFM confusion.
• We can leave the wrapper Makefile unsupported
  • This is just the worst of the two previous options.
• We let each developer eradicate the leading @s in GNUMakefile when necessary
  • This seems like a lot of duplicated effort.
• Other options I missed?

Limitations of the proposed solution:

As mentioned above, it is only addresses 2 of 5 parts of the solution.

It doesn't address the python tooling, which executes external commands; but so. far these tools appear to be detecting and respecting the VERBOSE environment variable.

It also doesn't collate command echoing with command errors and output when run in parallel execution mode. (That would make it easier to tell which command was generating the errors.)

Mock-up of the proposed user interface and a description of how users are going to interact with the new feature:

To start a build in VERBOSE mode, simply execute any of these:

% make verbose

% VERBOSE=1 make

% export VERBOSE=1
% make