\input texinfo      @c -*-texinfo-*-
@c Copyright 2004, 2005, 2006, 2011, 2012, 2017, 2020
@c Rocky Bernstein for the Free Software Foundation
@c
@c TODO:
@c   - add examples for commands
@c   - clean up/improve sample session
@c   - help text is inaccurate and formatted too much to right.
@c

@c Sets version and release names and dates. Frees us from changing
@c this file when a new release comes along.

@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@c of @set vars.  However, you can override filename with makeinfo -o.
@setfilename remake.info
@c

@c
@c Name of debugger program.  Used also for prompt string.
@set REMAKE @sc{gnu} Remake
@set MAKE @sc{gnu} Make

@set DBG the @value{MAKE} debugger
@set dBG The @value{REMAKE} debugger
@set DDD @acronym{DDD}

@settitle @value{MAKE} Debugger, Remake
@setchapternewpage odd
@c @setcontentsaftertitlepage

@c %**end of header

@include version-remake.texi

@c A simple macro for optional variables.
@macro ovar{varname}
@r{[}@var{\varname\}@r{]}
@end macro

@macro DDD {}
@acronym{DDD}
@end macro

@macro MAKE {}
@value{REMAKE}
@end macro

@macro DBG {}
@value{DBG}
@end macro

@iftex
@c @smallbook
@c @cropmarks
@end iftex

@finalout

@c readline appendices use @vindex, @findex and @ftable,
@c annotate.texi and gdbmi use @findex.
@c @syncodeindex vr cp
@c @syncodeindex fn cp

@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER.

@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.
@dircategory Programming & development tools.
@direntry
* remake: (@value{DBG}).                     The @MAKE extensions and debugger.
@end direntry

@ifinfo
This file documents the @sc{gnu} MAKE extensions and debugger, Remake


This is the @value{EDITION} Edition, @value{UPDATED-MONTH},
of @cite{MAKE extenstions and Debugging with REMAKE: the @sc{gnu} Make Debugger}

Copyright (C) 2004, 2005, 2011, 2012, 2020 Rocky Bernstein for the Free Software Foundation.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU
Manual,'' and with the Back-Cover Texts as in (a) below.

(a) The Free Software Foundation's Back-Cover Text is: ``You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development.''
@end ifinfo

@titlepage
@title @sc{gnu} MAKE extensions and debugger
@sp 1
@subtitle @value{EDITION} Edition, for MAKE
@subtitle @value{UPDATED-MONTH}
@author Rocky Bernstein
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 2004, 2005, 2006, 2012 Rocky Bernstein for the Free
Software Foundation.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.

(a) The Free Software Foundation's Back-Cover Text is: ``You have
freedom to copy and modify this GNU Manual, like GNU software.  Copies
published by the Free Software Foundation raise funds for GNU
development.''
@end titlepage
@page

@ifnottex
@node Top, Summary, (dir), (dir)

@top Using @value{DBG}, Remake

This file describes @value{DBG}, Remake

This is the @value{EDITION} Edition, @value{UPDATED-MONTH}

Copyright (C) 2004, 2005, 2006, 2011, 2012, 2020 Rocky Bernstein

@menu
* Summary::                     Overview of Debugger with a sample session

* Features::                    Extensions to @value{MAKE}
* Invocation::                  Getting in and out and GNU Make command options
* Debugger Command Reference::  @value{DBG} command reference

* Front Ends::                  Using @value{DBG} from a front-end user interface

* Make Debugger Bugs::          Reporting bugs
* History and Acknowledgments:: History and Acknowledgments

Indexes (nodes containing large menus)
* Command Index::             An item for each command name.
* General Index::             An item for each concept.
@end menu

@end ifnottex

@contents

@node Summary
@chapter Summary of the GNU Make Debugger

The purpose of a debugger such as @value{DBG} is to allow you to see what is
going on ``inside'' @value{DBG} when it processes a Makefile.

@value{dBG} can do four main kinds of things (plus other things in support of
these) to help you catch bugs in the act:

@itemize @bullet
@item
Have @value{REMAKE} stop at specified places such as targets.

@item
Examine what has happened, when @value{REMAKE} has stopped or encounters
an error.

@item
Change the internal state of things inside @value{REMAKE}, so you can
experiment with correcting the effects of one bug and go on to
discover another.
@end itemize

Although you can use the @value{DBG} to debug Makefiles, it can also
be used just as a front-end for learning more about Makefiles and
writing them with @value{REMAKE}.

A degenerate and less-interactive form of debugging is @emph{tracing}
in which one passively watches some of the steps that go on in
processing a Makefile.

@menu
* Sample Sessions::             Sample GNU Make Debugger sessions
@end menu

@node Sample Sessions
@section Sample @value{REMAKE} Debugger Sessions

You can use this manual at your leisure to read all about @value{DBG}.
However, a handful of commands are enough to get started using the
debugger.  This chapter illustrates those commands.

@iftex
In this sample session, we emphasize user input like this: @b{input},
to make it easier to pick out from the surrounding output.
@end iftex

@menu
* Tracing Not::              How NOT to debug your Makefile
* Tracing::                  Using --trace or -x on a simple example
* Tracing a Real Makefile::  A Larger Real-World Makefile Trace.
* Simple Debugging::         Getting into the Debugger (--debugging)
* Debugging Make Variables:: Seeing Make variable expansions at various levels
* Debugging Shell Commands:: Debugging the shell commands that Make runs
@end menu

@node Tracing Not
@subsection How @emph{not} to debug your Makefile

Before we get into debugging proper, we'll discuss tracing and a
pitfall the author once made in his first attempt to debug a large and
mysterious @code{Makefile}. Chances you may have happened to you too.

A simplified form of debugging is @emph{tracing}. Often this may be
good enough to understand what might have gone wrong. In fact, in the
Unix shell world (@code{tcsh}, @code{csh}, @code{bash}, @code{sh})
prior to my debugger for bash (@url{http://bashdb.sourceforge.net})
tracing along with print statements was about all that was available
to debug a program.

@value{MAKE} has had for a long time a ``debug'' flag (@code{--debug}
or @code{-d}) which prints ``lots of debugging information.'' For the
unwary one might think you just add this simple option and that's
going to do what you want. Wrong!@footnote{From the standpoint of a
nice user interface, this options should get replaced with
@code{--trace}. At present, this change is probably a little to young to
to make such a bold change, tempting as it is to do.}

Alas, the @code{--debug} option gives way too much information to be
helpful. Furthermore, debug-flag information @emph{omits} information
that would be helpful.

To elaborate upon this, here is a simple small @code{Makefile} with an
invalid shell command in it:

@smallexample
1: # Makefile to show off tracing
2: .PHONY: all
3: all: foo
4:
5: foo:
6: 	@@case $(MAKE) in \
7: 	*/remake|remake) echo "Enlightened!";; \
8: 	*/make|make) echo "This is what most folks use.";; \
9: 	esac
10: 	@@bogus-command
@end smallexample

But now let's see what happens when we run ``debug'' from an unpatched
@value{MAKE}:

@smallexample
$ @b{/usr/bin/make -d -f test1.mk}
Copyright (C) 2006  Free Software Foundation, 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.

This program built for i486-pc-linux-gnu
Reading makefiles...
Reading makefile `test1.mk'...
Updating makefiles....
 Considering target file `test1.mk'.
  Looking for an implicit rule for `test1.mk'.
  Trying pattern rule with stem `test1.mk'.
  Trying implicit prerequisite `test1.mk.o'.
  Trying pattern rule with stem `test1.mk'.
  Trying implicit prerequisite `test1.mk.c'.

... over 350 lines later ...

 No need to remake target `test1.mk'.
Updating goal targets....
Considering target file `all'.
 File `all' does not exist.
  Considering target file `foo'.
   File `foo' does not exist.
   Finished prerequisites of target file `foo'.
  Must remake target `foo'.
Putting child 0x08acced8 (foo) PID 307 on the chain.
Live child 0x08acced8 (foo) PID 307
This is what most folks use.
Got a SIGCHLD; 1 unreaped children.
Putting child 0x095b1310 (foo) PID 13440 on the chain.
Live child 0x095b1310 (foo) PID 13440
Reaping winning child 0x095b1310 PID 13440
make: bogus-command: Command not found
Got a SIGCHLD; 1 unreaped children.
Live child 0x095b1310 (foo) PID 13441
Reaping losing child 0x095b1310 PID 13441
make: *** [foo] Error 127
Removing child 0x095b1310 PID 13441 from chain.
@end smallexample

The output would have been about twice as long were it not for the
fact that we declared @code{all} a ``phony'' target!

Clearly this information referring to rule stems, implicit
prerequisites, @code{SIGCHLD}, pids, and unreaped children is intended
for someone who is well versed with the internals of @value{MAKE}.

But even for someone such as myself who has become more knowledgeable
(through writing this debugger), it @emph{still} isn't all that
helpful. In the midst of the above jumble, the program reports:
@smallexample
make: bogus-command: command not found
@end smallexample
Say what? Okay, but where in the source @code{Makefile} did that come from?
Since we added the debug output we see ``@code{foo}'' listed
beforehand after skipping hundreds of lines, but in a normal make,
there would have been no mention of ``@code{foo}.'' In our simple example
tracking down the location is easy.  But when you have a @code{Makefile}
which is hundreds of lines long as any Makefile is when it is
generated from @code{automake}, it would be nice to list the line in
the Makefile and full filename as well as the target name.

@node Tracing
@subsection Sample @value{REMAKE} Trace Sessions

Okay so now that we know what @emph{not} to do, lets delve into things
may be more helpful.

There are variants of the @code{--debug} command option that provide
shorter and more-interesting information. One is called ``basic''
tracing. Another is the @code{--just-print} option.

Again here's the sample Makefile:

@smallexample
1: # Makefile to show off tracing
2: .PHONY: all
3: all: foo
4:
5: foo:
6: 	@@case $(MAKE) in \
7: 	*/remake|remake) echo "Enlightended!";; \
8: 	*/make|make) echo "This is what most folks use.";; \
9: 	esac
10: 	@@bogus-command
@end smallexample

In an unpatched @value{MAKE} version 3.81 (and earlier) @value{MAKE},
@code{--just-print} gives this:

@smallexample
$ @b{make --just-print -f test1.mk}
case make in \
*/remake|remake) echo "Enlightended!";; \
*/make|make) echo "This is what most folks use.";; \
esac
This is what most folks use.
bogus-command
@end smallexample

Well, not much different from the original Makefile, except that
information about where this gets run from is curiously missing. If
there had been several targets that had commands, from the output it
would not be possible to determine which command was associated with
which target.

Here's what we give instead:

@smallexample
$ @b{remake --just-print -f test.mk1}
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
case make in \
*/remake|remake) echo "Enlightended!";; \
*/make|make) echo "This is what most folks use.";; \
esac
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This is what most folks use.
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
bogus-command
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
@end smallexample

What's different is that we separate the commands that are about to be
run, such as @code{case make in...} from the output @code{"This is
what...}" This may be a little bit subtle, but from the above output it
is more apparent that there are @emph{two} separate commands@footnote{or
``jobs'' in the terminology used when we used @code{--debug}} that are
getting run from target @code{foo}: one at line 7 and another at line
10.

Now let's try @code{--debug=basic} alluded to at the beginning of this
section. In an unpatched @value{MAKE} version 3.82, we get this:

@smallexample
$ @b{make --debug=basic -f test1.mk}
GNU Make 3.82
Built for i686-pc-linux-gnu
Copyright (C) 2010  Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://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.
Reading makefiles...
Updating goal targets....
 File `all' does not exist.
   File `foo' does not exist.
  Must remake target `foo'.
Invoking recipe from /tmp/test1.mk:6 to update target `foo'.
This is what most folks use.
make: bogus-command: Command not found
make: *** [foo] Error 127
@end smallexample

The @code{--debug=basic} command-line switch also works in
@value{REMAKE} as well if that's all you want..@footnote{Actually the
output is a little bit different here since we give a more context
about the position when a fatal error is encountered.}

But now let's try the new kind of trace we provide in this patched
@value{REMAKE}.  We use the new option @code{--trace}.
The short-form option format @code{-x} is the same as @code{--trace} and @code{--trace=normal}

@smallexample
@group
/usr/local/bin/remake -x -f test1.mk
...
Reading makefiles...
Updating goal targets....
 /tmp/test1.mk:3	File `all' does not exist.
   /tmp/test1.mk:5	File `foo' does not exist.
  /tmp/test1.mk:5	Must remake target `foo'.
Invoking recipe from test1.mk:6 to update target `foo'.
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
case /tmp/../make in \
*/remake|remake) echo "Enlightened!";; \
*/make|make) echo "This is what most folks use.";; \
esac
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This is what most folks use.
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
bogus-command
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
remake: bogus-command: Command not found
test1.mk:5: *** [foo] Error 127

#0  foo at /tmp/test1.mk:5
#1  all at /tmp/test1.mk:3
Command-line arguments:
	"/usr/local/bin/remake -x -f test1.mk"
@end group
@end smallexample

In some ways this is just a combination of the
enhanced@code{--just-print} option combined with the location-enhanced
@code{--debug=basic} information.

What is completely new is the shell tracing information and information
given when we hit an error.  After the error and we report the return
code (127), the stack of targets is listed. We were working on target
@code{foo} on line 5 of file @code{/tmp/test1.mk} which was rebuilt
because we were making target @code{all} on line 3 of file
@code{/tmp/test1.mk}.

In other words, when we hit the error, the above trace gives what
targets were in the process of getting considered at the error, and how
the program was run.

One last subtlety that you might not have noticed is that we echoed
the command @code{bogus-command} even though the original makefile had
this set to be silent, in particular by preceding that command with an
@@.

When tracing as with @code{--just-print}, we override any silent
execution making execution more verbose. This information is usually
helpful in tracing.

Although I think that the above may be improved, it is far better than
what has previously been available in GNU make. In my own experience,
just adding that @code{--trace} or @code{-x} option is enough to let me
find problems. No need to bring out the heavy artillery in a
full-fledged debugger.

Still, it is nice to have additional power available, so read
on...

@node Tracing a Real Makefile
@subsection A Larger Real-World Makefile Trace

@value{MAKE} and @value{REMAKE} work like many other interpreters. First
Makefiles are read in and parsed and then they are ``executed'' which in
@value{MAKE} means that dependency checks are done and actions are
performed based on those checks.  However there is quite a bit work that
may be done just in portion which reads in the Makefiles and performs
variable expansion. Most of the time this information is will not be of
much use. But if you should be interested in this phase, use the flag
@code{--trace=read}.

@smallexample
@group
$ @b{remake --trace=read}
GNU Make 3.82+dbg-0.5
Built for i686-pc-linux-gnu
Copyright (C) 2010  Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://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.
Reading makefile `Makefile'...
Reading makefile `.deps/alloca.Po' (search path) (no ~ expansion)...
Reading makefile `.deps/getloadavg.Po' (search path) (no ~ expansion)...
Reading makefile `.deps/ar.Po' (search path) (no ~ expansion)...
Reading makefile `.deps/arscan.Po' (search path) (no ~ expansion)...
Reading makefile `.deps/break.Po' (search path) (no ~ expansion)...
Reading makefile `.deps/buildargv.Po' (search path) (no ~ expansion)...
Reading makefile `.deps/cmd.Po' (search path) (no ~ expansion)...
...
@end group
@end smallexample

Now let's do a simple trace on a real example --- the Makefile the @code{doc}
directory for the GNU Make + Debugger. Here it is in its entirety:
@smallexample
@group
$ @b{remake --trace}
GNU Make 3.82+dbg-0.5
Built for i686-pc-linux-gnu
Copyright (C) 2010  Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://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.
Reading makefiles...
Updating goal targets....
 /tmp/remake/doc/Makefile:245	File `all' does not exist.
   /tmp/remake/doc/Makefile:545	File `all-am' does not exist.
  /tmp/remake/doc/Makefile:545	Must remake target `all-am'.
  /tmp/remake/doc/Makefile:545	Successfully remade target file `all-am'.
/tmp/remake/doc/Makefile:245	Must remake target `all'.
/tmp/remake/doc/Makefile:245	Successfully remade target file `all'.
remake: Nothing to be done for `all'.
$
@end group
@end smallexample

As before, after @code{Updating goal targets...} we show the position in
the Makefile @code{(/tmp/remake/doc/Makefile:245)} of where target
@code{all} appears and we see that this depends on target @code{all-am}
which must also be remade.

Above, no shell commands needed to get run. So let us get just a little
more complex and make the HTML pages which shows some running some
shell code:

@smallexample
@group
$ @b{remake --trace remake.html}
GNU Make 3.82+dbg-0.5
Built for i686-pc-linux-gnu
Copyright (C) 2010  Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://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.
Reading makefiles...
Updating goal targets....
 Prerequisite `remake.texi' is newer than target `remake.html'.
/tmp/remake/doc/Makefile:369	Must remake target `remake.html'.
Invoking recipe from Makefile:370 to update target `remake.html'.
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
rm -rf remake.htp
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
if /bin/sh /tmp/remake/config/missing --run makeinfo --html   -I . \
 -o remake.htp `test -f 'remake.texi' || echo './'`remake.texi; \
then \
  rm -rf remake.html; \
  if test ! -d remake.htp && test -d remake; then \
    mv remake remake.html; else mv remake.htp remake.html; fi; \
else \
  if test ! -d remake.htp && test -d remake; then \
    rm -rf remake; else rm -Rf remake.htp remake.html; fi; \
  exit 1; \
fi
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
/tmp/remake/doc/Makefile:369	Successfully remade target file `remake.html'.
$
@end group
@end smallexample

To make @code{remake.html} we need to make @code{remake.texi}, but
that file exists already. Then we remove file @code{remake.htp}. That is shown
in the lines:

@smallexample
@group
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
rm -rf remake.htp
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
@end group
@end smallexample

There is no output from running this command which would appear next.
Instead, we see:
@smallexample
@group
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
@end group
@end smallexample
which means we are about to runn a second shell command for this target:

@smallexample
@group
if /bin/sh /tmp/remake/config/missing --run makeinfo --html   -I . \
 -o remake.htp `test -f 'remake.texi' || echo './'`remake.texi; \
then \
  rm -rf remake.html; \
  if test ! -d remake.htp && test -d remake; then \
    mv remake remake.html; else mv remake.htp remake.html; fi; \
else \
  if test ! -d remake.htp && test -d remake; then \
    rm -rf remake; else rm -Rf remake.htp remake.html; fi; \
  exit 1; \
fi
@end group
@end smallexample

The backslashes in the above are there because this multi-line
@code{if} statement is passed off to the shell as one command.

@node Simple Debugging
@subsection Simple @value{REMAKE} Debug Sessions

Now let's go into the debugger. To do this, use the @code{--debugger}
or @code{-X} option. Again we'll use the Makefile from the source code
of this distribution.

@smallexample
$  @b{remake --debugger}
...
Reading makefiles...
Updating makefiles....
Updating goal targets....

-> (/tmp/remake/Makefile:471)
Makefile: Makefile.in config.status
remake<0>
@end smallexample

Before the prompt @code{remake<0>}, we show the position in the file
@code{(/tmp/remake/Makefile:471)} of the target @code{Makefile}. We also
show the dependencies of the target @code{Makefile}, namely:
@code{Makefile.in} and @code{config.status}. The ``0'' in the prompt
@code{remake<0>} is the command history number it increments as we enter
commands.

Before the position are two dashes @code{->}. This indicates that we
have not done prerequisite checking for this target yet.  Later we will
come across other two-character icons like @code{--}, @code{++}, and
@code{<-}, to name few. But to get full information about why were are
stopped, you can use the command @code{info program}:

@smallexample
remake<0> @b{info program}
Starting directory `/tmp/remake'
Program invocation:
	/tmp/remake/./remake  --debugger
Recursion level: 0
Program stopped at a breakpoint before prerequisite checking.
remake<1>
@end smallexample

Notice that the prompt now lists ``1'' since we entered a command.

We can use the @code{step} command, (see @ref{Step}), to progress a little
in the interpretation or execution of the makefile:
@smallexample
@group
remake<2> @b{step}
-> (/tmp/Makefile:457)
Makefile.in: Makefile.am config/gettext.m4 ... aclocal.m4
-> (/tmp/Makefile:488)
remake<3> @b{step}
-> (/tmp/Makefile:486)
aclocal.m4: config/dospaths.m4 config/gettext.m4 ...
remake<4> @b{step}
@end group
@end smallexample

One subtlety in the output above. In the @code{Makefile} at line 486 you
will see this:

@smallexample
@group
$(ACLOCAL_M4):  $(am__aclocal_m4_deps)
@end group
@end smallexample

In the location and dependent targets reported by @value{REMAKE} above,
variables have been expanded.

Let's recap where we are right now.  Target @code{Makefile} needs to
build dependency @code{Makefile.in} and that depends on target
@code{aclocal.m4}. We have now stepped into and stopped at that target.

You can see this dependency nesting using the @code{where} command:

@smallexample
@group
remake<2> @b{where}
=>#0  aclocal.m4 at /tmp/remake/Makefile:486
  #1  Makefile.in at /tmp/remake/Makefile:457
  #2  Makefile at /tmp/remake/Makefile:471
@end group
@end smallexample

If stepping is going too slowly, one can use @code{next} or
set a breakpoint at a target. Let's restart the program
and then go directly to target @code{config.h.in} which is where
we will see something else of interest.

@smallexample
@group
remake<3> @b{restart}
Changing directory to /tmp/remake and restarting...
GNU Make 3.82+dbg-0.5
Built for i686-pc-linux-gnu
...
Reading makefiles...
Updating makefiles....

-> (/tmp/remake/Makefile:471)
Makefile: Makefile.in config.status
remake<0> @b{continue config.h.in}
Breakpoint 1 on target config.h.in: file Makefile, line 499.
Updating goal targets....
 /tmp/remake/Makefile:450	File `all' does not exist.

-> (/tmp/remake/Makefile:499)
config.h.in: config/dospaths.m4 ...
remake<1> @b{step}
-> (/tmp/remake/Makefile:499)
remake<2> @b{step}
   Prerequisite `stamp-h1' is newer than target `config.h'.
  /tmp/Makefile:490	Must remake target `config.h'.
Invoking recipe from Makefile:491 to update target `config.h'.
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
if test ! -f config.h; then \
  rm -f stamp-h1; \
  /tmp/remake/./remake  stamp-h1; \
else :; fi
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

++ (/tmp/remake/Makefile:490)
config.h
remake<2>
@end group
@end smallexample

Before the location we now have two pluses,
@code{++}. This means that the code shown above in between
@code{##>>>>}... and @code{##<<<<}... is about to be run.

If you want the full details about a target, @code{config.h.in} at
this point in time, one can use the @code{target} (@ref{Target}) command:
@smallexample
@group
remake<4> @b{target}

config.h: stamp-h1
#  Implicit rule search has not been done.
#  Implicit/static pattern stem: `'
#  Last modified 2011-03-21 18:10:08
#  File has not been updated.
# automatic
# @@ := config.h
# automatic
# % :=
# automatic
# * :=
# automatic
# + := stamp-h1
# automatic
# | :=
# automatic
# < := stamp-h1
# automatic
# ^ := stamp-h1
# automatic
# ? := stamp-h1
#  commands to execute (from `Makefile', line 489):
	@@if test ! -f $@@; then \
	rm -f stamp-h1; \
	$(MAKE) $(AM_MAKEFLAGS) stamp-h1; \
	else :; fi
@end group
@end smallexample

I could have gotten the same output explicitly giving a target name
such as @code{target config.h}, or used the @value{MAKE}
automatic variable name @code{@@}, e.g. @code{target @@}.

And we don't have to be stopped on a target to get information about a target:

@smallexample
remake<4> @b{target Makefile}
Makefile: Makefile.in config.status
#  Precious file (prerequisite of .PRECIOUS).
#  Implicit rule search has not been done.
#  Implicit/static pattern stem: `'
#  Last modified 2011-03-25 17:57:09
#  File has been updated.
#  Successfully updated.
# automatic
# @ := Makefile
# automatic
# % :=
# automatic
# * :=
# automatic
# + := Makefile.in config.status
# automatic
# | :=
# automatic
# < := Makefile.in
# automatic
# ^ := Makefile.in config.status
# automatic
# ? :=
#  commands to execute (from `Makefile', line 470):
	@@case '$?' in \
	*config.status*) \
	echo ' $(SHELL) ./config.status'; \
	$(SHELL) ./config.status;; \
	*) \
	echo ' cd $(top_builddir) && $(SHELL) ./config.status $@@ $(am__depfiles_maybe)'; \
	cd $(top_builddir) && $(SHELL) ./config.status $@@ $(am__depfiles_maybe);; \
	esac;
@end smallexample

However information may change depending on where @code{remake} is. In
particular note that for target @code{config.h} we see ``File has not been
updated'', while for target @code{Makefile}, we get ``File has been updated''.

This means that we are finished with target @code{Makefile}, but not
target @code{config.h}.

@node Debugging Make Variables
@subsection Debugging Make Variables

We've seen we can get information about @value{REMAKE}'s targets.  We
can also get information about @value{REMAKE}'s variables. That is done
with the @code{print} command. (See @ref{Print}.)

@smallexample
  remake<4> @b{print MAKE}
  (origin default) MAKE = $(MAKE_COMMAND)
@end smallexample

The @code{(origin default)} means this is a built-in
definition. There is another print which does full expansion
of the variables. So if I run @code{x} (@code{expand}) instead I get:

@smallexample
  remake<5> @b{expand MAKE}
  (origin default) MAKE := /tmp/remake/src/./make
@end smallexample

Note that in printing expanded values we use @code{:=} while non-expanded
values we use @code{=} This output matches the semantics of these
assignment operators.

In fact, @code{expand} doesn't need a variable name, it will work
with a string. So I could type @code{x This is $(MAKE)} or
@code{x $(bin_PROGRAMS) $(noinst_PROGRAMS)}. For the latter, I
get:

@smallexample
  remake<6> @b{x $(bin_PROGRAMS) $(noinst_PROGRAMS)}
  make remake
@end smallexample

No location identification is given here since what I put in
isn't a variable.

But I can also @emph{change} values too using either @code{set} or
@code{setq}. (See @ref{set variable} and @ref{setq}.) Let's see the difference
between the two.

@smallexample
  remake<7> @b{set MAKE $(MAKE_COMMAND)}
  Variable MAKE now has value '/tmp/remake/src/./make'
  remake<8> @b{setq MAKE $(MAKE_COMMAND)}
  Variable MAKE now has value '$(MAKE_COMMAND)'
@end smallexample

So with @code{set}, the value in the expression @code{$(MAKE_COMMAND)}
is expanded before the variable definition is assigned. With @code{setq}
the internal variables are kept unexpanded. Which you use or want is up
to you.

Note the irregular syntax of @code{set} and @code{setq}. Don't put an
equal sign (@code{=}) between the variable and the expression. That
is, @code{set MAKE = $(MAKE_COMMAND)} gives:

@smallexample
  Variable MAKE now has value '= /tmp/remake/src/./make'
@end smallexample

which is probably not what you want.  One may optionally put in the the
word "variable" when using @code{set}, one must not supply it with
@code{setq}.  Down the line, someone (maybe @emph{you!}) will probably
put in a command parser.

@node Debugging Shell Commands
@subsection Debugging Shell Commands

Now consider the following sample Makefile:
@smallexample
@group
$ @b{cat -n test2.mk}
1 PACKAGE=make
2
3 all: $(PACKAGE).txt
4
5 $(PACKAGE).txt: ../doc/remake.texi
6 	makeinfo --no-headers $< > $@
@end group
@end smallexample

@smallexample
@group
$ @b{remake -X -f test2.mk}
...
Reading makefiles...
updating makefiles....
Updating goal targets....
 /tmp/remake/src/test2.mk:3	File `all' does not exist.

-> (/tmp/test2.mk:5)
make.txt: ../doc/remake.texi
@end group
@end smallexample

We could use the @code{target} command to show information about
the current target, but that returns lots if information. So let us instead
narrow the information to just the automatic variables that get set. The
following commands do this are all mean the same thing: @code{target make.txt
variables}, @code{target @ variables}, and @code{info locals}.

@smallexample
@group
remake<1> @b{info locals}
@@ := all
% :=
* :=
+ := make.txt
| :=
< := all
^ := make.txt
? :=
@end group
@end smallexample

There is a @code{target} option to list just the shell commands of the
target:

@smallexample
@group
remake<2> @b{target make.txt commands}

make.txt:
#  commands to execute (from `test2.mk', line 6):
	makeinfo --no-headers $< > $@@

@end group
@end smallexample

We can see a full expansion of the command that is about to be run:
@smallexample
@group

remake<5> @b{target @@ expand}

#  commands to execute (from `test2.mk', line 6):
	makeinfo --no-headers $< > $@

#  commands to execute (from `test2.mk', line 6):
	-makeinfo --no-headers ../doc/remake.texi > make.txt

@end group
@end smallexample

Now if we want to write out commands as a shell script which
we might want to execute, we can use the @code{write} (@ref{Write})
command:
@smallexample
@group
(/tmp/remake/src/test2.mk:6): make.txt
remake<6> @b{write}
File "/tmp/make.txt.sh" written.
@end group
@end smallexample

We can issue a shell command @code{cat -n /tmp/make.txt.sh} to see what
was written.

@smallexample
@group
remake<7> @b{shell cat -n /tmp/make.txt.sh}
     1	#!/bin/sh
     2  # cd /tmp/remake/src/
     3	#/tmp/remake/src/test2.mk:5
     4	makeinfo --no-headers ../doc/remake.texi > make.txt
     5
@end group
@end smallexample

If you issue step commands, the debugger runs the each command and
stops. In this way, you can inspect the result of running that
particular shell command and decide to continue or not.

@smallexample
@group
remake<8> @b{step}

  Must remake target `make.txt'.
Invoking recipe from test2.mk:6 to update target `make.txt'.
##>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
makeinfo --no-headers ../doc/remake.texi > make.txt
##<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

++ (/tmp/test2.mk:5)
@end group
@end smallexample

Notice that we've shown the expansion automatically. One subtle
difference in the above output, is that we only show the @emph{single}
shell command that is about to be run when there are several
commands. In our example though, there is only one command; so there is
no a difference.

The @code{++} icon means that we are about to run that code.

@smallexample
@group
make.txt
remake<9> @b{step}
  Successfully remade target file `make.txt'.

<- (/tmp/test2.mk:5)
make.txt
remake<10>
@end group
@end smallexample

We ran the code, and are still at target @code{make.txt}. The @code{<-}
icon means that have finished with this target and are about to return.

If you are at a target and want to continue to the end of the target you
can use the command @code{finish} which is the same as @code{finish
0}. See @ref{Finish}.

@node Features
@chapter Extensions to @value{MAKE}

Although the bulk of this document is devoted to @value{DBG}, there
are a number of handy extensions to @value{MAKE} that we list here.

@menu
* Profiling and Visualization:: Getting data on where build time is spent
* Comments::     Listing and Documenting Makefile Targets
* Searching::    Searching for a Makefile in Parent Directories
* Improved-Tracing::      Improved Execution Tracing
@end menu

@node Profiling and Visualization
@section Profiling build execution timing and dependencies
@cindex @code{--profile}
@cindex profiling

@smallexample
  $ remake --profile[=callgrind|json] # target...
@end smallexample

The @code{--profile} option enables dependency and timing output
from build execution. The data can be used to determine where your
build system spends it's time. By default, the @code{--profile}
option outputs profiling data in the callgrind format
@footnote{@url{http://valgrind.org/docs/manual/cl-format.html}} which
can be used with
@code{kcachegrind}@footnote{http://kcachegrind.sourceforge.net/html/Home.html}
or other
tools@footnote{@url{https://github.com/icefox/callgrind_tools},
@url{https://github.com/zenkj/callgrind2dot}} that work with this
format. Each recursive call to @value{REMAKE} generates its own
output in the starting directory named @code{callgrind.out.<pid>}
where @code{pid} is the PID of the @value{REMAKE} process.

By default, profiling data is written in the same directory where
@value{REMAKE} is executed. This includes recursive calls. The
@code{--profile-directory} argument can be used to specify a
single directory for all profiling data. This is taken to
be relative to the initial invocation of @value{REMAKE} unless
the path begins with ~ or /.

@subsection JSON-formatted profiling data
@cindex json

The @code{--profile} option also accepts a @code{json} flag that
will output profiling data in json-formatted files. With the following
formatting:

@example
 @{
     "version":"1.0.0",
     "pid":1234,
     "parent":@{
         "pid":1230,
         "target":"target-name"
     @},
     "jobs": 8,
     "server": true,
     "creator":"remake"
     "argv":[
         "arg0",
         "arg1",
         "arg2"
     ],
     "directory":"path/to/working/dir",
     "status":"Normal program termination",
     "start":1235.6789,
     "end":1240.0123,
     "resolution":1000,
     "entry":[
         "all",
         "other"
     ],
     "targets":[
         @{
             "name":"all",
             "file":"path/to/file/with/target",
             "line":100,
             "start":123.123,
             "deps":null,
             "recipe":124.0,
             "end":124.124,
             "depends":[
                 "dependent",
                 "target0",
                 "target1",
                 "target2"
             ]
         @}
     ]
 @}
@end example

@subsubsection Top-level field definitions
@table @code
@item version
The @code{version} field specifies the version of build.json file.
@item pid
The PID of the @value{REMAKE} execution that created this file
@item parent.pid
If present, this PID of the @value{REMAKE} process that recursively called the
current @value{REMAKE} process
@item parent.target
If present, the name of the target the parent @value{REMAKE} process that
recusively called the current @value{REMAKE} process.
@item jobs
If present, either @code{unlimited} when parallel jobs were not restricted. Or
an integer value reprenting the maximum number of available jobs.
@item server
True if connected to a jobserver
@item creator
A string representing the version of @value{REMAKE} that generated this file
@item argv
An array of strings that represent the command used to start @value{REMAKE}
@item directory
Path to the starting directory, generally the path current directory or the value
passed to @value{REMAKE} with @code{-C path/to/subdir}
@item status
String representing what caused @value{REMAKE} to exit
@item start
Timestamp in seconds representing when @value{REMAKE} started
@item end
Timestamp in seconds representing when @value{REMAKE} ended
@item resolution
Number of nanoseconds specifying the minimum resolution of timestamps
in the output
@item entry
An array of targets that were requested to be built.
@item targets
An array of target specifications
@end table

@subsubsection Target field definitions
@table @code
@item name
Name of the target
@item file
Path to the file that contains the target definition relative to the top-level
@code{directory} field
@item line
Line number of the @code{name} target in the @code{file} field
@item start
Timestamp when the target was first considered by @value{REMAKE}
@item deps
Timestamp when @value{REMAKE} marked the target as waiting on dependencies.
Or @code{null} if it was not marked as waiting.
@item recipe
Timestamp when the recipe for the target began execution. Or @code{null} if
the recipe did not need to execute.
@item end
Timestamp when the target was considered complete
@item depends
Array of target names that this target depended on.
@end table

@node Comments
@section Listing and Documenting Makefile Targets

Have you ever wanted @code{rake tasks} for @value{MAKE}?  That is, you
have some strange Makefile and you want to see the interesting
targets, that you can run ``make @emph{target-name}'' on?

There are two new options added to `remake` to assist this:

@itemize @bullet
@item @code{--tasks}  gives a list of ``interesting'' targets
@item @code{--targets} gives a list of @emph{all} targets
@end itemize

Before each target in the Makefile, you can give add a one-line comment
describing what the target does, starting the comment with @code{#:}.

If you do this, when either of these options is shown it will also be shown
with next to the target name.

Here is an example. Consider this Makefile:

@smallexample

#: This is the main target
all:
	echo all here

#: test things
check:
	echo check here

#: Build distribution
dist:
	echo dist here
@end smallexample

Running @code{remake --tasks} gives:

@smallexample
all         # This is the main target
check       # test things
dist        # Build distribution
@end smallexample

@node Searching
@section Searching for a Makefile in Parent Directories

@cindex @code{-c}
@cindex @code{--search-parent}
When the @code{-c} flag is given (or @code{--search-parent}), if a
Makefile or goal target isn't found in the current directory,
@value{REMAKE} will search in the parent directory for a Makefile. On
finding a parent the closest parent directory with a Makefile,
@value{REMAKE} will set its current working directory to the directory
where the Makefile was found.

In this respect the short option @code{-c}, is like @code{-C} except no
directory need to be specified.

@node Improved-Tracing
@section Improved Execution Tracing

@cindex @code{-x}
When the @code{-x} flag is given (or @code{--trace=normal}), any
commands that are about to be run are shown as seen in the `Makefile`
along with @code{set -x} tracing when run in a POSIX shell. Also, we
override or rather ignore, any non-echo prefix @code{@@} directive listed at
the beginning of target commands.

If different granularity of tracing is desired the @code{--trace} option
has other settings. See the relevant parts of this manual for more information.

And, if you the most flexibility in tracing there is a built-in debugger.

@node Invocation
@chapter Getting in and out and new @value{REMAKE} Command Options

This chapter discusses how to start @value{DBG}, and how to get out of it.

There are a couple ways you could get into the debugger

@itemize @bullet
@item
invoke from the outset, using option @code{-X} or @code{--debugger}.
@item
enter when there is a fatal error using option @code{--debugger=error},
@code{debugger=fatal}, or @code{--post-mortem}
@item
through an explicit call inside the debugger using built-in function @code{debugger}
@end itemize

Once inside the debugger, and type @kbd{quit} or @kbd{C-d} inside the
debugger to exit.

You don't have to use the command-line interface. At present there is
a front-end available via GNU Emacs which can be entered via the Emacs
command @code{M-x remake} after loading @code{dbgr}. See
@ref{Emacs,,Using @value{DBG} from @sc{gnu} Emacs}.

@menu
* Starting the GNU Make debugger::    How to enter the @value{DBG}
* Quitting the GNU Make debugger::    How to leave the @value{DBG}
@end menu

@node Starting the GNU Make debugger
@section Starting the GNU Make debugger

@emph{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 @value{DBG} 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 @value{DBG} from a command line, use the @samp{--debugger}.
The short form @samp{-X} option is short for @samp{--debugger} or @samp{--debugger=preaction}

@example
make --debugger @var{other-make-arguments...}
make -X
@end example

This runs @value{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 @code{--debugger} (or @code{-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:

@example
make --debugger=preread @var{other-make-arguments...}
@end example

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

@table @code
@item --debugger @ovar{preread | preaction | full | error | fatal}
@itemx -X
@cindex @code{-X}
@cindex @code{--debugger}
The ``preread'' sub-option enters the debugger after command-line
options are parsed but before any Makefiles have been read. It also
puts @value{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 @value{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, @value{REMAKE} can ignore errors
and continue processing. So the overall effect could be like the
@code{--keep-going} flag.

The ``fatal'' sub-option enters the debugger when it encounters a fatal
error. A fatal error generally cause @value{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.

@item --no-extended-errors
@cindex @code{--no-extended-errors}
This option causes @value{REMAKE} to @emph{not} print a target stack
trace if it encounters an error.

@item --trace @ovar{=suboption}
@itemx -x
@cindex @code{-x}
@cindex @code{--trace}
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 @value{REMAKE} @@ specifier which would otherwise cause them not to
echo.

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

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

@cindex @code{-!}
@cindex @code{--post-mortem}
@item --post-mortem
This option causes @value{REMAKE} to go into the debugger after
encountering an error.

@end table

@subsection 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 @code{debugger} built-in function.

@smallexample
foo: bar

debug:
     $(debugger "debug target break")

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

baz: debug
     @@echo hello again
@end smallexample

@smallexample
$ 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>
@end smallexample

@node Quitting the GNU Make debugger
@section Quitting the GNU Make debugger

@cindex interrupt
An interrupt (often @kbd{C-c}) does not exit from @value{DBG}, but
rather terminates the action of any @value{DBG} command that is in
progress and returns to @value{DBG} command level.  Inside a debugger
command interpreter, use @code{quit} command (@pxref{Quit, ,Quitting
the Make debugger}).

@node Debugger Command Reference
@chapter @value{REMAKE} Debugger Command Reference

You can abbreviate the long name of @value{DBG} command to the first
few letters of the command name, if that abbreviation is unambiguous;
and you can repeat the @code{next} or @code{step} commands by typing
just @key{RET}. Some commands which require a parameter, such as
@code{print} remember the argument that was given to them.

@menu
* Command Syntax::        How to give commands to the @value{DBG}
* Help::                  How to ask for help (help)
* Quit::                  Leaving the remake (quit)
* Stopping::              Stopping and continuing (break, watch, step, cont...)
* Information::           Status and Debugger settings (info, set, show)
* Stack::                 Examining the stack (where, up, down, frame)
* Data::                  Examining data (print, target, expand, info variables)
* Files::                 Specifying and examining files (load, edit)
* Interfacing to the OS:: Interfacing to the OS (cd, pwd, source)
* Controlling Make::      Controlling make (annotate, file, prompt...)
@end menu

@node Command Syntax
@section Command syntax

A @value{REMAKE} debugger command is a single line of input.  There is
no limit on how long it can be.  It starts with a command name, which
is followed by arguments whose meaning depends on the command name.
For example, the command @code{step} accepts an argument which is the
number of times to step, as in @samp{step 5}.  You can also use the
@code{step} command with no arguments.  Some commands do not allow any
arguments. In commands that have attributes, the attribute can be
abbreviated to the minimum string that makes it unique. For example
``commands''in @code{target all commands} can be shortened to
``command'' or ``com'' or just ``c''.

@cindex repeating next/step commands
@kindex RET @r{(repeat last command)}
A blank line as input to @value{DBG} (typing just @key{RET}) means to
repeat the previous next or step command.

@kindex # @r{@code{comment}}
@cindex comment
Any text from a @kbd{#} to the end of the line is a comment; it does
nothing.  This is useful mainly in command files

@node Help
@section Getting help (@samp{help})
@cindex on-line documentation

Once inside the debugger, you can always ask it for information on its
commands, using the command @code{help}.

@table @code
@kindex h @r{(@code{help})}
@item help
@itemx h
You can use @code{help} (abbreviated @code{h}) with no arguments to
display a short list of named classes of commands:
@end table

@flushleft
@smallexample
remake<0> @b{help}
  Command                  Short Name  Aliases
  ----------------------   ----------  ---------
  break [TARGET|LINENUM] [all|run|prereq|end]* (b)  L
  cd DIR                          (C)
  comment TEXT                    (#)
  continue [TARGET [all|run|prereq|end]*] (c)
  delete breakpoint numbers..     (d)
  down [AMOUNT]                   (D)
  edit                            (e)
  eval STRING                     (E)
  expand STRING                   (x)
  finish [AMOUNT]                 (F)
  frame N                         (f)
  help [COMMAND]                  (h)  ?, ??
  info [SUBCOMMAND]               (i)
  list [TARGET|LINE-NUMBER]       (l)
  next [AMOUNT]                   (n)
  print @{VARIABLE [attrs...]@}     (p)
  pwd                             (P)
  quit [exit-status]              (q)  exit, return
  run [ARGS]                      (R)  restart
  set OPTION @{on|off|toggle@}
  set variable VARIABLE VALUE     (=)
  setq VARIABLE VALUE             (")
  shell STRING                    (!)  !!
  show [SUBCOMMAND]               (S)
  source FILENAME                 (<)
  skip                            (k)
  step [AMOUNT]                   (s)
  target [TARGET-NAME] [info1 [info2...]] (t)
  up [AMOUNT]                     (u)
  where                           (T)  backtrace, bt
  write [TARGET [FILENAME]]       (w)

Readline command line editing (emacs/vi mode) is available.
For more detailed help, type h <cmd> or consult online-documentation.
@end smallexample
@end flushleft
@c the above line break eliminates huge line overfull...

@table @code
@item help @var{command}
With a command name as @code{help} argument, @value{REMAKE} displays
short information on how to use that command.

@example
remake<3> @b{help where}
  where:
	Show target stack.
@end example

In addition to @code{help}, you can use the debugger command
@code{info} to inquire about the state of your script, or the state of
@value{DBG} itself.  The listings under @code{info} in the Index
point to all the sub-commands.  @xref{Command Index}.
@end table

@c @group
@table @code
@kindex info
@kindex i @r{(@code{info})}
@item info
This command (abbreviated @code{i}) is for describing the state of
your program.  You can get a complete list of the
@code{info} sub-commands with @w{@code{help info}}.

Subcommands can be abbreviated with the minimum number of letters to
make that subcommand distinct from another. For example @code{info lo}
is the same as @code{info locals} and @code{info li} is the same as
@code{info line}.

@example
remake<0> @b{help info}
  info [thing]:
	Show the state of thing.
	If no 'thing' is specified, show everything there is to show.

	Available info subcommands are:
	 line locals makefiles targets variables warranty
@end example
@end table

@node Quit
@section Gentle termination of @value{DBG} (@samp{quit})

@table @code
@kindex quit @ovar{return-code}
@kindex q @r{(@code{quit})}
@item quit @ovar{return-code}
@itemx q  @ovar{return-code}

To exit @value{REMAKE}, use the @code{quit} command (abbreviated
@code{q}), or type an end-of-file character (usually @kbd{C-d}).  If
you do not supply @var{return-code}, @value{REMAKE} will terminate
normally or with exit code 0. Otherwise it use the value of the
@var{return-code} as the exit code. Usually a 0 exit is a normal exit.

Often when running @value{MAKE} or @value{REMAKE}, a recursive call is
made or made in another directory. The @code{quit} only terminates
only the last one: the one that the debugger is in. @value{dBG}
arranges for the debug flags to get passed down in recursive
calls. Consequently when you quit one of the inner make calls, you may
find yourself still in the debugger but up a call level.

@end table

@node Stopping
@section Stopping and Resuming Execution

One important use of a debugger is to stop execution before it gets
into trouble, so you can investigate and find out what is going
on. However should @value{REMAKE} accidentally continue to termination,
@value{DBG} has arranged for it not to leave the debugger without your
explicit instruction. That way, you can restart the program using the
same command arguments.

Inside @value{DBG}, your script may stop for any of several reasons,
such as a signal, a breakpoint, or reaching a new line after a
debugger command such as @code{step}.  You may then expand and
change variables, set new breakpoints or remove old ones, and then
continue execution.

@menu
* Breakpoints::          Breakpoints, watchpoints (break, clear)
* Resuming Execution::   Resuming execution (continue, step, next, skip)
* Signals::              Signals
@end menu

@node Breakpoints
@subsection Breakpoints

@cindex breakpoints
A @dfn{breakpoint} arranges for @value{REMAKE} to stop when it reaches
a Makefile target.

You can set breakpoints with the @code{break} command and its variants
(@pxref{Set Breaks, ,Setting breakpoints}), to specify the place where
your script should stop by target name.

The debugger assigns a number to each breakpoint when you create it;
these numbers are successive integers starting with 1. In many of the
commands for controlling various features of breakpoints you use this
number.


@menu
* Set Breaks::                      Setting breakpoints (break)
* Delete Breaks::                   Deleting breakpoints (delete, clear)
@end menu

@node Set Breaks
@subsubsection Setting breakpoints (@samp{break})

@kindex break
@kindex b @r{(@code{break})}
@cindex latest breakpoint
Breakpoints are set with the @code{break} command (abbreviated
@code{b}).  Use @code{info targets} to get a list of target names that
you can break at.

@table @code
@item break
In this form without argument, list all breakpoints.

Example:
@example
remake<0> @b{break}
remake<1> info break
Num Type           Disp Enb target     What
  1 breakpoint     keep y   in all at /tmp/Makefile:450
@end example

@item break @var{target|line-number} @ovar{all|run|prereq}
Set a breakpoint at @var{target} or at line @var{line-number} in the
current Makefile.

There are 3 place where one may want to stop at:

@itemize @bullet
@item
before prerequisite checking (prereq)

@item
after prerequisite checking but before running commands (run)

@item
after target is complete (end)
@end itemize

@end table

Example:
@example
remake<0> @b{break all}

Breakpoint 1 on target all: file Makefile, line 450.
Warning: target is in the process of being updated;
@end example

@node Delete Breaks
@subsubsection Deleting breakpoints (@samp{delete})

@cindex deleting breakpoints
It may be desirable to eliminate a breakpoint once it
has done its job and you no longer want stop there.
This is called @dfn{deleting} the breakpoint.  A breakpoint that has
been deleted no longer exists; it is forgotten.

It is not necessary to delete a breakpoint to proceed past it.  @DBG
automatically ignores breakpoints on the first instruction to be executed
when you continue execution.

@table @code

@cindex delete breakpoints
@kindex delete
@kindex d @r{(@code{delete})}
@item delete @var{breakpoint-number}...
Delete the breakpoints by breakpoint-number specified as arguments.

@end table

@node Resuming Execution
@subsection Resuming Execution

@cindex stepping
@cindex continuing
@cindex resuming execution
@dfn{Continuing} means resuming program execution until your script
completes normally.  In contrast, @dfn{stepping} means executing just
one more ``step'' of your script, where ``step'' may mean either one
line of source code.  Either when continuing or when stepping,
your script may stop even sooner, due to a breakpoint or a signal.

@menu
* Next::          running the next target (next)
* Step::          running the next target in smaller increments (step)
* Finish::        step out
* Skip::          skipping over a target (skip)
* Continue::      continuing execution (continue)
@end menu

@node Next
@subsubsection Next (@samp{next})
@table @code
@kindex next
@kindex n @r{(@code{next})}
@item next
Continue processing your Makefile until control reaches the next
interesting target, then stop and return control to @value{DBG}.  This
command is abbreviated @code{n}. If you want more fine-grained
stepping use @code{step}. See @ref{Step}. If you want to not stop at
any of targets the current target depends on, but instead run until
after this target is remade, use @code{finish}. See @ref{Finish}.

@item next @ovar{count}
Continue running as in @code{next}, but do so @var{count} times.  If a
breakpoint is reached, or a signal not related to stepping occurs before
@var{count} steps, stepping stops right away.
@end table

@node Step
@subsubsection Step (@samp{step})
@table @code
@kindex step into
@kindex s @r{(@code{step})}
@item step
Stepping is like @code{next} but it is more fine-grained. However we
still don't stop at targets for which there is no rule.  We once tried
that and stepping is too tedious for C source files as one C file may
depend on several included headers which are all extant files.

If there are multiple commands associated with a target @code{step} will
stop before each one.

If you want to be sure to stop at a particular target, use the
@code{break} command. See @ref{Breakpoints}. Also see @ref{Next} and
@ref{Finish} for other kinds of stepping.

@item step @ovar{count}
Continue running as in @code{step}, but do so @var{count} times.  If a
breakpoint is reached, or a signal not related to stepping occurs before
@var{count} steps, stepping stops right away.
@end table

@node Finish
@subsubsection Finish (@samp{finish})
@table @code
@kindex finish
@kindex F @r{(@code{finish})}
@item finish

With no arguments, @value{DBG} runs to the end of the target. Any prerequisite
checking and building that needs to occur is done and any shell commands
that occur get run.

This is analogous to ``step out'' in programming-language debuggers.

@item finish @ovar{count}
Runs a ``finish'' @emph{count} times, putting the program that many
levels up the current target stack. A count of 0 is the current target
and that's the same as giving no count.
@end table

@node Skip
@subsubsection Skip over tareget (@samp{skip})
@table @code
@kindex skip
@item skip @ovar{count}
Skip executing the remaining commands of the target you are stopped at.
This may be useful if you have an action that ``fixes'' existing code in
a Makefile.
@end table

@node Continue
@subsubsection Continue (@samp{continue})
@table @code
@item continue @ovar{@var{target @{all|run|prereq@}*}}
@kindex c @r{(@code{continue})}
Resume program execution until the next breakpoint or recursive make is
called. If a target name is given, a temporary breakpoint is set
there. Use @code{info target} to get a list of target names you can use.

A common mistake is giving a target already updated, so we will warn
about that situation. It is possible to set a breakpoint on a target
that subsequently never gets updated. In that situation the
@code{remake} will also not stop. This is another cause of constant
confusion, as you may expected (erroneously) that the program should
have decided to update the target. See also @xref{Breakpoints}.
@end table

@node Signals
@subsection Signals
@cindex signals

A signal is an asynchronous event that can happen in a program.  The
operating system defines the possible kinds of signals, and gives each
kind a name and a number.  For example, in Unix @code{SIGINT} is the
signal a program gets when you type an interrupt character (often
@kbd{C-c}); @code{SIGALRM} occurs when the alarm clock timer goes off
(which happens only if your program has requested an alarm).

@value{REMAKE} sets up some signal handlers of children it spawns.  When
we are running under the debugger when and we get a signal the
debugger read loop is entered.

@cindex fatal signals
Some signals, including @code{SIGALRM}, are a normal part of the
functioning of your program.  Others, such as @code{SIGSEGV}, indicate
errors; these signals are @dfn{fatal} (they kill your program
immediately) if the program has not specified in advance some other
way to handle the signal.  @code{SIGINT} does not indicate an error in
your program, but it is normally fatal so it can carry out the purpose
of the interrupt: to kill the program.

@node Information
@section Status and Debugger Settings (@samp{info}, @samp{show}, @samp{set})

@menu
* Info::        Showing information about the program being debugged
* Set::         Change debugger settings
* Show::        Show debugger settings
@end menu

In addition to @code{help}, you can use @value{DBG} commands @code{info}
and @code{show} to inquire about the state of your program, or the state
of @value{REMAKE} itself.  The @code{set} command allow you to change
debugger behavior and in some cases program behavior.

@node Info
@subsection Showing information about the program being debugged (@samp{info})
@c @group
This @code{info} command (abbreviated @code{i}) is for describing the state of
your program.  For example, you can list the current @code{$1}, @code{$2}
parameters with @code{info args}, or list the breakpoints you have set
with @code{info breakpoints} or @code{info watchpoints}.  You can get
a complete list of the @code{info} sub-commands with @w{@code{help
info}}.

@c @group
@table @code
@kindex info targets
@kindex i t @r{(@code{info targets})}
@item info targets @r{@ovar{verbose}}
Use @code{info targets} to get a list of all the targets explicitly
mentioned in the makefiles that are read. The location of each target is
given before the target name.

The result of running this on the sample makefile used in
@ref{Tracing Not}:

@smallexample
@group
remake<0> @b{info targets}
test1.mk:2:
	.PHONY
test1.mk:3:
	all
test1.mk:5:
	foo
remake<1>
@end group
@end smallexample
@item info program
@kindex info program
@kindex i p @r{(@code{info files})}
Use @code{info program} to give information about the state of the
stopping point.

@smallexample
@group
remake<0> @b{info program}
Starting directory `/tmp'
Program invocation:
	/usr/bin/remake -f /tmp/test1.mk
Recursion level: 0
Line 5 of "/tmp/test1.mk"
Program stopped at a breakpoint before rule-prequisite checking.
@end group
@end smallexample

@item info break
@kindex info break
@kindex i b @r{(@code{info files})}
Use @code{info break} to give a list of breakpoint currently in effect.

@smallexample
@group
remake<0> @b{info break}
Num Type           Disp Enb target     What
  1 breakpoint     keep y   in all at /tmp/test1.mk:3
  2 breakpoint     keep y   in foo at /tmp/test1.mk:5
remake<1>
@end group
@end smallexample

@item info line
@kindex info line
Shows the line number and file of for the place that you are currently
stopped.

@smallexample
@group
$ @b{remake -X -f test1.mk}
...
remake<0> @b{info line}
Line 5 of "/tmp/test1.mk"
remake<1>
@end group
@end smallexample

@item info lines
@kindex info lines
Shows for each Makefile the line numbers that targets appear.

@smallexample
@group
$ @b{remake -X -f test1.mk}
...
remake<0> @b{info lines}
test1.mk
       2: .PHONY
       3: all
       5: foo
remake<1>
@end group
@end smallexample

@item info locals
@kindex info locals
Displays a the values of the automatic variables.

@item info makefiles
@kindex info makefiles
Displays the list of Makefiles read in the order that they were read
in. The last Makefile listed is the one you started with (e.g. Makefile).

@item info warranty
@kindex info warranty
Displays GNU Warranty

@end table

@c @end group

@node Set
@subsection Change debugger settings (@samp{set})

@table @code
@kindex set
@item set
In addition to showing @value{REMAKE} settings you can change them or
change @value{REMAKE} variables with @code{set}.  For example, you can
change setting @value{REMAKE} has whether to ignore errors.
@end table

@node Show
@subsection Show information about the debugger (@samp{show})

@table @code
@kindex show
@item show
In contrast to @code{info}, @code{show} is for describing the state of
@value{REMAKE} itself.
You can change most of the things you can @code{show}, by using the
related command @code{set};

The distinction between @code{info} and @code{show} however is a bit
fuzzy and is kept here to try to follow the GDB interface.

@kindex info set
To display all the settable parameters and their current
values, you can use @code{show} with no arguments; you may also use
@code{info set}.  Both commands produce the same display.
@c FIXME: "info set" violates the rule that "info" is for state of
@c FIXME...program.  Ck w/ GNU: "info set" to be called something else,
@c FIXME...or change desc of rule---eg "state of prog and debugging session"?
@end table
@c @end group

Here are force miscellaneous @code{show} subcommands, all of which are
exceptional in lacking corresponding @code{set} commands:

@table @code
@kindex show command
@cindex history
@item show command
Shows the list of commands previously entered

@kindex show version
@cindex version number
@item show version
Show what version of @value{REMAKE} is running.  You should include this
information in @value{DBG} bug-reports.  If multiple versions of
@value{REMAKE} are in use at your site, you may need to determine which
version you are running; as @value{DBG} evolves, new commands are
introduced, and old ones may wither away. The version number is the
same as the one announced when you start @value{REMAKE}.

@kindex show warranty
@item show warranty
Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty,
if your version of @value{DBG} comes with one.

@end table

@node Stack
@section Examining the Stack (@samp{where}, @samp{frame}, @samp{up}, @samp{down})

When you enter the debugger, one thing you'll probably want to know is
where it stopped and some idea of how it got there.

@cindex target stack
Each time your Makefile performs dependency checking (sometimes as
implicit rules or pattern-substitution rules), information about the
target that caused the new target to be considered action is saved on
a stack.  This target call stack then is this a history of the
dependency checks that got you to the point that you are currently
stopped at.

@cindex selected frame
One of the stack frames is @dfn{selected} by @value{DBG} and many
@value{DBG} commands refer implicitly to the selected frame.  In
particular, whenever you ask @value{DBG} to list lines without giving
a line number or location the value is found in the selected frame.
There are special @value{DBG} commands to select whichever frame you
are interested in. @xref{Selection, ,Selecting a frame}.

When your program stops, @value{DBG} automatically selects the
currently executing frame and describes it briefly, similar to the
@code{frame} command.


@menu
* Frames::                      Stack frames
* Backtrace::                   Backtraces (where)
* Selection::                   Selecting a frame (up, down, frame)

@end menu

@node Frames
@subsection Stack frames

@cindex frame, definition
@cindex target stack frame
The target stack is divided up into contiguous pieces called
@dfn{stack frames}, or @dfn{frames} for short. The frame contains the
line number of the target which triggered the next one to be
considered, the Makefile file name that the line in that refers to a
target name. When some of this information is be missing you may see a
filename shown as ``null'' or have line number 0.

@cindex initial frame
@cindex outermost frame
@cindex innermost frame
When your script is started, the stack has only one frame, that of the
function @code{main}.  This is called the @dfn{initial} frame or the
@dfn{outermost} frame.  Each time a function is called, a new frame is
made.  Each time a function returns, the frame for that function invocation
is eliminated.  If a function is recursive, there can be many frames for
the same function.  The frame for the function in which execution is
actually occurring is called the @dfn{innermost} frame.  This is the most
recently created of all the stack frames that still exist.

@cindex frame number
@value{DBG} assigns numbers to all existing stack frames, starting with
zero for the innermost frame, one for the frame that called it,
and so on upward.  These numbers do not really exist in your script;
they are assigned by @value{DBG} to give you a way of designating stack
frames in @value{DBG} commands.

@node Backtrace
@subsection Backtraces (@samp{where})

@cindex backtraces
@cindex tracebacks
@cindex stack traces
A backtrace is essentially the same as the call stack: a summary of
how your script got where it is.  It shows one line per frame, for
many frames, starting with the place that you are stopped at (frame
zero), followed by its caller (frame one), and on up the stack.

If @value{REMAKE} is in the reading phase the backtrace shows the
nesting of include files. If @value{REMAKE} is in the interpretation
phase the backtrace shows the nesting of targets.

@table @code
@kindex backtrace
@item where
@itemx backtrace
@itemx bt
@itemx T
If we are reading Makefiles, print a backtrace of the included
Makefile stack. If we are evaluating the Makefile to bring targets up
to date, print a backtrace of the target stack. In either case, we print
line per frame.

@item where @var{n}
@itemx backtrace @var{n}
@itemx bt @var{n}
@itemx T @var{n}
Similar, but print only the innermost @var{n} frames. A negative
number prints the outermost @var{n} frames.

@end table

@kindex where

Each line in the backtrace shows the frame number and the function
name, the source file name and line number, as well as the function name.

Here is an example of a backtrace taken a program in the
regression-tests @file{parm.sh}.

@smallexample
@group
@b{./make -X}

/tmp/remake/src/Makefile:228: Makefile.in
remake<0> @b{step}

/tmp/remake/src/Makefile:263: make
remake<1> @b{where}

=>#0  make at /tmp/remake/src/Makefile:263
  #1  all-am at /tmp/remake/src/Makefile:386
  #2  all at /tmp/remake/src/Makefile:224

@end group
@end smallexample

However if we have set debugging to stop before reading makefiles are
we are in the reading phase, we show included Makefiles:

@smallexample
@group
$ @b{./make --debugger=preread}
Reading makefiles...
Reading makefile `Makefile'...

(/tmp/remake/src/Makefile:1)
remake<0> @b{step}
/tmp/remake/src/Makefile:324
	Reading makefile `.deps/alloca.Po' (search path) (no ~ expansion)...

(/tmp/remake/src/.deps/alloca.Po:1)
remake<1> @b{where}

=>#0  /tmp/remake/src/.deps/alloca.Po:1
  #1  /tmp/remake/src/Makefile:324

remake<2> @b{next}
/tmp/remake/src/Makefile:327
	Reading makefile `.deps/getloadavg.Po' (search path) (no ~ expansion)...
/tmp/remake/src/Makefile:328
	Reading makefile `.deps/ar_fns.Po' (search path) (no ~ expansion)...
/tmp/remake/src/Makefile:329

... lots of lines deleted ...

	Reading makefile `.deps/version.Po' (search path) (no ~ expansion)...
/tmp/remake/src/Makefile:360
	Reading makefile `.deps/vpath.Po' (search path) (no ~ expansion)...
Updating goal targets....
 /tmp/remake/src/Makefile:254	File `all' does not exist.

(/tmp/remake/src/Makefile:254): all
remake<3>
@end group
@end smallexample

@noindent

Note in the above @samp{step} goes on to the next read of a makefile
while the @samp{next} command can be used to skip over all of the
remaining reads.

@node Selection
@subsection Selecting a frame (@samp{up}, @samp{down}, @samp{frame})

Commands for printing targets script work on whichever
stack frame is selected at the moment.  Here are the commands for
selecting a stack frame; all of them finish by printing a brief
description of the stack frame just selected.

@table @code
@kindex up
@item up @var{n}
Move @var{n} frames up the stack.  For positive numbers @var{n}, this
advances toward the outermost frame, to higher frame numbers, to frames
that have existed longer.  @var{n} defaults to one.

@kindex down
@kindex D @r{(@code{down})}
@item down @var{n}
Move @var{n} frames down the stack.  For positive numbers @var{n}, this
advances toward the innermost frame, to lower frame numbers, to frames
that were created more recently.  @var{n} defaults to one.  You may
abbreviate @code{down} as @code{do}.
@end table

All of these commands end by printing two lines of output describing the
frame.  The first line shows the frame number, the function name, the
arguments, and the source file and line number of execution in that
frame.  The second line shows the text of that source line.

@need 100
For example:

@smallexample
@group
remake<8> @b{up}
/tmp/remake/src/Makefile:386: all-am
remake<8> @b{T}
  #0  make at /tmp/remake/src/Makefile:263
=>#1  all-am at /tmp/remake/src/Makefile:386
  #2  all at /tmp/remake/src/Makefile:224
@end group
@end smallexample

@table @code
@kindex frame
@cindex current stack frame
@item frame @var{args}
The @code{frame} command allows you to move from one stack frame to
another, and to print the stack frame you select.  @var{args} is the
the stack frame number.  Without an argument, @code{frame} prints the
current stack frame.
@end table

@node Data
@section Examining Data (@samp{print}, @samp{expand}, @samp{target}, @samp{edit}, @samp{write}, @samp{info})

@menu
* Print::                  Print variable info
* Expand::                 Print a string expanded
* Target::                 Print target Info
* Write::                  Write commands of a target
* Info Variables::         Print all variables
@end menu

@node Print
@subsection Print variable info (@samp{print})

@cindex printing data
@cindex examining data
@kindex print

One way to expand variables the @code{print}
command (abbreviated @code{p}). However a more versatile print command
is @code{x}; it can print arbitrary string expands which of course
includes variable.

@table @code
@kindex print
@kindex p @r{(@code{print})}
@item print @var{variable-name}

Use @code{print} to display @value{REMAKE}'s variables. As such,
variable names should @emph{not} be preceded with a dollar sign.

@smallexample
@group
remake<0> @b{print SHELL}
Makefile:168 (origin: makefile) SHELL = /bin/sh

/tmp/remake/Makefile:243: Makefile.in
remake<1> @b{print $MAKE}   # don't use $
Can't find variable $MAKE

/tmp/remake/Makefile:243: Makefile.in
remake<1> @b{print shell}   # note case is significant
Can't find variable shell
@end group
@end smallexample


@item print
@itemx p

If you omit @var{variable}, @value{DBG} displays the last expression again.
@end table

@node Expand
@subsection Print a string expanded (@samp{expand})

@table @code
@item x @var{string}
@kindex x @r{(@code{expand})}
@kindex expand

The @code{x} command expands the string given using @value{REMAKE}'s
internal variables. The expansion would be the same as if the string
were given as a command inside the target.

@smallexample
@group
remake<0> @b{expand MAKE}
(origin default) MAKE := /tmp/remake/src/./make


/tmp/remake/src/Makefile:264: Makefile.in

remake<1> @b{print MAKE}  # note the difference with the ``print''
(origin default) MAKE = $(MAKE_COMMAND)

remake<2> @b{expand $(MAKE)}   # Note using $( ) doesn't matter here...
/tmp/remake/src/./make          # except in output format - no origin info

/tmp/remake/src/Makefile:264: Makefile.in

remake<2> @b{p COMPILE}
Makefile:104 (origin: makefile) COMPILE := $(CC) $(DEFS) $(DEFAULT_INCLUDES)

/tmp/remake/src/Makefile:264: Makefile.in
remake<10> @b{x compile starts: $(CC) $(DEFS) $(DEFAULT_INCLUDES)}
compile starts: gcc -DLOCALEDIR=\"\" -DLIBDIR=\"/usr/local/lib\" -DINCLUDEDIR=\"/usr/local/include\" -DHAVE_CONFIG_H -I. -I..

@end group
@end smallexample
@end table

@node Target
@subsection Examining Targets (@samp{target}, @samp{list})

@value{DBG} can print information about targets.  When @value{DBG}
enters the debugger, @value{DBG} spontaneously prints the target name
under consideration and the location of this target.  Likewise, when
you select a target frame (@pxref{Selection, ,Selecting a frame}),
@value{DBG} the default target name is changed.

As with debugging any program, the value shown at a particular point in
time may change. Targets, and commands can use GNU Make uses variables
and these values can change.

@table @code
@item target
@itemx t
print information about the current target.


@item target @var{target}
@itemx t @var{target}
Print information about @var{target}. A list of attributes can be
specified after the target name. The list of attributes names are

@table @kbd
@item attributes
Show the list of ``attributes'' associated with the target. Attributes
can be:
@itemize @bullet
@item implicit rule search has been done
@item phony: has no file associated with it
@item precious:
@item a command-line target
@end itemize

@item commands
Show the list of commands that need to get run in order to bring the
target up to date.

@item depends
Show the targets that this one depends on.

@item expand
Show the list of commands that need to get run in order to bring the
target up to date with @value{REMAKE} variables expanded.

@item nonorder
Show the ``non-order'' dependencies, i.e. dependencies that are not ordered.

@item previous
Previous target name when there are multiple double-colons
@item state
Show target status:
@itemize @bullet
@item Successfully updated
@item Needs to be updated
@item Failed to be updated
@item Invalid - error of some sort
@end itemize

@item time
This shows the time that the file was last modified and if the file
has been brought up to date. If it is not up to date you will see the
message ``File is very old.'' If a target is ``phony'', i.e. doesn't
have file associated with it, the message ``File does not exist.''
will appear instead of the time. In some cases you may see
``Modification time never checked.''

@item variables
Show single-character automatic state variables (if defined):
@itemize @bullet
@item @@ - the target name
@item % - target member name, when target is an the archive member
@item * - the stem with which an implicit rule matches
@item + - like $^ but with the duplicate dependencies listed in order
@item < - the name of the first prerequisite
@item ^ - the names of all prerequisites (no duplicates)
@item ? - the names of all prerequisites newer than the target (@@)
@end itemize

Note that there are other automatic variables defined based on
these. In particular those that have a `D' or `F' suffix, e.g. $(@@D),
or $(*F). These however are not listed here but can shown in a
@code{print} command or figured out from their corresponding
single-letter variable name.

@end table

@item list
@itemx l
The ``list'' is like target but only text-oriented information is shown.
@end table

@node Write
@subsection Write commands of a target (@samp{write})

@table @code
@kindex write @ovar{@var{target} @var{filename|here}}
@item write @r{[}@var{target} @ovar{filename|here}@r{]}

Use this to write the command portion of a target with @value{REMAKE}'s
internal variables expanded.  If a filename is given that is the file
where the expanded commands are written. If the filename is ``here''
then it is not written to a file but output inside the debugger as
other debugger commands behave. And if no file name is given a
filename based on the target name is created.

@end table

@node Info Variables
@subsection Print all variables (@samp{info variables})

@table @code
@item info variables
@kindex info variables

List all POSIX-shell environment and GNU Make variables.

Each variable is shown on a single line and is preceded by a line which indicates the
type of variable it is . This list of types is:


Each variable is preceded by a line which indicates
@itemize @bullet
@item automatic: variables which have values computed afresh for each rule
@item default: a variable using its default value
@item environment: a POSIX shell environment variable
@item pattern-specific
@end itemize

At the end of the list, hash table statistics are shown.

Here is an example:

@smallexample
@group
remake<0> @b{info variables}
# 'override' directive
GNUMAKEFLAGS :=
# automatic
<D = $(patsubst %/,%,$(dir $<))
# default
.SHELLFLAGS := -c
# default
LD = ld
# environment
PATH = /usr/bin/:/sbin/
...
# variable set hash-table stats:
# Load=214/1024=21%, Rehash=0, Collisions=35/240=15%
remake<4>
@end group
@end smallexample
@end table

@node Files
@section Specifying and examining files (@samp{edit}, @samp{list}, @samp{load})

@menu
* Edit::                   Edit Makefile
* List::                   Read Makefile target
* Load::                   Read and Evaluate a Makefile
@end menu

@node Edit
@subsection Edit Makefile (@samp{edit})

To edit the Makefile at the current target location file, use the
@code{edit} command.  The editing program of your choice is invoked
with the current line set to the active line in the program.

You can customize to use any editor you want by using the
@code{EDITOR} environment variable. The only restriction is that your
editor, e.g.\ @code{ex}), recognizes the following command-line syntax:
@smallexample
ex +@var{number} @var{file}
@end smallexample

The optional numeric value +@var{number} specifies the number of the
line in the file where to start editing.  For example, to configure
@value{DBG} to use the @code{emacs} editor, you could use these commands
with a POSIX shell:
@smallexample
EDITOR=/usr/bin/emacs
export EDITOR
remake @dots{}
@end smallexample

@table @code
@kindex edit
@item edit
Edit line specification using the editor specified by the
@code{EDITOR} environment variable.
@end table

@node List
@subsection List Makefile target (@samp{edit})

@table @code
@kindex list
@item list

List target dependencies and commands for @emph{target} or @emph{line-number}.

Without a target name or line number, use the current target.
A target name of @code{-} will use the parent target on the target stack.

@smallexample
remake<0> @b{list}
/tmp/remake/tests/spec/example/simple.Makefile:2
all:
#  recipe to execute (from '/tmp/remake/tests/spec/example/simple.Makefile', line 3):
   echo all here

remake<1> @b{list -}
 ** We don't seem to have a parent target.
remake<2>
@end smallexample

@end table

@node Load
@subsection Read and Evaluate Makefile (@samp{load})

@table @code
@item load
@kindex load

**load** *Makefile*

Read in and evaluate *Makefile*.

@end table

Note that dependencies are updated after reading the file in.

Here are several possible uses of this command.

In debug sessions you can fix the source code and the run `load` to have the code reread in, to test out the fix.

Another use is to have pecific "debug"-oriented Makefiles that aren't
normally used, but when you want to trace things are avialable.
This is an aspect of aspect-oriented programming. See @url{https://en.wikipedia.org/wiki/Aspect-oriented_programming}.

@node Interfacing to the OS
@section Interfacing to the OS (@samp{cd}, @samp{pwd}, @samp{source}, @samp{shell})

@table @code
@kindex cd @var{directory}
@cindex change working directory
@item cd

Set working directory to @var{directory} for debugger and program
being debugged.  The change does not take effect for the program being
debugged until the next time it is started.

@kindex pwd
@cindex print working directory
@item pwd

Prints the working directory as the program sees things.

@kindex source @var{filename}
@item source @var{filename}

Reads each line of @emph{filename} and runs that as a debugger command.

@end table

@table @code
@kindex shell
@kindex ! @r{(@code{shell})}
@cindex shell escape
@item shell @var{command string}
@itemx !

If you need to execute occasional shell commands during your
debugging session, there is no need to leave or suspend @value{DBG}; you can
just use the @code{shell} command or its alias @code{!}.

Invoke a shell to execute @var{command string}.

@end table

@node Controlling Make
@section Controlling @DBG (@samp{set})

You can alter the way @value{REMAKE}
interacts with you in various ways given below.

@menu
* set basename::      Annotation Level (set basename)
* set ignore-errors:: Ignoring errors
* set trace::         Set tracing
* set variable::      Set a variable to an expanded string
* setq::              Set a variable to an unexpanded string
@end menu

@node set basename
@subsection Basename (@samp{set basename})

@table @code
@kindex set basename
@item set basename @var{on/off/toggle}
The basename level controls how much information @value{DBG} prints
when it has to show a file name. When this is on we just show the base
filename part an not the path info. When @value{DBG} is run as a
subprocess of @sc{gnu} Emacs of @value{DDD}, it is important
to show full pathnames.
@end table

@node set ignore-errors
@subsection Ignoring errors (@samp{set ignore-errors})

@table @code
@kindex set ignore-errors
@item set ignore-errors @var{on/off/toggle}

Use this to change whether you ignore errors. Turning it on is
as though you started @value{REMAKE} with the @code{--ignore-errors} option.
@end table

@node set trace
@subsection Tracing (@samp{set basename})

@table @code
@kindex set trace
@item set trace @var{on/off/toggle}

Use this to change whether you want tracing or not. Turning it on is
as though you started @value{REMAKE} with the @code{--trace} option.
@end table

@node set variable
@subsection Setting a variable to an expanded string (@samp{set variable})

@table @code
@item set varible @var{variable} @var{string}
@kindex set variable @var{variable} @var{string}

Sets @var{variable} to the value @var{string}, but @var{string} is
expanded first as it would be when you use @code{expand}.
@end table

One nice use of set variable in debugging is to set the value of
@code{SHELL} to include tracing in that. Here's an example:

@smallexample
remake<0> @b{set variable SHELL $(SHELL) -x}
Variable SHELL now has value '/bin/sh -x'
remake<1>
@end smallexample

Now we'll show this in a real example - stepping (or actually
``next''ing though the top-level makefile in the source distribution
for @value{REMAKE}:

@smallexample
$ @b{remake -X}
Reading makefiles...

(/tmp/remake/Makefile:256)
Makefile.in: Makefile.am config/readline.m4 gettext.m4 iconv.m4 lib-ld.m4 lib-link.m4 lib-prefix.m4 progtest.m4 acinclude.m4 configure.ac aclocal.m4
remake<0> @b{set variable SHELL $(SHELL) -x}
Variable SHELL now has value '/bin/sh -x'
remake<1> @b{n}
Updating goal targets....
 /tmp/remake/Makefile:250	File `all' does not exist.

(/tmp/remake/Makefile:250)
all: config.h
remake<2> p SHELL
Makefile:156 (origin: debugger) SHELL = /bin/bash -x
remake<3> @b{n}
   Prerequisite `stamp-h1' is newer than target `config.h'.
  /tmp/remake/Makefile:288	Must remake target `config.h'.

(/tmp/remake/Makefile:288)
config.h: stamp-h1
remake<4> @b{n}
if test ! -f config.h; then \
  rm -f stamp-h1; \
  remake stamp-h1; \
else :; fi
+ test '!' -f config.h
+ :
  /tmp/remake/Makefile:288	Successfully remade target file `config.h'.
@end smallexample

Above we see the script source code followed by the trace information
-- we took the ``else'' branch which has the null statement ``:''.

@node setq
@subsection Setting a variable to an unexpanded string (@samp{setq})

@table @code
@kindex setq @var{variable} @var{string}
@item setq @var{variable} @var{string}

Sets @var{variable} to the value @var{string}, but @var{string} is
@emph{not} expanded first as it is not you use @code{print}.
@end table

@node Front Ends
@chapter Using @value{DBG} from a front-end user interface

The only front-ends that can use @value{DBG} as a back-end debugger is
@sc{gnu} Emacs and @value{DDD}.

@menu
* Emacs::      Using @value{DBG} from @sc{gnu} Emacs
* DDD::        Using @value{DBG} from @value{DDD}
@end menu


@node Emacs
@section Using @value{DBG} from @sc{gnu} Emacs

@cindex Emacs
@cindex @sc{gnu} Emacs
There is a multi-debugger emacs interface which includes
@code{remake}. This is distributed as a separate program and is
available via the Emacs package managers ELPA or MELPA. See
@url{https://github.com/realgud/realgud}

@node DDD
@section Using @value{REMAKE} from @value{DDD}
@cindex DDD

@value{REMAKE} support is rather new in @value{DDD}. As a programming
language, @value{REMAKE} is not feature rich: there are no record
structures or hash tables (yet), no pointers, package variable scoping
or methods. So much of the data display and visualization features of
@value{DDD} are disabled.

As with any scripting or interpreted language (e.g. Perl), one can't
step by a single machine-language instruction. So the ddd Stepi/Nexti
commands are disabled.

@node Make Debugger Bugs
@chapter Reporting Bugs
@cindex bugs
@cindex reporting bugs

Your bug reports play an essential role in making the @value{REMAKE} reliable.

Reporting a bug may help you by bringing a solution to your problem, or it
may not.  But in any case the principal function of a bug report is to help
the entire community by making the next version of @value{REMAKE} work better.  Bug
reports are your contribution to the maintenance of @value{REMAKE}.

In order for a bug report to serve its purpose, you must include the
information that enables us to fix the bug.

@menu
* Bug Criteria::                Have you found a bug?
* Bug Reporting::               How to report bugs
@end menu

@node Bug Criteria
@section Have you found a bug?
@cindex bug criteria

If you are not sure whether you have found a bug, here are some guidelines:

@itemize @bullet
@cindex fatal signal
@cindex debugger crash
@cindex crash, debugger
@item
If the debugger gets a fatal signal, for any input whatever, that is a
@value{REMAKE} bug.  Reliable debuggers never crash.

@cindex error on valid input
@item
If @value{REMAKE} produces an error message for valid input, that is a
bug.  (Note that if you're cross debugging, the problem may also be
somewhere in the connection to the target.)

@cindex invalid input
@item
If @value{REMAKE} does not produce an error message for invalid input,
that is a bug.  However, you should note that your idea of
``invalid input'' might be our idea of ``an extension'' or ``support
for traditional practice''.

@item
If you are an experienced user of debugging tools, your suggestions
for improvement of @value{REMAKE} are welcome in any case.
@end itemize

@node Bug Reporting
@section How to report bugs
@cindex bug reports
@cindex debugger bugs, reporting

Submit bug reports for @value{REMAKE}
to @url{https://github.com/rocky/remake/issues}

The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}.  If you are not sure whether to state a
fact or leave it out, state it!

Often people omit facts because they think they know what causes the
problem and assume that some details do not matter.  Thus, you might
assume that the name of the variable you use in an example does not matter.
Well, probably it does not, but one cannot be sure.  Perhaps the bug is a
stray memory reference which happens to fetch from the location where that
name is stored in memory; perhaps, if the name were different, the contents
of that location would fool the debugger into doing the right thing despite
the bug.  Play it safe and give a specific, complete example.  That is the
easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable us to fix the
bug.  It may be that the bug has been reported previously, but neither
you nor we can know that unless your bug report is complete and
self-contained.

Sometimes people give a few sketchy facts and ask, ``Does this ring a
bell?''  Those bug reports are useless, and we urge everyone to
@emph{refuse to respond to them} except to chide the sender to report
bugs properly.

To enable us to fix the bug, you should include all these things:

@itemize @bullet
@item
The version of @value{REMAKE}.  @value{REMAKE} announces it if you start
with no arguments; you can also print it at any time using @code{version}
command.

Without this, we will not know whether there is any point in looking for
the bug in the current version of @value{REMAKE}.

@item
The type of machine you are using, and the operating system name and
version number.

@item
What compiler (and its version) was used to compile @value{REMAKE}---e.g.
``@code{gcc}--4.4.3-4ubuntu5''.

@item
The command arguments you gave the compiler to compile your example and
observe the bug.  For example, did you use @samp{-O}?  To guarantee
you will not omit something important, list them all.  A copy of the
Makefile (or the output from make) is sufficient.

If we were to try to guess the arguments, we would probably guess wrong
and then we might not encounter the bug.

@item
A complete input script, and all necessary source files, that will
reproduce the bug.

@item
A description of what behavior you observe that you believe is
incorrect.  For example, ``It gets a fatal signal.''

Of course, if the bug is that @value{REMAKE} gets a fatal signal, then we
will certainly notice it.  But if the bug is incorrect output, we might
not notice unless it is glaringly wrong.  You might as well not give us
a chance to make a mistake.

Even if the problem you experience is a fatal signal, you should still
say so explicitly.  Suppose something strange is going on, such as, your
copy of @value{REMAKE} is out of synchronization, or you have
encountered a bug in the C library on your system.  (This has happened!)
Your copy might crash and ours would not.  If you told us to expect a
crash, then when ours fails to crash, we would know that the bug was not
happening for us.  If you had not told us to expect a crash, then we
would not be able to draw any conclusion from our observations.

@item
If you wish to suggest changes to the @value{REMAKE} source, send us context
diffs.  If you even discuss something in the @value{REMAKE} source, refer to
it by context, not by line number.

The line numbers in our development sources will not match those in your
sources.  Your line numbers would convey no useful information to us.

@end itemize

Here are some things that are not necessary:

@itemize @bullet
@item
A description of the envelope of the bug.

Often people who encounter a bug spend a lot of time investigating
which changes to the input file will make the bug go away and which
changes will not affect it.

This is often time consuming and not very useful, because the way we
will find the bug is by running a single example under the debugger
with breakpoints, not by pure deduction from a series of examples.
We recommend that you save your time for something else.

Of course, if you can find a simpler example to report @emph{instead}
of the original one, that is a convenience for us.  Errors in the
output will be easier to spot, running under the debugger will take
less time, and so on.

However, simplification is not vital; if you do not want to do this,
report the bug anyway and send us the entire test case you used.

@item
A patch for the bug.

A patch for the bug does help us if it is a good one.  But do not omit
the necessary information, such as the test case, on the assumption that
a patch is all we need.  We might see problems with your patch and decide
to fix the problem another way, or we might not understand it at all.

Sometimes with a program as complicated as @value{REMAKE} it is very hard to
construct an example that will make the program follow a certain path
through the code.  If you do not send us the example, we will not be able
to construct one, so we will not be able to verify that the bug is fixed.

And if we cannot understand what bug you are trying to fix, or why your
patch should be an improvement, we will not install it.  A test case will
help us to understand.

@item
A guess about what the bug is or what it depends on.

Such guesses are usually wrong.  Even we cannot guess right about such
things without first using the debugger to find the facts.
@end itemize

@node History and Acknowledgments
@chapter History and Acknowledgments

My idea for a debugger for @value{REMAKE} came about on working on a
debugger for bash (@url{http://bashdb.sourceforge.net}). I knew the
bash debugger was good enough when it was able to debug
autoconf-generated script which are tens of thousands of lines long.

But almost immediately after scaling this new height, I became sunk
deep in depression when I realized that to debug the configuration
mess I also needed to deal with Makefiles, if not also autoconf, and
automake as well.

After seeing an article on the auto-configuration mess
@url{http://freshmeat.net/articles/view/889} I posted a query to ask
if anyone was interested in writing a debugger for @value{REMAKE}.

Almost year goes by and no takers. To put this in perspective. it was
over a decade before someone (me) did anything about a debugger for
bash. I was reminded of my query by accident when I got a query from one
of the GNU mailing lists that I am on regarding a problem in email on the
@value{MAKE} mailing list.

That jogged my memory. So I suggested the idea of a debugger to this
list, and was told how incredibly difficult it would be to write a
debugger and how incredibly unique @value{MAKE} is. At that point I
looked into the code and to my surprise and delight I found that in
contrast to BASH the code, @value{MAKE} is much smaller and written in a
more modern coding style (although certainly it could use much
improvement). In fact, it had most of the information stored that would
be helpful in a debugger. All I would need to do is add a GNU readline
for the debug loop, extend to save a target stack and track line numbers
and report line numbers better. But this last part I'd been through with
the bash debugger.

All in all, I've been very pleased at how far I've been able to get
with much less effort than needed for the bash debugger. That's not to
say that much work isn't still needed or that the overall design
couldn't be improved.

This documentation was modified from the GNU Bash Debugger (bashdb) Reference
manual which in turn was modified from GNU Bash debugger (gdb).

Many thanks to Yaroslav Halchenko who moved the CVS code over to git on
github. He is also packages this for Debian. And thanks to all the other
packagers for the other OS distributions.

Additions to this section are particularly welcome.  If you or your
friends (or enemies, to be evenhanded) have been unfairly omitted from
this list, we would like to add your names!

@c The readline documentation is distributed with the readline code
@c and consists of the two following files:
@c     rluser.texinfo
@c     inc-hist.texinfo
@c Use -I with makeinfo to point to the appropriate directory,
@c environment var TEXINPUTS with TeX.
@c @include rluser.texinfo
@c @include hsuser.texinfo

@c @include gpl.texi

@c @include fdl.texi

@node Command Index
@unnumbered Command Index
@printindex ky

@node General Index
@unnumbered General Index
@printindex cp

@tex
% I think something like @@colophon should be in texinfo.  In the
% meantime:
\long\def\colophon{\hbox to0pt{}\vfill
\centerline{The body of this manual is set in}
\centerline{\fontname\tenrm,}
\centerline{with headings in {\bf\fontname\tenbf}}
\centerline{and examples in {\tt\fontname\tentt}.}
\centerline{{\it\fontname\tenit\/},}
\centerline{{\bf\fontname\tenbf}, and}
\centerline{{\sl\fontname\tensl\/}}
\centerline{are used for emphasis.}\vfill}
\page\colophon
% Blame: doc@@cygnus.com, 1991.
@end tex

@bye
