~ubuntu-branches/debian/sid/make-doc-non-dfsg/sid : revision 4

1

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">

2

<html>

3

<!-- This file documents the GNU make utility, which determines

4

automatically which pieces of a large program need to be recompiled,

5

and issues the commands to recompile them.

6

7

This is Edition 0.70, last updated 1 April 2006,

8

of The GNU Make Manual, for GNU make version 3.81.

9

10

Copyright C 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,

11

1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006

12

Free Software Foundation, Inc.

13

14

Permission is granted to copy, distribute and/or modify this document

15

under the terms of the GNU Free Documentation License, Version 1.2 or

16

any later version published by the Free Software Foundation; with no

17

Invariant Sections, with the Front-Cover Texts being "A GNU Manual,"

18

and with the Back-Cover Texts as in (a) below. A copy of the

19

license is included in the section entitled "GNU Free Documentation

20

License."

21

22

(a) The FSF's Back-Cover Text is: "You have freedom to copy and modify

23

this GNU Manual, like GNU software. Copies published by the Free

24

Software Foundation raise funds for GNU development."

25

26

-->

27

28

<!--

29

Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)

30

Karl Berry <karl@freefriends.org>

31

Olaf Bachmann <obachman@mathematik.uni-kl.de>

32

and many others.

33

Maintained by: Many creative people.

34

Send bugs and suggestions to <texi2html-bug@nongnu.org>

35

36

-->

37

<head>

38

<title>GNU make: 5. Writing the Commands in Rules</title>

39

40

41

42

43

44

45

46

47

<!--

48

a.summary-letter {text-decoration: none}

49

pre.display {font-family: serif}

50

pre.format {font-family: serif}

51

pre.menu-comment {font-family: serif}

52

pre.menu-preformatted {font-family: serif}

53

pre.smalldisplay {font-family: serif; font-size: smaller}

54

pre.smallexample {font-size: smaller}

55

pre.smallformat {font-family: serif; font-size: smaller}

56

pre.smalllisp {font-size: smaller}

57

span.roman {font-family:serif; font-weight:normal;}

58

span.sansserif {font-family:sans-serif; font-weight:normal;}

59

ul.toc {list-style: none}

60

-->

61

</style>

62

63

64

</head>

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

83

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

84

85

</tr></table>

86

<h1 class="chapter"> 5. Writing the Commands in Rules </h1>

87

88

<p>The commands of a rule consist of one or more shell command lines to

89

be executed, one at a time, in the order they appear. Typically, the

90

result of executing these commands is that the target of the rule is

91

brought up to date.

92

</p>

93

<p>Users use many different shell programs, but commands in makefiles are

94

always interpreted by ‘<tt>/bin/sh</tt>’ unless the makefile specifies

95

otherwise. See section <a href="#SEC61">Command Execution</a>.

96

</p>

97

98

<tr><td align="left" valign="top"><a href="#SEC57">5.1 Command Syntax</a></td><td>  </td><td align="left" valign="top"> Command syntax features and pitfalls.

99

</td></tr>

100

<tr><td align="left" valign="top"><a href="#SEC60">5.2 Command Echoing</a></td><td>  </td><td align="left" valign="top"> How to control when commands are echoed.

101

</td></tr>

102

<tr><td align="left" valign="top"><a href="#SEC61">5.3 Command Execution</a></td><td>  </td><td align="left" valign="top"> How commands are executed.

103

</td></tr>

104

<tr><td align="left" valign="top"><a href="#SEC64">5.4 Parallel Execution</a></td><td>  </td><td align="left" valign="top"> How commands can be executed in parallel.

105

</td></tr>

106

<tr><td align="left" valign="top"><a href="#SEC65">5.5 Errors in Commands</a></td><td>  </td><td align="left" valign="top"> What happens after a command execution error.

107

</td></tr>

108

<tr><td align="left" valign="top"><a href="#SEC66">5.6 Interrupting or Killing <code>make</code></a></td><td>  </td><td align="left" valign="top"> What happens when a command is interrupted.

109

</td></tr>

110

<tr><td align="left" valign="top"><a href="#SEC67">5.7 Recursive Use of <code>make</code></a></td><td>  </td><td align="left" valign="top"> Invoking <code>make</code> from makefiles.

111

</td></tr>

112

<tr><td align="left" valign="top"><a href="#SEC72">5.8 Defining Canned Command Sequences</a></td><td>  </td><td align="left" valign="top"> Defining canned sequences of commands.

113

</td></tr>

114

<tr><td align="left" valign="top"><a href="#SEC73">5.9 Using Empty Commands</a></td><td>  </td><td align="left" valign="top"> Defining useful, do-nothing commands.

115

</td></tr>

116

</table>

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

134

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

135

136

</tr></table>

137

<h2 class="section"> 5.1 Command Syntax </h2>

138

139

<p>Makefiles have the unusual property that there are really two distinct

140

syntaxes in one file. Most of the makefile uses <code>make</code> syntax

141

(see section <a href="make_3.html#SEC13">Writing Makefiles</a>). However, commands are meant to be

142

interpreted by the shell and so they are written using shell syntax.

143

The <code>make</code> program does not try to understand shell syntax: it

144

performs only a very few specific translations on the content of the

145

command before handing it to the shell.

146

</p>

147

<p>Each command line must start with a tab, except that the first command

148

line may be attached to the target-and-prerequisites line with a

149

semicolon in between. <em>Any</em> line in the makefile that begins

150

with a tab and appears in a “rule context” (that is, after a rule

151

has been started until another rule or variable definition) will be

152

considered a command line for that rule. Blank lines and lines of

153

just comments may appear among the command lines; they are ignored.

154

</p>

155

<p>Some consequences of these rules include:

156

</p>

157

<ul>

158

<li>

159

A blank line that begins with a tab is not blank: it's an empty

160

command (see section <a href="#SEC73">Using Empty Commands</a>).

161

162

163

164

165

</li><li>

166

A comment in a command line is not a <code>make</code> comment; it will be

167

passed to the shell as-is. Whether the shell treats it as a comment

168

or not depends on your shell.

169

170

</li><li>

171

A variable definition in a “rule context” which is indented by a tab

172

as the first character on the line, will be considered a command line,

173

not a <code>make</code> variable definition, and passed to the shell.

174

175

</li><li>

176

A conditional expression (<code>ifdef</code>, <code>ifeq</code>,

177

etc. see section <a href="make_7.html#SEC90">Syntax of Conditionals</a>) in a “rule

178

context” which is indented by a tab as the first character on the

179

line, will be considered a command line and be passed to the shell.

180

181

</li></ul>

182

183

184

<tr><td align="left" valign="top"><a href="#SEC58">5.1.1 Splitting Command Lines</a></td><td>  </td><td align="left" valign="top"> Breaking long command lines for readability.

185

</td></tr>

186

<tr><td align="left" valign="top"><a href="#SEC59">5.1.2 Using Variables in Commands</a></td><td>  </td><td align="left" valign="top"> Using <code>make</code> variables in commands.

187

</td></tr>

188

</table>

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

206

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

207

208

</tr></table>

209

<h3 class="subsection"> 5.1.1 Splitting Command Lines </h3>

210

211

<p>One of the few ways in which <code>make</code> does interpret command lines

212

is checking for a backslash just before the newline. As in normal

213

makefile syntax, a single command can be split into multiple lines in

214

the makefile by placing a backslash before each newline. A sequence

215

of lines like this is considered a single command, and one instance of

216

the shell will be invoked to run it.

217

</p>

218

<p>However, in contrast to how they are treated in other places in a

219

makefile, backslash-newline pairs are <em>not</em> removed from the

220

command. Both the backslash and the newline characters are preserved

221

and passed to the shell. How the backslash-newline is interpreted

222

depends on your shell. If the first character of the next line

223

after the backslash-newline is a tab, then that tab (and only that

224

tab) is removed. Whitespace is never added to the command.

225

</p>

226

<p>For example, this makefile:

227

</p>

228

<table><tr><td> </td><td><pre class="example">all :

229

@echo no\

230

space

231

@echo no\

232

space

233

@echo one \

234

space

235

@echo one\

236

space

237

</pre></td></tr></table>

238

239

<p>consists of four separate shell commands where the output is:

240

</p>

241

<table><tr><td> </td><td><pre class="example">nospace

242

nospace

243

one space

244

one space

245

</pre></td></tr></table>

246

247

<p>As a more complex example, this makefile:

248

</p>

249

<table><tr><td> </td><td><pre class="example">all : ; @echo 'hello \

250

world' ; echo "hello \

251

world"

252

</pre></td></tr></table>

253

254

<p>will run one shell with a command script of:

255

</p>

256

<table><tr><td> </td><td><pre class="example">echo 'hello \

257

world' ; echo "hello \

258

world"

259

</pre></td></tr></table>

260

261

<p>which, according to shell quoting rules, will yield the following output:

262

</p>

263

<table><tr><td> </td><td><pre class="example">hello \

264

world

265

hello world

266

</pre></td></tr></table>

267

268

<p>Notice how the backslash/newline pair was removed inside the string quoted

269

with double quotes (<code>"..."</code>), but not from the string quoted with single

270

quotes (<code>'...'</code>). This is the way the default shell (‘<tt>/bin/sh</tt>’)

271

handles backslash/newline pairs. If you specify a different shell in your

272

makefiles it may treat them differently.

273

</p>

274

<p>Sometimes you want to split a long line inside of single quotes, but

275

you don't want the backslash-newline to appear in the quoted content.

276

This is often the case when passing scripts to languages such as Perl,

277

where extraneous backslashes inside the script can change its meaning

278

or even be a syntax error. One simple way of handling this is to

279

place the quoted string, or even the entire command, into a

280

<code>make</code> variable then use the variable in the command. In this

281

situation the newline quoting rules for makefiles will be used, and

282

the backslash-newline will be removed. If we rewrite our example

283

above using this method:

284

</p>

285

<table><tr><td> </td><td><pre class="example">HELLO = 'hello \

286

world'

287

288

all : ; @echo $(HELLO)

289

</pre></td></tr></table>

290

291

<p>we will get output like this:

292

</p>

293

<table><tr><td> </td><td><pre class="example">hello world

294

</pre></td></tr></table>

295

296

<p>If you like, you can also use target-specific variables

297

(see section <a href="make_6.html#SEC86">Target-specific Variable Values</a>) to obtain

298

a tighter correspondence between the variable and the command that

299

uses it.

300

</p>

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

317

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

318

319

</tr></table>

320

<h3 class="subsection"> 5.1.2 Using Variables in Commands </h3>

321

322

<p>The other way in which <code>make</code> processes commands is by expanding

323

any variable references in them (see section <a href="make_6.html#SEC75">Basics of Variable References</a>). This occurs after make has finished reading all the

324

makefiles and the target is determined to be out of date; so, the

325

commands for targets which are not rebuilt are never expanded.

326

</p>

327

<p>Variable and function references in commands have identical syntax and

328

semantics to references elsewhere in the makefile. They also have the

329

same quoting rules: if you want a dollar sign to appear in your

330

command, you must double it (‘<samp>$$</samp>’). For shells like the default

331

shell, that use dollar signs to introduce variables, it's important to

332

keep clear in your mind whether the variable you want to reference is

333

a <code>make</code> variable (use a single dollar sign) or a shell variable

334

(use two dollar signs). For example:

335

</p>

336

<table><tr><td> </td><td><pre class="example">LIST = one two three

337

all:

338

for i in $(LIST); do \

339

echo $$i; \

340

done

341

</pre></td></tr></table>

342

343

<p>results in the following command being passed to the shell:

344

</p>

345

<table><tr><td> </td><td><pre class="example">for i in one two three; do \

346

echo $i; \

347

done

348

</pre></td></tr></table>

349

350

<p>which generates the expected result:

351

</p>

352

<table><tr><td> </td><td><pre class="example">one

353

two

354

three

355

</pre></td></tr></table>

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

373

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

374

375

</tr></table>

376

<h2 class="section"> 5.2 Command Echoing </h2>

377

378

<p>Normally <code>make</code> prints each command line before it is executed.

379

We call this <em>echoing</em> because it gives the appearance that you

380

are typing the commands yourself.

381

</p>

382

<p>When a line starts with ‘<samp>@</samp>’, the echoing of that line is suppressed.

383

The ‘<samp>@</samp>’ is discarded before the command is passed to the shell.

384

Typically you would use this for a command whose only effect is to print

385

something, such as an <code>echo</code> command to indicate progress through

386

the makefile:

387

</p>

388

<table><tr><td> </td><td><pre class="example">@echo About to make distribution files

389

</pre></td></tr></table>

390

391

392

393

394

395

<p>When <code>make</code> is given the flag ‘<samp>-n</samp>’ or ‘<samp>--just-print</samp>’

396

it only echoes commands, it won't execute them. See section <a href="make_9.html#SEC112">Summary of Options</a>. In this case and only this case, even the

397

commands starting with ‘<samp>@</samp>’ are printed. This flag is useful for

398

finding out which commands <code>make</code> thinks are necessary without

399

actually doing them.

400

</p>

401

402

403

404

405

<p>The ‘<samp>-s</samp>’ or ‘<samp>--silent</samp>’

406

flag to <code>make</code> prevents all echoing, as if all commands

407

started with ‘<samp>@</samp>’. A rule in the makefile for the special target

408

<code>.SILENT</code> without prerequisites has the same effect

409

(see section <a href="make_4.html#SEC48">Special Built-in Target Names</a>).

410

<code>.SILENT</code> is essentially obsolete since ‘<samp>@</samp>’ is more flexible.

411

</p>

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

428

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

429

430

</tr></table>

431

<h2 class="section"> 5.3 Command Execution </h2>

432

433

<p>When it is time to execute commands to update a target, they are

434

executed by invoking a new subshell for each command line. (In

435

practice, <code>make</code> may take shortcuts that do not affect the

436

results.)

437

</p>

438

439

440

441

<p><strong>Please note:</strong> this implies that setting shell variables and

442

invoking shell commands such as <code>cd</code> that set a context local to

443

each process will not affect the following command lines.<a name="DOCF2" href="make_fot.html#FOOT2">(2)</a> If you want to use <code>cd</code> to affect the next statement,

444

put both statements in a single command line. Then <code>make</code> will

445

invoke one shell to run the entire line, and the shell will execute

446

the statements in sequence. For example:

447

</p>

448

<table><tr><td> </td><td><pre class="example">foo : bar/lose

449

cd $(@D) && gobble $(@F) > ../$@

450

</pre></td></tr></table>

451

452

<p>Here we use the shell AND operator (<code>&&</code>) so that if the

453

<code>cd</code> command fails, the script will fail without trying to invoke

454

the <code>gobble</code> command in the wrong directory, which could cause

455

problems (in this case it would certainly cause ‘<tt>../foo</tt>’ to be

456

truncated, at least).

457

</p>

458

459

<tr><td align="left" valign="top"><a href="#SEC62">5.3.1 Choosing the Shell</a></td><td>  </td><td align="left" valign="top"> How <code>make</code> chooses the shell used

460

to run commands.

461

</td></tr>

462

</table>

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

480

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

481

482

</tr></table>

483

<h3 class="subsection"> 5.3.1 Choosing the Shell </h3>

484

485

<p>The program used as the shell is taken from the variable <code>SHELL</code>.

486

If this variable is not set in your makefile, the program

487

‘<tt>/bin/sh</tt>’ is used as the shell.

488

</p>

489

490

<p>Unlike most variables, the variable <code>SHELL</code> is never set from the

491

environment. This is because the <code>SHELL</code> environment variable is

492

used to specify your personal choice of shell program for interactive

493

use. It would be very bad for personal choices like this to affect the

494

functioning of makefiles. See section <a href="make_6.html#SEC85">Variables from the Environment</a>.

495

</p>

496

<p>Furthermore, when you do set <code>SHELL</code> in your makefile that value

497

is <em>not</em> exported in the environment to commands that <code>make</code>

498

invokes. Instead, the value inherited from the user's environment, if

499

any, is exported. You can override this behavior by explicitly

500

exporting <code>SHELL</code> (see section <a href="#SEC69">Communicating Variables to a Sub-<code>make</code></a>), forcing it to be passed in the

501

environment to commands.

502

</p>

503

504

<p>However, on MS-DOS and MS-Windows the value of <code>SHELL</code> in the

505

environment <strong>is</strong> used, since on those systems most users do not

506

set this variable, and therefore it is most likely set specifically to

507

be used by <code>make</code>. On MS-DOS, if the setting of <code>SHELL</code> is

508

not suitable for <code>make</code>, you can set the variable

509

<code>MAKESHELL</code> to the shell that <code>make</code> should use; if set it

510

will be used as the shell instead of the value of <code>SHELL</code>.

511

</p>

512

513

<h4 class="subsubheading"> Choosing a Shell in DOS and Windows </h4>

514

515

<p>Choosing a shell in MS-DOS and MS-Windows is much more complex than on

516

other systems.

517

</p>

518

519

<p>On MS-DOS, if <code>SHELL</code> is not set, the value of the variable

520

<code>COMSPEC</code> (which is always set) is used instead.

521

</p>

522

523

<p>The processing of lines that set the variable <code>SHELL</code> in Makefiles

524

is different on MS-DOS. The stock shell, ‘<tt>command.com</tt>’, is

525

ridiculously limited in its functionality and many users of <code>make</code>

526

tend to install a replacement shell. Therefore, on MS-DOS, <code>make</code>

527

examines the value of <code>SHELL</code>, and changes its behavior based on

528

whether it points to a Unix-style or DOS-style shell. This allows

529

reasonable functionality even if <code>SHELL</code> points to

530

‘<tt>command.com</tt>’.

531

</p>

532

<p>If <code>SHELL</code> points to a Unix-style shell, <code>make</code> on MS-DOS

533

additionally checks whether that shell can indeed be found; if not, it

534

ignores the line that sets <code>SHELL</code>. In MS-DOS, GNU <code>make</code>

535

searches for the shell in the following places:

536

</p>

537

<ol>

538

<li>

539

In the precise place pointed to by the value of <code>SHELL</code>. For

540

example, if the makefile specifies ‘<samp>SHELL = /bin/sh</samp>’, <code>make</code>

541

will look in the directory ‘<tt>/bin</tt>’ on the current drive.

542

543

</li><li>

544

In the current directory.

545

546

</li><li>

547

In each of the directories in the <code>PATH</code> variable, in order.

548

549

</li></ol>

550

551

<p>In every directory it examines, <code>make</code> will first look for the

552

specific file (‘<tt>sh</tt>’ in the example above). If this is not found,

553

it will also look in that directory for that file with one of the known

554

extensions which identify executable files. For example ‘<tt>.exe</tt>’,

555

‘<tt>.com</tt>’, ‘<tt>.bat</tt>’, ‘<tt>.btm</tt>’, ‘<tt>.sh</tt>’, and some others.

556

</p>

557

<p>If any of these attempts is successful, the value of <code>SHELL</code> will

558

be set to the full pathname of the shell as found. However, if none of

559

these is found, the value of <code>SHELL</code> will not be changed, and thus

560

the line that sets it will be effectively ignored. This is so

561

<code>make</code> will only support features specific to a Unix-style shell if

562

such a shell is actually installed on the system where <code>make</code> runs.

563

</p>

564

<p>Note that this extended search for the shell is limited to the cases

565

where <code>SHELL</code> is set from the Makefile; if it is set in the

566

environment or command line, you are expected to set it to the full

567

pathname of the shell, exactly as things are on Unix.

568

</p>

569

<p>The effect of the above DOS-specific processing is that a Makefile that

570

contains ‘<samp>SHELL = /bin/sh</samp>’ (as many Unix makefiles do), will work

571

on MS-DOS unaltered if you have e.g. ‘<tt>sh.exe</tt>’ installed in some

572

directory along your <code>PATH</code>.

573

</p>

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

590

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

591

592

</tr></table>

593

<h2 class="section"> 5.4 Parallel Execution </h2>

594

595

<p>GNU <code>make</code> knows how to execute several commands at once.

596

Normally, <code>make</code> will execute only one command at a time, waiting

597

for it to finish before executing the next. However, the ‘<samp>-j</samp>’ or

598

‘<samp>--jobs</samp>’ option tells <code>make</code> to execute many commands

599

simultaneously.

600

</p>

601

<p>On MS-DOS, the ‘<samp>-j</samp>’ option has no effect, since that system doesn't

602

support multi-processing.

603

</p>

604

<p>If the ‘<samp>-j</samp>’ option is followed by an integer, this is the number of

605

commands to execute at once; this is called the number of <em>job slots</em>.

606

If there is nothing looking like an integer after the ‘<samp>-j</samp>’ option,

607

there is no limit on the number of job slots. The default number of job

608

slots is one, which means serial execution (one thing at a time).

609

</p>

610

<p>One unpleasant consequence of running several commands simultaneously is

611

that output generated by the commands appears whenever each command

612

sends it, so messages from different commands may be interspersed.

613

</p>

614

<p>Another problem is that two processes cannot both take input from the

615

same device; so to make sure that only one command tries to take input

616

from the terminal at once, <code>make</code> will invalidate the standard

617

input streams of all but one running command. This means that

618

attempting to read from standard input will usually be a fatal error (a

619

‘<samp>Broken pipe</samp>’ signal) for most child processes if there are

620

several.

621

622

623

</p>

624

<p>It is unpredictable which command will have a valid standard input stream

625

(which will come from the terminal, or wherever you redirect the standard

626

input of <code>make</code>). The first command run will always get it first, and

627

the first command started after that one finishes will get it next, and so

628

on.

629

</p>

630

<p>We will change how this aspect of <code>make</code> works if we find a better

631

alternative. In the mean time, you should not rely on any command using

632

standard input at all if you are using the parallel execution feature; but

633

if you are not using this feature, then standard input works normally in

634

all commands.

635

</p>

636

<p>Finally, handling recursive <code>make</code> invocations raises issues. For

637

more information on this, see

638

<a href="#SEC70">Communicating Options to a Sub-<code>make</code></a>.

639

</p>

640

<p>If a command fails (is killed by a signal or exits with a nonzero

641

status), and errors are not ignored for that command

642

(see section <a href="#SEC65">Errors in Commands</a>),

643

the remaining command lines to remake the same target will not be run.

644

If a command fails and the ‘<samp>-k</samp>’ or ‘<samp>--keep-going</samp>’

645

option was not given

646

(see section <a href="make_9.html#SEC112">Summary of Options</a>),

647

<code>make</code> aborts execution. If make

648

terminates for any reason (including a signal) with child processes

649

running, it waits for them to finish before actually exiting.

650

</p>

651

652

653

654

655

656

657

<p>When the system is heavily loaded, you will probably want to run fewer jobs

658

than when it is lightly loaded. You can use the ‘<samp>-l</samp>’ option to tell

659

<code>make</code> to limit the number of jobs to run at once, based on the load

660

average. The ‘<samp>-l</samp>’ or ‘<samp>--max-load</samp>’

661

option is followed by a floating-point number. For

662

example,

663

</p>

664

<table><tr><td> </td><td><pre class="example">-l 2.5

665

</pre></td></tr></table>

666

667

<p>will not let <code>make</code> start more than one job if the load average is

668

above 2.5. The ‘<samp>-l</samp>’ option with no following number removes the

669

load limit, if one was given with a previous ‘<samp>-l</samp>’ option.

670

</p>

671

<p>More precisely, when <code>make</code> goes to start up a job, and it already has

672

at least one job running, it checks the current load average; if it is not

673

lower than the limit given with ‘<samp>-l</samp>’, <code>make</code> waits until the load

674

average goes below that limit, or until all the other jobs finish.

675

</p>

676

<p>By default, there is no load limit.

677

</p>

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

694

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

695

696

</tr></table>

697

<h2 class="section"> 5.5 Errors in Commands </h2>

698

699

<p>After each shell command returns, <code>make</code> looks at its exit status.

700

If the command completed successfully, the next command line is executed

701

in a new shell; after the last command line is finished, the rule is

702

finished.

703

</p>

704

<p>If there is an error (the exit status is nonzero), <code>make</code> gives up on

705

the current rule, and perhaps on all rules.

706

</p>

707

<p>Sometimes the failure of a certain command does not indicate a problem.

708

For example, you may use the <code>mkdir</code> command to ensure that a

709

directory exists. If the directory already exists, <code>mkdir</code> will

710

report an error, but you probably want <code>make</code> to continue regardless.

711

</p>

712

713

<p>To ignore errors in a command line, write a ‘<samp>-</samp>’ at the beginning of

714

the line's text (after the initial tab). The ‘<samp>-</samp>’ is discarded before

715

the command is passed to the shell for execution.

716

</p>

717

<p>For example,

718

</p>

719

<table><tr><td> </td><td><pre class="example">clean:

720

-rm -f *.o

721

</pre></td></tr></table>

722

723

724

<p>This causes <code>rm</code> to continue even if it is unable to remove a file.

725

</p>

726

727

728

729

<p>When you run <code>make</code> with the ‘<samp>-i</samp>’ or ‘<samp>--ignore-errors</samp>’

730

flag, errors are ignored in all commands of all rules. A rule in the

731

makefile for the special target <code>.IGNORE</code> has the same effect, if

732

there are no prerequisites. These ways of ignoring errors are obsolete

733

because ‘<samp>-</samp>’ is more flexible.

734

</p>

735

<p>When errors are to be ignored, because of either a ‘<samp>-</samp>’ or the

736

‘<samp>-i</samp>’ flag, <code>make</code> treats an error return just like success,

737

except that it prints out a message that tells you the status code

738

the command exited with, and says that the error has been ignored.

739

</p>

740

<p>When an error happens that <code>make</code> has not been told to ignore,

741

it implies that the current target cannot be correctly remade, and neither

742

can any other that depends on it either directly or indirectly. No further

743

commands will be executed for these targets, since their preconditions

744

have not been achieved.

745

</p>

746

747

748

749

<p>Normally <code>make</code> gives up immediately in this circumstance, returning a

750

nonzero status. However, if the ‘<samp>-k</samp>’ or ‘<samp>--keep-going</samp>’

751

flag is specified, <code>make</code>

752

continues to consider the other prerequisites of the pending targets,

753

remaking them if necessary, before it gives up and returns nonzero status.

754

For example, after an error in compiling one object file, ‘<samp>make -k</samp>’

755

will continue compiling other object files even though it already knows

756

that linking them will be impossible. See section <a href="make_9.html#SEC112">Summary of Options</a>.

757

</p>

758

<p>The usual behavior assumes that your purpose is to get the specified

759

targets up to date; once <code>make</code> learns that this is impossible, it

760

might as well report the failure immediately. The ‘<samp>-k</samp>’ option says

761

that the real purpose is to test as many of the changes made in the

762

program as possible, perhaps to find several independent problems so

763

that you can correct them all before the next attempt to compile. This

764

is why Emacs' <code>compile</code> command passes the ‘<samp>-k</samp>’ flag by

765

default.

766

767

</p>

768

769

770

771

772

<p>Usually when a command fails, if it has changed the target file at all,

773

the file is corrupted and cannot be used—or at least it is not

774

completely updated. Yet the file's time stamp says that it is now up to

775

date, so the next time <code>make</code> runs, it will not try to update that

776

file. The situation is just the same as when the command is killed by a

777

signal; see section <a href="#SEC66">Interrupting or Killing <code>make</code></a>. So generally the right thing to do is to

778

delete the target file if the command fails after beginning to change

779

the file. <code>make</code> will do this if <code>.DELETE_ON_ERROR</code> appears

780

as a target. This is almost always what you want <code>make</code> to do, but

781

it is not historical practice; so for compatibility, you must explicitly

782

request it.

783

</p>

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

800

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

801

802

</tr></table>

803

<h2 class="section"> 5.6 Interrupting or Killing <code>make</code> </h2>

804

805

<p>If <code>make</code> gets a fatal signal while a command is executing, it may

806

delete the target file that the command was supposed to update. This is

807

done if the target file's last-modification time has changed since

808

<code>make</code> first checked it.

809

</p>

810

<p>The purpose of deleting the target is to make sure that it is remade from

811

scratch when <code>make</code> is next run. Why is this? Suppose you type

812

<kbd>Ctrl-c</kbd> while a compiler is running, and it has begun to write an

813

object file ‘<tt>foo.o</tt>’. The <kbd>Ctrl-c</kbd> kills the compiler, resulting

814

in an incomplete file whose last-modification time is newer than the source

815

file ‘<tt>foo.c</tt>’. But <code>make</code> also receives the <kbd>Ctrl-c</kbd> signal

816

and deletes this incomplete file. If <code>make</code> did not do this, the next

817

invocation of <code>make</code> would think that ‘<tt>foo.o</tt>’ did not require

818

updating—resulting in a strange error message from the linker when it

819

tries to link an object file half of which is missing.

820

</p>

821

822

<p>You can prevent the deletion of a target file in this way by making the

823

special target <code>.PRECIOUS</code> depend on it. Before remaking a target,

824

<code>make</code> checks to see whether it appears on the prerequisites of

825

<code>.PRECIOUS</code>, and thereby decides whether the target should be deleted

826

if a signal happens. Some reasons why you might do this are that the

827

target is updated in some atomic fashion, or exists only to record a

828

modification-time (its contents do not matter), or must exist at all

829

times to prevent other sorts of trouble.

830

</p>

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

847

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

848

849

</tr></table>

850

<h2 class="section"> 5.7 Recursive Use of <code>make</code> </h2>

851

852

<p>Recursive use of <code>make</code> means using <code>make</code> as a command in a

853

makefile. This technique is useful when you want separate makefiles for

854

various subsystems that compose a larger system. For example, suppose you

855

have a subdirectory ‘<tt>subdir</tt>’ which has its own makefile, and you would

856

like the containing directory's makefile to run <code>make</code> on the

857

subdirectory. You can do it by writing this:

858

</p>

859

<table><tr><td> </td><td><pre class="example">subsystem:

860

cd subdir && $(MAKE)

861

</pre></td></tr></table>

862

863

<p>or, equivalently, this (see section <a href="make_9.html#SEC112">Summary of Options</a>):

864

</p>

865

<table><tr><td> </td><td><pre class="example">subsystem:

866

$(MAKE) -C subdir

867

</pre></td></tr></table>

868

869

870

871

<p>You can write recursive <code>make</code> commands just by copying this example,

872

but there are many things to know about how they work and why, and about

873

how the sub-<code>make</code> relates to the top-level <code>make</code>. You may

874

also find it useful to declare targets that invoke recursive

875

<code>make</code> commands as ‘<samp>.PHONY</samp>’ (for more discussion on when

876

this is useful, see <a href="make_4.html#SEC45">Phony Targets</a>).

877

</p>

878

879

<p>For your convenience, when GNU <code>make</code> starts (after it has

880

processed any <code>-C</code> options) it sets the variable <code>CURDIR</code> to

881

the pathname of the current working directory. This value is never

882

touched by <code>make</code> again: in particular note that if you include

883

files from other directories the value of <code>CURDIR</code> does not

884

change. The value has the same precedence it would have if it were

885

set in the makefile (by default, an environment variable <code>CURDIR</code>

886

will not override this value). Note that setting this variable has no

887

impact on the operation of <code>make</code> (it does not cause <code>make</code>

888

to change its working directory, for example).

889

</p>

890

891

<tr><td align="left" valign="top"><a href="#SEC68">5.7.1 How the <code>MAKE</code> Variable Works</a></td><td>  </td><td align="left" valign="top"> The special effects of using ‘<samp>$(MAKE)</samp>’.

892

</td></tr>

893

<tr><td align="left" valign="top"><a href="#SEC69">5.7.2 Communicating Variables to a Sub-<code>make</code></a></td><td>  </td><td align="left" valign="top"> How to communicate variables to a sub-<code>make</code>.

894

</td></tr>

895

<tr><td align="left" valign="top"><a href="#SEC70">5.7.3 Communicating Options to a Sub-<code>make</code></a></td><td>  </td><td align="left" valign="top"> How to communicate options to a sub-<code>make</code>.

896

</td></tr>

897

<tr><td align="left" valign="top"><a href="#SEC71">5.7.4 The ‘<samp>--print-directory</samp>’ Option</a></td><td>  </td><td align="left" valign="top"> How the ‘<samp>-w</samp>’ or ‘<samp>--print-directory</samp>’ option

898

helps debug use of recursive <code>make</code> commands.

899

</td></tr>

900

</table>

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

918

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

919

920

</tr></table>

921

<h3 class="subsection"> 5.7.1 How the <code>MAKE</code> Variable Works </h3>

922

923

<p>Recursive <code>make</code> commands should always use the variable <code>MAKE</code>,

924

not the explicit command name ‘<samp>make</samp>’, as shown here:

925

</p>

926

<table><tr><td> </td><td><pre class="example">subsystem:

927

cd subdir && $(MAKE)

928

</pre></td></tr></table>

929

930

<p>The value of this variable is the file name with which <code>make</code> was

931

invoked. If this file name was ‘<tt>/bin/make</tt>’, then the command executed

932

is ‘<samp>cd subdir && /bin/make</samp>’. If you use a special version of

933

<code>make</code> to run the top-level makefile, the same special version will be

934

executed for recursive invocations.

935

936

</p>

937

938

<p>As a special feature, using the variable <code>MAKE</code> in the commands of

939

a rule alters the effects of the ‘<samp>-t</samp>’ (‘<samp>--touch</samp>’), ‘<samp>-n</samp>’

940

(‘<samp>--just-print</samp>’), or ‘<samp>-q</samp>’ (‘<samp>--question</samp>’) option.

941

Using the <code>MAKE</code> variable has the same effect as using a ‘<samp>+</samp>’

942

character at the beginning of the command line. See section <a href="make_9.html#SEC108">Instead of Executing the Commands</a>. This special feature

943

is only enabled if the <code>MAKE</code> variable appears directly in the

944

command script: it does not apply if the <code>MAKE</code> variable is

945

referenced through expansion of another variable. In the latter case

946

you must use the ‘<samp>+</samp>’ token to get these special effects.

947

</p>

948

<p>Consider the command ‘<samp>make -t</samp>’ in the above example. (The

949

‘<samp>-t</samp>’ option marks targets as up to date without actually running

950

any commands; see <a href="make_9.html#SEC108">Instead of Executing the Commands</a>.) Following the usual

951

definition of ‘<samp>-t</samp>’, a ‘<samp>make -t</samp>’ command in the example would

952

create a file named ‘<tt>subsystem</tt>’ and do nothing else. What you

953

really want it to do is run ‘<samp>cd subdir && make -t</samp>’; but that would

954

require executing the command, and ‘<samp>-t</samp>’ says not to execute

955

commands.

956

957

958

959

</p>

960

<p>The special feature makes this do what you want: whenever a command

961

line of a rule contains the variable <code>MAKE</code>, the flags ‘<samp>-t</samp>’,

962

‘<samp>-n</samp>’ and ‘<samp>-q</samp>’ do not apply to that line. Command lines

963

containing <code>MAKE</code> are executed normally despite the presence of a

964

flag that causes most commands not to be run. The usual

965

<code>MAKEFLAGS</code> mechanism passes the flags to the sub-<code>make</code>

966

(see section <a href="#SEC70">Communicating Options to a Sub-<code>make</code></a>), so your request to touch the files, or print the

967

commands, is propagated to the subsystem.

968

</p>

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

985

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

986

987

</tr></table>

988

<h3 class="subsection"> 5.7.2 Communicating Variables to a Sub-<code>make</code> </h3>

989

990

<p>Variable values of the top-level <code>make</code> can be passed to the

991

sub-<code>make</code> through the environment by explicit request. These

992

variables are defined in the sub-<code>make</code> as defaults, but do not

993

override what is specified in the makefile used by the sub-<code>make</code>

994

makefile unless you use the ‘<samp>-e</samp>’ switch (see section <a href="make_9.html#SEC112">Summary of Options</a>).

995

</p>

996

<p>To pass down, or <em>export</em>, a variable, <code>make</code> adds the variable

997

and its value to the environment for running each command. The

998

sub-<code>make</code>, in turn, uses the environment to initialize its table

999

of variable values. See section <a href="make_6.html#SEC85">Variables from the Environment</a>.

1000

</p>

1001

<p>Except by explicit request, <code>make</code> exports a variable only if it

1002

is either defined in the environment initially or set on the command

1003

line, and if its name consists only of letters, numbers, and underscores.

1004

Some shells cannot cope with environment variable names consisting of

1005

characters other than letters, numbers, and underscores.

1006

</p>

1007

1008

<p>The value of the <code>make</code> variable <code>SHELL</code> is not exported.

1009

Instead, the value of the <code>SHELL</code> variable from the invoking

1010

environment is passed to the sub-<code>make</code>. You can force

1011

<code>make</code> to export its value for <code>SHELL</code> by using the

1012

<code>export</code> directive, described below. See section <a href="#SEC62">Choosing the Shell</a>.

1013

</p>

1014

<p>The special variable <code>MAKEFLAGS</code> is always exported (unless you

1015

unexport it). <code>MAKEFILES</code> is exported if you set it to anything.

1016

</p>

1017

<p><code>make</code> automatically passes down variable values that were defined

1018

on the command line, by putting them in the <code>MAKEFLAGS</code> variable.

1019

See section <a href="#SEC70">Communicating Options to a Sub-<code>make</code></a>.

1020

</p>

1021

<p>Variables are <em>not</em> normally passed down if they were created by

1022

default by <code>make</code> (see section <a href="make_10.html#SEC116">Variables Used by Implicit Rules</a>). The sub-<code>make</code> will define these for

1023

itself.

1024

</p>

1025

1026

<p>If you want to export specific variables to a sub-<code>make</code>, use the

1027

<code>export</code> directive, like this:

1028

</p>

1029

<table><tr><td> </td><td><pre class="example">export <var>variable</var> …

1030

</pre></td></tr></table>

1031

1032

1033

<p>If you want to <em>prevent</em> a variable from being exported, use the

1034

<code>unexport</code> directive, like this:

1035

</p>

1036

<table><tr><td> </td><td><pre class="example">unexport <var>variable</var> …

1037

</pre></td></tr></table>

1038

1039

<p>In both of these forms, the arguments to <code>export</code> and

1040

<code>unexport</code> are expanded, and so could be variables or functions

1041

which expand to a (list of) variable names to be (un)exported.

1042

</p>

1043

<p>As a convenience, you can define a variable and export it at the same

1044

time by doing:

1045

</p>

1046

<table><tr><td> </td><td><pre class="example">export <var>variable</var> = value

1047

</pre></td></tr></table>

1048

1049

<p>has the same result as:

1050

</p>

1051

<table><tr><td> </td><td><pre class="example"><var>variable</var> = value

1052

export <var>variable</var>

1053

</pre></td></tr></table>

1054

1055

<p>and

1056

</p>

1057

<table><tr><td> </td><td><pre class="example">export <var>variable</var> := value

1058

</pre></td></tr></table>

1059

1060

<p>has the same result as:

1061

</p>

1062

<table><tr><td> </td><td><pre class="example"><var>variable</var> := value

1063

export <var>variable</var>

1064

</pre></td></tr></table>

1065

1066

<p>Likewise,

1067

</p>

1068

<table><tr><td> </td><td><pre class="example">export <var>variable</var> += value

1069

</pre></td></tr></table>

1070

1071

<p>is just like:

1072

</p>

1073

<table><tr><td> </td><td><pre class="example"><var>variable</var> += value

1074

export <var>variable</var>

1075

</pre></td></tr></table>

1076

1077

<p>See section <a href="make_6.html#SEC82">Appending More Text to Variables</a>.

1078

</p>

1079

<p>You may notice that the <code>export</code> and <code>unexport</code> directives

1080

work in <code>make</code> in the same way they work in the shell, <code>sh</code>.

1081

</p>

1082

<p>If you want all variables to be exported by default, you can use

1083

<code>export</code> by itself:

1084

</p>

1085

<table><tr><td> </td><td><pre class="example">export

1086

</pre></td></tr></table>

1087

1088

<p>This tells <code>make</code> that variables which are not explicitly mentioned

1089

in an <code>export</code> or <code>unexport</code> directive should be exported.

1090

Any variable given in an <code>unexport</code> directive will still <em>not</em>

1091

be exported. If you use <code>export</code> by itself to export variables by

1092

default, variables whose names contain characters other than

1093

alphanumerics and underscores will not be exported unless specifically

1094

mentioned in an <code>export</code> directive.

1095

</p>

1096

1097

<p>The behavior elicited by an <code>export</code> directive by itself was the

1098

default in older versions of GNU <code>make</code>. If your makefiles depend

1099

on this behavior and you want to be compatible with old versions of

1100

<code>make</code>, you can write a rule for the special target

1101

<code>.EXPORT_ALL_VARIABLES</code> instead of using the <code>export</code> directive.

1102

This will be ignored by old <code>make</code>s, while the <code>export</code>

1103

directive will cause a syntax error.

1104

1105

</p>

1106

<p>Likewise, you can use <code>unexport</code> by itself to tell <code>make</code>

1107

<em>not</em> to export variables by default. Since this is the default

1108

behavior, you would only need to do this if <code>export</code> had been used

1109

by itself earlier (in an included makefile, perhaps). You

1110

<strong>cannot</strong> use <code>export</code> and <code>unexport</code> by themselves to

1111

have variables exported for some commands and not for others. The last

1112

<code>export</code> or <code>unexport</code> directive that appears by itself

1113

determines the behavior for the entire run of <code>make</code>.

1114

</p>

1115

1116

1117

<p>As a special feature, the variable <code>MAKELEVEL</code> is changed when it

1118

is passed down from level to level. This variable's value is a string

1119

which is the depth of the level as a decimal number. The value is

1120

‘<samp>0</samp>’ for the top-level <code>make</code>; ‘<samp>1</samp>’ for a sub-<code>make</code>,

1121

‘<samp>2</samp>’ for a sub-sub-<code>make</code>, and so on. The incrementation

1122

happens when <code>make</code> sets up the environment for a command.

1123

</p>

1124

<p>The main use of <code>MAKELEVEL</code> is to test it in a conditional

1125

directive (see section <a href="make_7.html#SEC88">Conditional Parts of Makefiles</a>); this

1126

way you can write a makefile that behaves one way if run recursively and

1127

another way if run directly by you.

1128

</p>

1129

1130

<p>You can use the variable <code>MAKEFILES</code> to cause all sub-<code>make</code>

1131

commands to use additional makefiles. The value of <code>MAKEFILES</code> is

1132

a whitespace-separated list of file names. This variable, if defined in

1133

the outer-level makefile, is passed down through the environment; then

1134

it serves as a list of extra makefiles for the sub-<code>make</code> to read

1135

before the usual or specified ones. See section <a href="make_3.html#SEC17">The Variable <code>MAKEFILES</code></a>.

1136

</p>

1137

1138

1139

1140

1141

1142

1143

1144

1145

1146

1147

1148

1149

1150

1151

1152

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1153

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

1154

1155

</tr></table>

1156

<h3 class="subsection"> 5.7.3 Communicating Options to a Sub-<code>make</code> </h3>

1157

1158

<p>Flags such as ‘<samp>-s</samp>’ and ‘<samp>-k</samp>’ are passed automatically to the

1159

sub-<code>make</code> through the variable <code>MAKEFLAGS</code>. This variable is

1160

set up automatically by <code>make</code> to contain the flag letters that

1161

<code>make</code> received. Thus, if you do ‘<samp>make -ks</samp>’ then

1162

<code>MAKEFLAGS</code> gets the value ‘<samp>ks</samp>’.

1163

</p>

1164

<p>As a consequence, every sub-<code>make</code> gets a value for <code>MAKEFLAGS</code>

1165

in its environment. In response, it takes the flags from that value and

1166

processes them as if they had been given as arguments.

1167

See section <a href="make_9.html#SEC112">Summary of Options</a>.

1168

</p>

1169

1170

1171

1172

<p>Likewise variables defined on the command line are passed to the

1173

sub-<code>make</code> through <code>MAKEFLAGS</code>. Words in the value of

1174

<code>MAKEFLAGS</code> that contain ‘<samp>=</samp>’, <code>make</code> treats as variable

1175

definitions just as if they appeared on the command line.

1176

See section <a href="make_9.html#SEC110">Overriding Variables</a>.

1177

</p>

1178

1179

1180

1181

1182

1183

1184

1185

1186

1187

1188

1189

1190

1191

1192

<p>The options ‘<samp>-C</samp>’, ‘<samp>-f</samp>’, ‘<samp>-o</samp>’, and ‘<samp>-W</samp>’ are not put

1193

into <code>MAKEFLAGS</code>; these options are not passed down.

1194

</p>

1195

1196

1197

1198

1199

<p>The ‘<samp>-j</samp>’ option is a special case (see section <a href="#SEC64">Parallel Execution</a>).

1200

If you set it to some numeric value ‘<samp>N</samp>’ and your operating system

1201

supports it (most any UNIX system will; others typically won't), the

1202

parent <code>make</code> and all the sub-<code>make</code>s will communicate to

1203

ensure that there are only ‘<samp>N</samp>’ jobs running at the same time

1204

between them all. Note that any job that is marked recursive

1205

(see section <a href="make_9.html#SEC108">Instead of Executing the Commands</a>)

1206

doesn't count against the total jobs (otherwise we could get ‘<samp>N</samp>’

1207

sub-<code>make</code>s running and have no slots left over for any real work!)

1208

</p>

1209

<p>If your operating system doesn't support the above communication, then

1210

‘<samp>-j 1</samp>’ is always put into <code>MAKEFLAGS</code> instead of the value you

1211

specified. This is because if the ‘<samp>-j</samp>’ option were passed down

1212

to sub-<code>make</code>s, you would get many more jobs running in parallel

1213

than you asked for. If you give ‘<samp>-j</samp>’ with no numeric argument,

1214

meaning to run as many jobs as possible in parallel, this is passed

1215

down, since multiple infinities are no more than one.

1216

</p>

1217

<p>If you do not want to pass the other flags down, you must change the

1218

value of <code>MAKEFLAGS</code>, like this:

1219

</p>

1220

<table><tr><td> </td><td><pre class="example">subsystem:

1221

cd subdir && $(MAKE) MAKEFLAGS=

1222

</pre></td></tr></table>

1223

1224

1225

<p>The command line variable definitions really appear in the variable

1226

<code>MAKEOVERRIDES</code>, and <code>MAKEFLAGS</code> contains a reference to this

1227

variable. If you do want to pass flags down normally, but don't want to

1228

pass down the command line variable definitions, you can reset

1229

<code>MAKEOVERRIDES</code> to empty, like this:

1230

</p>

1231

<table><tr><td> </td><td><pre class="example">MAKEOVERRIDES =

1232

</pre></td></tr></table>

1233

1234

1235

1236

<p>This is not usually useful to do. However, some systems have a small

1237

fixed limit on the size of the environment, and putting so much

1238

information into the value of <code>MAKEFLAGS</code> can exceed it. If you

1239

see the error message ‘<samp>Arg list too long</samp>’, this may be the problem.

1240

1241

1242

(For strict compliance with POSIX.2, changing <code>MAKEOVERRIDES</code> does

1243

not affect <code>MAKEFLAGS</code> if the special target ‘<samp>.POSIX</samp>’ appears

1244

in the makefile. You probably do not care about this.)

1245

</p>

1246

1247

<p>A similar variable <code>MFLAGS</code> exists also, for historical

1248

compatibility. It has the same value as <code>MAKEFLAGS</code> except that it

1249

does not contain the command line variable definitions, and it always

1250

begins with a hyphen unless it is empty (<code>MAKEFLAGS</code> begins with a

1251

hyphen only when it begins with an option that has no single-letter

1252

version, such as ‘<samp>--warn-undefined-variables</samp>’). <code>MFLAGS</code> was

1253

traditionally used explicitly in the recursive <code>make</code> command, like

1254

this:

1255

</p>

1256

<table><tr><td> </td><td><pre class="example">subsystem:

1257

cd subdir && $(MAKE) $(MFLAGS)

1258

</pre></td></tr></table>

1259

1260

<p>but now <code>MAKEFLAGS</code> makes this usage redundant. If you want your

1261

makefiles to be compatible with old <code>make</code> programs, use this

1262

technique; it will work fine with more modern <code>make</code> versions too.

1263

</p>

1264

1265

1266

1267

1268

<p>The <code>MAKEFLAGS</code> variable can also be useful if you want to have

1269

certain options, such as ‘<samp>-k</samp>’ (see section <a href="make_9.html#SEC112">Summary of Options</a>), set each time you run <code>make</code>. You simply put a value for

1270

<code>MAKEFLAGS</code> in your environment. You can also set <code>MAKEFLAGS</code> in

1271

a makefile, to specify additional flags that should also be in effect for

1272

that makefile. (Note that you cannot use <code>MFLAGS</code> this way. That

1273

variable is set only for compatibility; <code>make</code> does not interpret a

1274

value you set for it in any way.)

1275

</p>

1276

<p>When <code>make</code> interprets the value of <code>MAKEFLAGS</code> (either from the

1277

environment or from a makefile), it first prepends a hyphen if the value

1278

does not already begin with one. Then it chops the value into words

1279

separated by blanks, and parses these words as if they were options given

1280

on the command line (except that ‘<samp>-C</samp>’, ‘<samp>-f</samp>’, ‘<samp>-h</samp>’,

1281

‘<samp>-o</samp>’, ‘<samp>-W</samp>’, and their long-named versions are ignored; and there

1282

is no error for an invalid option).

1283

</p>

1284

<p>If you do put <code>MAKEFLAGS</code> in your environment, you should be sure not

1285

to include any options that will drastically affect the actions of

1286

<code>make</code> and undermine the purpose of makefiles and of <code>make</code>

1287

itself. For instance, the ‘<samp>-t</samp>’, ‘<samp>-n</samp>’, and ‘<samp>-q</samp>’ options, if

1288

put in one of these variables, could have disastrous consequences and would

1289

certainly have at least surprising and probably annoying effects.

1290

</p>

1291

1292

1293

1294

1295

1296

1297

1298

1299

1300

1301

1302

1303

1304

1305

1306

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1307

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

1308

1309

</tr></table>

1310

<h3 class="subsection"> 5.7.4 The ‘<samp>--print-directory</samp>’ Option </h3>

1311

1312

<p>If you use several levels of recursive <code>make</code> invocations, the

1313

‘<samp>-w</samp>’ or ‘<samp>--print-directory</samp>’ option can make the output a

1314

lot easier to understand by showing each directory as <code>make</code>

1315

starts processing it and as <code>make</code> finishes processing it. For

1316

example, if ‘<samp>make -w</samp>’ is run in the directory ‘<tt>/u/gnu/make</tt>’,

1317

<code>make</code> will print a line of the form:

1318

</p>

1319

<table><tr><td> </td><td><pre class="example">make: Entering directory `/u/gnu/make'.

1320

</pre></td></tr></table>

1321

1322

<p>before doing anything else, and a line of the form:

1323

</p>

1324

<table><tr><td> </td><td><pre class="example">make: Leaving directory `/u/gnu/make'.

1325

</pre></td></tr></table>

1326

1327

<p>when processing is completed.

1328

</p>

1329

1330

1331

1332

1333

1334

1335

1336

1337

1338

1339

<p>Normally, you do not need to specify this option because ‘<samp>make</samp>’

1340

does it for you: ‘<samp>-w</samp>’ is turned on automatically when you use the

1341

‘<samp>-C</samp>’ option, and in sub-<code>make</code>s. <code>make</code> will not

1342

automatically turn on ‘<samp>-w</samp>’ if you also use ‘<samp>-s</samp>’, which says to

1343

be silent, or if you use ‘<samp>--no-print-directory</samp>’ to explicitly

1344

disable it.

1345

</p>

1346

1347

1348

1349

1350

1351

1352

1353

1354

1355

1356

1357

1358

1359

1360

1361

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1362

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

1363

1364

</tr></table>

1365

<h2 class="section"> 5.8 Defining Canned Command Sequences </h2>

1366

1367

<p>When the same sequence of commands is useful in making various targets, you

1368

can define it as a canned sequence with the <code>define</code> directive, and

1369

refer to the canned sequence from the rules for those targets. The canned

1370

sequence is actually a variable, so the name must not conflict with other

1371

variable names.

1372

</p>

1373

<p>Here is an example of defining a canned sequence of commands:

1374

</p>

1375

<table><tr><td> </td><td><pre class="example">define run-yacc

1376

yacc $(firstword $^)

1377

mv y.tab.c $@

1378

endef

1379

</pre></td></tr></table>

1380

1381

1382

<p>Here <code>run-yacc</code> is the name of the variable being defined;

1383

<code>endef</code> marks the end of the definition; the lines in between are the

1384

commands. The <code>define</code> directive does not expand variable references

1385

and function calls in the canned sequence; the ‘<samp>$</samp>’ characters,

1386

parentheses, variable names, and so on, all become part of the value of the

1387

variable you are defining.

1388

See section <a href="make_6.html#SEC84">Defining Variables Verbatim</a>,

1389

for a complete explanation of <code>define</code>.

1390

</p>

1391

<p>The first command in this example runs Yacc on the first prerequisite of

1392

whichever rule uses the canned sequence. The output file from Yacc is

1393

always named ‘<tt>y.tab.c</tt>’. The second command moves the output to the

1394

rule's target file name.

1395

</p>

1396

<p>To use the canned sequence, substitute the variable into the commands of a

1397

rule. You can substitute it like any other variable

1398

(see section <a href="make_6.html#SEC75">Basics of Variable References</a>).

1399

Because variables defined by <code>define</code> are recursively expanded

1400

variables, all the variable references you wrote inside the <code>define</code>

1401

are expanded now. For example:

1402

</p>

1403

<table><tr><td> </td><td><pre class="example">foo.c : foo.y

1404

$(run-yacc)

1405

</pre></td></tr></table>

1406

1407

<p>‘<samp>foo.y</samp>’ will be substituted for the variable ‘<samp>$^</samp>’ when it occurs in

1408

<code>run-yacc</code>'s value, and ‘<samp>foo.c</samp>’ for ‘<samp>$@</samp>’.

1409

</p>

1410

<p>This is a realistic example, but this particular one is not needed in

1411

practice because <code>make</code> has an implicit rule to figure out these

1412

commands based on the file names involved

1413

(see section <a href="make_10.html#SEC113">Using Implicit Rules</a>).

1414

</p>

1415

1416

1417

1418

<p>In command execution, each line of a canned sequence is treated just as

1419

if the line appeared on its own in the rule, preceded by a tab. In

1420

particular, <code>make</code> invokes a separate subshell for each line. You

1421

can use the special prefix characters that affect command lines

1422

(‘<samp>@</samp>’, ‘<samp>-</samp>’, and ‘<samp>+</samp>’) on each line of a canned sequence.

1423

See section <a href="#SEC56">Writing the Commands in Rules</a>.

1424

For example, using this canned sequence:

1425

</p>

1426

<table><tr><td> </td><td><pre class="example">define frobnicate

1427

@echo "frobnicating target $@"

1428

frob-step-1 $< -o $@-step-1

1429

frob-step-2 $@-step-1 -o $@

1430

endef

1431

</pre></td></tr></table>

1432

1433

<p><code>make</code> will not echo the first line, the <code>echo</code> command.

1434

But it <em>will</em> echo the following two command lines.

1435

</p>

1436

<p>On the other hand, prefix characters on the command line that refers to

1437

a canned sequence apply to every line in the sequence. So the rule:

1438

</p>

1439

<table><tr><td> </td><td><pre class="example">frob.out: frob.in

1440

@$(frobnicate)

1441

</pre></td></tr></table>

1442

1443

<p>does not echo <em>any</em> commands.

1444

(See section <a href="#SEC60">Command Echoing</a>, for a full explanation of ‘<samp>@</samp>’.)

1445

</p>

1446

1447

1448

1449

1450

1451

1452

1453

1454

1455

1456

1457

1458

1459

1460

1461

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1462

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

1463

1464

</tr></table>

1465

<h2 class="section"> 5.9 Using Empty Commands </h2>

1466

1467

<p>It is sometimes useful to define commands which do nothing. This is done

1468

simply by giving a command that consists of nothing but whitespace. For

1469

example:

1470

</p>

1471

<table><tr><td> </td><td><pre class="example">target: ;

1472

</pre></td></tr></table>

1473

1474

<p>defines an empty command string for ‘<tt>target</tt>’. You could also use a

1475

line beginning with a tab character to define an empty command string,

1476

but this would be confusing because such a line looks empty.

1477

</p>

1478

1479

<p>You may be wondering why you would want to define a command string that

1480

does nothing. The only reason this is useful is to prevent a target

1481

from getting implicit commands (from implicit rules or the

1482

<code>.DEFAULT</code> special target; see section <a href="make_10.html#SEC113">Using Implicit Rules</a> and

1483

see section <a href="make_10.html#SEC125">Defining Last-Resort Default Rules</a>).

1484

</p>

1485

1486

<p>You may be inclined to define empty command strings for targets that are

1487

not actual files, but only exist so that their prerequisites can be

1488

remade. However, this is not the best way to do that, because the

1489

prerequisites may not be remade properly if the target file actually does exist.

1490

See section <a href="make_4.html#SEC45">Phony Targets</a>, for a better way to do this.

1491

</p>

1492

1493

1494

1495

1496

1497

1498

1499

1500

1501

1502

<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1503

<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>

1504

1505

</tr></table>

1506

<p>

1507

1508

This document was generated by <em>Manoj Srivastava</em> on <em>August, 17 2009</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.78</em></a>.

1509

</font>

1510

<br>

1511

1512

</p>

1513

</body>

1514

</html>