.\" by Kevin Braunsdorf
.\" $Id: maketd.man,v 4.16 2012/10/07 16:21:50 ksb Exp $
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -tbl -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -tbl -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/maketd.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/maketd.1*
.TH MAKETD 1 LOCAL
.SH NAME
maketd - edit a makefile to update transitive dependencies
.SH SYNOPSIS
.ds PN "maketd
\fI\*(PN\fP [\fB\-4Cabcdflnrvx\fP] [\fB\-D\fP\~\fIdefine\fP] [\fB\-e\fP\~\fIrule\fP] [\fB\-L\fP\~\fIlib.a\fP] [\fB\-I\fP\~\fIincludedir\fP] [\fB\-U\fP\~\fIundefine\fP] [\fB\-j\fP\~\fIextender\fP] [\fB\-m\fP\~\fImakefile\fP] [\fB\-o\fP\~\fIdir\fP] [\fB\-s\fP\~\fIsuffix\fP] [\fB\-t\fP\~\fItarget\fP] [\fBfiles\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
.B Maketd
computes dependencies for targets that are introduced through the
C preprocessor's (\fBcpp\fP) \fB#include\fP directive.
The development of this program resulted from \fBmake\fP(1)'s
inability to recognize transitive dependencies.  For example,
given the following makefile fragment:
.RS
.nf
xx.o: xx.c e.h

e.h: struct.h /usr/include/local/const.h
.fi
.RE
\fBMake\fP will \fUnot\fP recognize the target xx.o's dependency on struct.h.
.P
\fIMaketd\fP generates lines like:
.RS
.nf
xx.o: xx.c e.h struct.h $L/const.h
.fi
.RE
Thus making the target xx.o not only dependent on all files that it includes,
but also recursively on all files that the included files include.
This is achieved by passing the source through the C preprocessor
(via either \fBcc\fP \fB\-M\fP or \fBcc\fP \fB\-E\fP).
.PP
The directories used in the search for include files
are identical to the ones used by the C compiler because the
C preprocessor is used.  This also means that \fB#define\fP's,
\fB#ifdef\fP's, etc., are evaluated.
It is necessary to recompute the dependencies when any source has been changed.
The generated dependencies will be inserted after a line of the form
\*(lq# DO NOT DELETE...\*(rq (which will be inserted if \fI\*(PN\fP
finds the end of file).
Everything after this line may be deleted or changed as \fI\*(PN\fP edits
the \fImakefile\fP (the portion of the makefile before this line is only
examined for context).
If no such line exists, a line of the expected form will be emitted,
followed by the dependencies.
.PP
By default \fI\*(PN\fP will search for the \fImakefile\fP
to be edited in the same way \fBmake\fP does; that is by first checking
for the existence of \*(lqmakefile\*(rq, then \*(lqMakefile\*(rq.
The \fB\-m\fP and \fB\-d\fP options override this default action (below).
Before it is edited, \fImakefile\fP will be saved in
\*(lq\fImakefile\fP.\fIextend\fP\*(rq
(overwriting any existing file with the same name).
This \fIextender\fP on the old version of \fImakefile\fP may
be changed by using the \fB\-j\fP option (below).
.SH OPTIONS
.PP
Options and arguments may be intermixed on the command line to modify
\fI\*(PN\fP's behavior on a per file basis.
.TP
.BI \-4
Use \fBm4\fP(1) as the preprocessor rather than \fBcc\fP(1).
This requires that modifications have been made to \fBm4\fP and that
this program be compiled with CPP_M defined.  Use \*(lqmaketd \-h\*(rq
to check this.
.TP
.nf
.BI \-a
.fi
Normally, dependencies on files in \*(lq/usr/include\*(rq are
not included.  This option also includes dependencies on those files.
This option should always be used for system level makefiles.
.TP
.nf
.BI \-b
.fi
Generate dependencies for binaries rather than object files.
This is equivalent to specifying a null suffix:  the \*(lq.o\*(rq
is stripped from the target.
.TP
.nf
.BI \-c
.fi
Use cc to generate dependencies (rather than m4).  This is the default.
.TP
.nf
.BI \-d
.fi
Dependencies are written to standard output instead of editing a makefile.
The standard header and trailer, \*(lq# DO NOT DELETE...\*(rq are not printed.
.TP
.nf
.BI \-e rule
.fi
The given \fIrule\fP is ouptut under each of the following \fIfile\fP's
dependency lists.
For \fBprintf\fP-like percent (\fB%\fP) escapes are expanded to allow the
user to customize the rule.  (This options has been in \fI\*(PN\fP for
many releases, but has not been documented.)
.RS
.TS
allbox;
c l.
markup	expands to
%	a literal percent
F	the source file name
I	the \fBcpp\fP flags for this file
O	the source dir
S	the source suffix
L	the library containing this file
T	the source basename
f	the full target file
o	the target dir (set by \fB\-o\fP)
s	the target suffix (set by \fB\-s\fP)
t	the target base name (set by \fB\-t\fP)
.TE
.RE
.sp
This is most useful for creation of \fBsendmail\fP recipe files.
.TP
.nf
.BI \-f
.fi
Force printing of header and trailer.
Normally these are suppressed when the output file is the standard output.
.TP
.nf
.BI \-h
.fi
Only output a usage summary.
.TP
.nf
.BI \-j extender
.fi
Specify an extension for the backup makefile, rather than the default
\*(lqbak\*(rq extender.
.TP
.nf
.BI \-l
.fi
Turn off the nonlocal object option, and make all targets local.
.TP
.nf
.BI \-m makefile
.fi
Instead of editing \*(lqmakefile\*(rq, \fImakefile\fP is edited.
.TP
.nf
.BI \-n
.fi
Generate nonlocal object dependency paths.
These paths will match the source paths given.
.TP
.nf
.BI \-o dir
.fi
Generate nonlocal object dependencies in the specified \fIdir\fP.
This option generates dependencies of the form
.nf
	\fIdir\fP/a.o: a.c
.fi
which is useful for makefiles that produce the objects in
a separate subdirectory.
The name of the directory must not be empty (see \fB\-l\fP above).
.TP
.nf
.BI \-r
.fi
Replace the dependencies for the target(s) mentioned on the command line.
Do not alter any other dependencies that may have been in \fImakefile\fP.
This option is of limited use and unlimited misuse: beware.
.TP
.nf
.BI \-s suffix
.fi
Supply a suffix for the target.  The \fIsuffix\fP should
start with a \*(lq.\*(rq.
The target file name should have a suffix of some sort that
is delimited by a \*(lq.\*(rq that is replaced by this suffix.
.TP
.nf
.BI \-t target
.fi
Supply a new basename for the target rather than using the basename of the
source file.
.TP
.nf
.BI \-v
.fi
Be verbose.
Extra output is directed to the standard error channel.
.TP
.nf
.BI \-V
.fi
Show which version of \fI\*(PN\fP is running.
.TP
.nf
.BI \-x
.fi
Do not shorten include files.
The pathnames \*(lq/usr/include\*(rq and \*(lq/usr/include/sys\*(rq
along with any pathnames specified with the \-I options, are abbreviated.
Unused uppercase single letters are defined in \fImakefile\fP and used to
compress pathnames.
.TP
.nf
.BI \-C
.fi
Cancel all previous cpp flags (\fB\-D\fP, \fB\-I\fP, and \fB\-U\fP)
and begin a new list.  This is useful for generating
dependencies for more than one product with only one \fI\*(PN\fP call.
.TP
.nf
.BI \-D define
.fi
Specify a cpp (C preprocessor) definition.  See \fBcc\fP(1)
for a complete description.
.TP
.nf
.BI \-E
.fi
Cancel an explicit \fIrule\fP given by \fB\-e\fP.
.\".TP
.\".nf
.\".BI \-F gen-dep
.\".fi
.\"The \fIgen-dep\fP shell command is expanded as a \-e \fIrule\fP would be
.\"and given to the shell.  The resulting output must look like the
.\"output of \fBcpp\fP \fB\-M\fP, that is contain only lines of the form:
.\".RS
.\".nf
.\"\fItarget\fP\fB: \fP\fIdep\fP
.\".fi
.\".RE
.\"which should list of all the \fIdeps\fP on which \fItarget\fP
.\"depends one per line.
.TP
.nf
.BI \-I includedir
.fi
Specify a directory for cpp to search for include files.
See \fBcc\fP(1) for a complete description.
Note that \fIincludedir\fP is subject to abbreviation unless \fB\-x\fP is
given.
.TP
.nf
.BI \-L lib.a
.fi
This option produces a dependency that tells \fBmake\fP(1) that the
target is part of \fIlib.a\fP.
.TP
.nf
.BI \-U name
.fi
Remove any initial definition of the (C preprocessor) variable \fIname\fP.

.SH EXAMPLES
A typical application in a makefile might look like:
.RS
.nf
L=/usr/include/local
INCLUDE=  \-I$L \-I../h
CDEFS=	\-DPUCC \-DBSD4_2
CFLAGS= ${DEFS} ${INCLUDE}

SRC=	a.c b.c c.c
HDR=	a.h b.h c.h

\&. . .
depend: ${SRC} ${HDR}
	maketd \-a ${CDEFS} ${INCLUDE} ${SRC}

# DO NOT DELETE THIS LINE \- maketd DEPENDS ON IT

a.o: a.c a.h b.h c.h $L/goop.h

b.o: b.c b.h $L/goop.h

c.o: c.c c.h

# *** Do not add anything here \- It will go away. ***
.fi
.RE

.SH BUGS
.PP
If a single letter macro name is used but never defined (in the makefile),
\fI\*(PN\fP might still use it for an abbreviation name.  This should not
effect the makefile as all the dependencies and the redefinition of the
macro will follow the users last usage of it.  This happens in DYNIX makefiles
that use \*(lqP\*(rq to indicate that parallel compilation should be used.
We suggest that Makefiles which use this trick put a
.RS
.nf
P=
.fi
.RE
in the Makefile (above the all target) to keep \fI\*(PN\fP from using
the macro \*(lqP\*(rq; the command line definition of P="&" will override
the Makefile's definition.
.PP
Some more path compression could be done.
.SH AUTHORS
Stephan Bechtolsheim (a shell script), Purdue CS
.br
Stephen Uitti (a C version), Purdue CC
.br
Craig Norborg (m4 modifications), Purdue CC
.br
KS Braunsdorf (intermix options), NPCGuild.org
.SH "SEE ALSO"
.hlm 0
make(1), cc(1), m4(1), cpp(1), msync(8l), level2s(8l)