% Reference Card for GNU Make version 3.76.1 on Unix systems
% May be correct for older versions, too
%**start of header
\newcount\columnsperpage

% This file can be printed with 1, 2, or 3 columns per page (see below).
% Specify how many you want here.  Nothing else needs to be changed.

\columnsperpage=1

% Copyright (c) 2002 Free Software Foundation, Inc.

% This file is part of GNU Make.

% GNU Make is free software; you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation; either version 2, or (at your option)
% any later version.

% GNU Make is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.

% You should have received a copy of the GNU General Public License
% along with GNU Make; see the file COPYING.  If not, write to
% the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
% Boston, MA 02111-1307, USA.

% This file is intended to be processed by plain TeX (TeX82).
%
% The final reference card has six columns, three on each side.
% This file can be used to produce it in any of three ways:
% 1 column per page
%    produces six separate pages, each of which needs to be reduced to 80%.
%    This gives the best resolution.
% 2 columns per page
%    produces three already-reduced pages.
%    You will still need to cut and paste.
% 3 columns per page
%    produces two pages which must be printed sideways to make a
%    ready-to-use 8.5 x 11 inch reference card.
%    For this you need a dvi device driver that can print sideways.
% Which mode to use is controlled by setting \columnsperpage above.
%
% Author:
%  Gabor Urban
%  Internet: address@hidden
%
% Thanks to Viktor Pusztai and Akos...... for their many good ideas.


\def\versionnumber{0.8}
\def\year{2002}

\def\shortcopyrightnotice{\vskip 1ex plus 2 fill
  \centerline{\small \copyright\ \year\ Free Software Foundation, Inc.
  Permissions on back.  v\versionnumber}}

\def\copyrightnotice{
\vskip 1ex plus 2 fill\begingroup\small
\centerline{Copyright \copyright\ \year\ Free Software Foundation, Inc.}
\centerline{v\versionnumber{} for GNU Make version 3.76.1, November \year}
\centerline{designed by Stephen Gildea and G\'abor Urb\'an}

Permission is granted to make and distribute copies of
this card provided the copyright notice and this permission notice
are preserved on all copies.

For copies of the GNU Make manual, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

\endgroup}

% make \bye not \outer so that the \def\bye in the \else clause below
% can be scanned without complaint.
\def\bye{\par\vfill\supereject\end}

\newdimen\intercolumnskip	%horizontal space between columns
\newbox\columna			%boxes to hold columns already built
\newbox\columnb

\def\ncolumns{\the\columnsperpage}

\message{[\ncolumns\space 
  column\if 1\ncolumns\else s\fi\space per page]}

\def\scaledmag#1{ scaled \magstep #1}

% This multi-way format was designed by Stephen Gildea October 1986.
%% Extensions to the original format is done by Gabor Urban 2001.
% Note that the 1-column format is fontfamily-independent.
\if 1\ncolumns			%one-column format uses normal size
  \hsize 4in
  \vsize 10in
  \voffset -.7in
  \font\titlefont=\fontname\tenbf \scaledmag3
  \font\headingfont=\fontname\tenbf \scaledmag2
  \font\smallfont=\fontname\sevenrm
  \font\smallsy=\fontname\sevensy

  \footline{\hss\folio}
  \def\makefootline{\baselineskip10pt\hsize6.5in\line{\the\footline}}
\else				%2 or 3 columns uses prereduced size
  \hsize 3.2in
  \vsize 7.95in
  \hoffset -.75in
  \voffset -.745in
  \font\titlefont=cmbx10 \scaledmag2
  \font\headingfont=cmbx10 \scaledmag1
  \font\smallfont=cmr6
  \font\smallsy=cmsy6
  \font\eightrm=cmr8
  \font\eightbf=cmbx8
  \font\eightit=cmti8
  \font\eighttt=cmtt8
  \font\eightmi=cmmi8
  \font\eightsy=cmsy8
  \textfont0=\eightrm
  \textfont1=\eightmi
  \textfont2=\eightsy
  \def\rm{\eightrm}
  \def\bf{\eightbf}
  \def\it{\eightit}
  \def\tt{\eighttt}
  \normalbaselineskip=.8\normalbaselineskip
  \normallineskip=.8\normallineskip
  \normallineskiplimit=.8\normallineskiplimit
  \normalbaselines\rm		%make definitions take effect

  \if 2\ncolumns
    \let\maxcolumn=b
    \footline{\hss\rm\folio\hss}
    \def\makefootline{\vskip 2in \hsize=6.86in\line{\the\footline}}
  \else \if 3\ncolumns
    \let\maxcolumn=c
    \nopagenumbers
  \else
    \errhelp{You must set \columnsperpage equal to 1, 2, or 3.}
    \errmessage{Illegal number of columns per page}
  \fi\fi

  \intercolumnskip=.46in
  \def\abc{a}
  \output={%			%see The TeXbook page 257
      % This next line is useful when designing the layout.
      %\immediate\write16{Column \folio\abc\space starts with \firstmark}
      \if \maxcolumn\abc \multicolumnformat \global\def\abc{a}
      \else\if a\abc
	\global\setbox\columna\columnbox \global\def\abc{b}
        %% in case we never use \columnb (two-column mode)
        \global\setbox\columnb\hbox to -\intercolumnskip{}
      \else
	\global\setbox\columnb\columnbox \global\def\abc{c}\fi\fi}
  \def\multicolumnformat{\shipout\vbox{\makeheadline
      \hbox{\box\columna\hskip\intercolumnskip
        \box\columnb\hskip\intercolumnskip\columnbox}
      \makefootline}\advancepageno}
  \def\columnbox{\leftline{\pagebody}}

  \def\bye{\par\vfill\supereject
    \if a\abc \else\null\vfill\eject\fi
    \if a\abc \else\null\vfill\eject\fi
    \end}  
\fi

% we won't be using math mode much, so redefine some of the characters
% we might want to talk about
\catcode`\^=12
\catcode`\_=12

\chardef\\=`\\
\chardef\{=`\{
\chardef\}=`\}

\hyphenation{mini-buf-fer}

\parindent 0pt
\parskip 1ex plus .5ex minus .5ex

\def\small{\smallfont\textfont2=\smallsy\baselineskip=.8\baselineskip}

% newcolumn - force a new column.  Use sparingly, probably only for
% the first column of a page, which should have a title anyway.
\outer\def\newcolumn{\vfill\eject}

% title - page title.  Argument is title text.
\outer\def\title#1{{\titlefont\centerline{#1}}\vskip 1ex plus .5ex}

% section - new major section.  Argument is section name.
\outer\def\section#1{\par\filbreak
  \vskip 3ex plus 2ex minus 2ex {\headingfont #1}\mark{#1}%
  \vskip 2ex plus 1ex minus 1.5ex}

% subsection - new minor section.  Argument is section name by Gabor Urban
\outer\def\subsection#1{\par\goodbreak
  \vskip 3ex plus 2ex minus 2ex {\bf #1}\mark{#1}%
  \vskip 2ex plus 1ex minus 1.5ex}

\newdimen\keyindent

% beginindentedkeys...endindentedkeys - key definitions will be
% indented, but running text, typically used as headings to group
% definitions, will not.
\def\beginindentedkeys{\keyindent=1em}
\def\endindentedkeys{\keyindent=0em}
\endindentedkeys

% paralign - begin paragraph containing an alignment.
% If an \halign is entered while in vertical mode, a parskip is never
% inserted.  Using \paralign instead of \halign solves this problem.
\def\paralign{\vskip\parskip\halign}

% \<...> - surrounds a variable name in a code example
\def\<#1>{{\it #1\/}}

% kbd - argument is characters typed literally.  Like the Texinfo command.
\def\kbd#1{{\tt#1}\null}	%\null so not an abbrev even if period follows

% beginexample...endexample - surrounds literal text, such a code example.
% typeset in a typewriter font with line breaks preserved
\def\beginexample{\par\leavevmode\begingroup
  \obeylines\obeyspaces\parskip0pt\tt}
{\obeyspaces\global\let =\ }
\def\endexample{\endgroup}

% key - definition of a key.
% \key{description of key}{key-name}
% prints the description left-justified, and the key-name in a \kbd
% form near the right margin.
\def\key#1#2{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.75\hsize\rightskip=1em
  \hskip\keyindent\relax#1}\kbd{#2}\hfil}}

% args - definition of argument switches (Gabor Urban)
% GNU make uses no keybindings :-)
% \args{tarditional arguments}{POSIX arguments}
\def\args#1#2{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.75\hsize\rightskip=1em
  \hskip\keyindent\relax POSIX: \kbd{#2}} or \kbd{#1}\hfil}}

% posix - definition of argument switches (Gabor Urban)
% GNU make uses no keybindings :-)
% \posix{POSIX arguments}
\def\posix#1{\leavevmode\hbox to \hsize{\vtop
  {\hsize=.75\hsize\rightskip=1em
  \hskip\keyindent\relax POSIX \kbd{#1}}\hfil}}

\newbox\metaxbox
\setbox\metaxbox\hbox{\kbd{M-x }}
\newdimen\metaxwidth
\metaxwidth=\wd\metaxbox

% metax - definition of a M-x command.
% \metax{description of command}{M-x command-name}
% Tries to justify the beginning of the command name at the same place
% as \key starts the key name.  (The "M-x " sticks out to the left.)
\def\metax#1#2{\leavevmode\hbox to \hsize{\hbox to .75\hsize
  {\hskip\keyindent\relax#1\hfil}%
  \hskip -\metaxwidth minus 1fil
  \kbd{#2}\hfil}}

% threecol - like "key" but with two key names.
% for example, one for doing the action backward, and one for forward.
\def\threecol#1#2#3{\hskip\keyindent\relax#1\hfil&\kbd{#2}\hfil\quad
  &\kbd{#3}\hfil\quad\cr}

%**end of header

\title{GNU Make Reference Card}

\centerline{(for version 3.76.1)}

\section{1. Invoking GNU Make}

To invoke GNU make type the following command line:

\kbd{make [-f makefile-name] [options] [targets]}

or use the POSIX style command line:

\kbd{make [--file=makefile-name] [options] [targets]}

Standard makefile names:

-- \kbd{GNUMakefile}

-- \kbd{Makefile}

-- \kbd{makefile}

These file names will be searched for in the current directory automatically.

\section{2. Options}

Both the POSIX and the traditional format is given. Not all equivalent
options are given, if there are alternative forms to the same
switch. More information can be found in the GNU make manual.

\subsection{2.1 Debugging options}

\args{-n}{--recon, --dry-run, --just-print}

no execution, it prints the commands only.

\args{-d}{--debug}

prints detailed rules/decisions analyses for debugging

\args{-p}{--print-data-base}
    
prints all rules and variables

\args{-q}{--question}
   
returns $0$ if target up-to-date, $1$ if remake is to be done, $2$ if error
occoured

\args{-t}{--touch}

no execution, touch target files only

\args{-v}{--version}

print GNU make version info only

\args{-w}{--print-directory}

prints directory info, mainly for recursive makes

\args{-W file}{--what-if=file}

considers {\tt file} is updated, and follows the dependencies with this
as\-sump\-tion. 

\subsection{2.2 Directory handling}

\args{-C dir}{--directory=dir}

changes to directory {\tt dir} before reading the makedile or doing
anything (switches {\tt -w} on automatically) 

\posix{--no-print-directory}

switch {\tt -w} off if {\tt -c} is specified

\args{-I dir}{--include-dir=dir}

sets the {\tt dir} for makefile includes.

\subsection{2.3. Error handling}

\args{-i}{--ignore-errors}

ignore ALL errors

\args{-k}{--keep-going}

try to update other targets after errors

\args{-S}{-- stop, --no-keep-going}

opposite of {\tt -k}

\posix{--warn-undefined-variables}

prints warning if there are undefined variables

\subsection{2.4. Job control}

\args{-j jobnum}{--jobs=jobnum}

using more parallel jobs (commands), the maximum may be given

\args{-l load}{--max-load=load}

limits load factor, no arguments deletes previous limit

\subsection{2.5. Environment}

\args{-e}{--environment-overrides}

environment variables have precedence over makefile variables

\args{-r}{--no-builtin-rules}

no built-in implicite rules are used    

\subsection{2.6. Other switches}

\args{-o file}{--old-file=file}

do not remake dependencies of file

\args{-s}{--silent}

silent operation with no command echo

\newcolumn

\section{3. Writing Makefiles}

\subsection{3.1. Basic Elements of Makefiles}

3.1.1. Rule:
\beginexample		
target : dependency [depency ...]
\indent\indent command
\indent\indent [ command]
\endexample

Where:

a. {\it Target} is the result of the operation.

b., {\it Commands} are the sequences to execute (ie. the commands of the
operational system.

c., {\it Dependency} is the input of the operation

3.1.2. "Nested" rules:
\beginexample
target : target1 target2
	.....
target1 : dependencies_1
	......
target_2 : dependencies_2
	.....
\endexample

make program builds a {\it dependency-tree} from these rules.

3.1.3. Variables (macroes)

If
\beginexample
header = prg.h
code = prg.c
files = \$(header) \$(code)
\endexample
then \$(file) is expanded to "prg.h prg.c" running make program.

\subsection{3.2. Efficient (lazy) style and tricks}

{\bf Topics}: suffix rules, built-in variables, built-in rules, phony
targets and target selection

3.2.1. Suffix rules (aka pattern rules)

Rule used to process a depency of two given types of files (defined by
extensions). 
Syntax (eg):
\beginexample
	\%.o : \%.cxx
	    g++ -c \$<
\endexample

This will compile any C++ code, supposing it's extension is .cxx.

3.2.2., Built-in variables

There are a lot of variables to help help writing rules. Some
examples:
 
CC is set to "cc" to compile C code

SHELL is set to the given command interpreter

etc ....

More variables are described in the manual.

\newcolumn

3.2.3., Built-in rules

Most Linux/U*ix development activities are supported by built-in
rule. Eg:
\beginexample
      foo.o : foo.c
\endexample
dependency is processed correctly using the appropriate rules.

3.2.4., Miscellanious tricks

3.2.4.1 Not "real" targets $->$ goals

Some activities do not not produce real files $- >$ pseudo "phony"
target.
Eg:
\beginexample
clean :
\indent rm *.o
\indent rm *.a
\endexample

You can explicitely declare as phony:
\beginexample
.PHONY : clean
\endexample
\beginexample
clean :
\indent rm *.o
\indent rm *.a
\endexample
There are some other tricks with goals.

3.2.4.1., Target selections

-- make program updates the target(s) you specify in the command line

or

-- make program updates the first target in the makefile
automatically.

To circumvent the last feature use phony targets, eg:
\beginexample
   ALL : clean libs prg archive
\endexample

\shortcopyrightnotice

\title{GNU Make Reference Card}

\copyrightnotice

\bye