3.1 Starting the GNU Make debugger

Note: it is important to use a debugger-enabled GNU Make. You will get usage help output if a patched GNU Make is not used.

As mentioned above, one can enter the GNU Make debugger via Emacs (and perhaps later DDD). However you don’t have to use either of these. And these still need a way on their own to get things started.

The enter the GNU Make debugger from a command line, use the ‘--debugger’. The short form ‘-X’ option is short for ‘--debugger’ or ‘--debugger=preaction’

make --debugger other-make-arguments...
make -X

This runs GNU Remake as it would normally do; that is Makefiles are read and dependencies are checked. However it is in a “stepping” mode and will go into the debugger read loop when before encounter in “interesting” target. An “interesting” target is one that has commands associated with it to rebuild the target.

A sub-option to the --debugger (or -X) option specifies under what conditions to enter the debugger; it is specified by putting an equals sign (‘=’) and then the sub-option; for example:

make --debugger=preread other-make-arguments...

Here is a full list of debugger options and sub-options...

--debugger [preread | preaction | full | error | fatal]

-X

The “preread” sub-option enters the debugger after command-line options are parsed but before any Makefiles have been read. It also puts GNU Remake in step-tracing mode and sets the debugger to enter if it encounters an error.

The “preaction” sub-option enters the debugger after command-line options are parsed and after Makefiles have been read, but before any action is performed. It also puts GNU Remake in step-tracing mode and sets the debugger to enter if it encounters an error.

The “error” sub-option enters the debugger when it encounters an error. Depending on other conditions, GNU Remake can ignore errors and continue processing. So the overall effect could be like the --keep-going flag.

The “fatal” sub-option enters the debugger when it encounters a fatal error. A fatal error generally cause GNU Remake to abort execution.

The “full” sub-option is just a convenience for giving the “enter,” “error,” and “fatal” options described above. execution.

If no sub-option is provided, “full” is assumed.

--no-extended-errors

This option causes GNU Remake to not print a target stack trace if it encounters an error.

--trace [=suboption]

-x

Causes target names which have commands associated with them to get printed before they are considered. If a target has multiple commands each one is printed before they are run whether or not the command has the GNU Remake @ specifier which would otherwise cause them not to echo.

This option also allows for sub-options, read, normal, and full. The default is normal; read adds tracing as Makefiles are read.

tracing is independent of the --debugger option and can be used in conjunction with it. Inside the debugger one can have the same effect by issuing the debugger set trace on command.

--post-mortem

This option causes GNU Remake to go into the debugger after encountering an error.

3.1.1 Explicit call to the GNU Make debugger

Another way to get into the debugger is to make a specific all inside your Makefile using the debugger built-in function.

foo: bar

debug:
     $(debugger "debug target break")

bar:
     $(debugger "first bar command")
     @echo hi

baz: debug
     @echo hello again

$ remake -f /tmp/foo.Makefile
debugger() function called with parameter "first bar command"
break
:o (/tmp/foo.Makefile:3)
bar
remake<0> where
=>#0  bar at /tmp/foo.Makefile:6
  #1  foo at /tmp/foo.Makefile:1
  remake<0> quit
  remake: That's all, folks...

$ remake -f /tmp/foo.Makefile baz
debugger() function called with parameter "debug target break"
 break
:o (/src/external-vcs/github/rocky/remake/tmp/debugger.Makefile:3)
debug
remake<0> where
=>#0  debug at /tmp/foo.Makefile:3
  #1  baz at /tmp/foo.Makefile:10
remake<0>