/usr/share/doc/make-doc/make.html/Recipes.html is in make-doc 4.1-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the GNU make utility, which determines
automatically which pieces of a large program need to be recompiled,
and issues the commands to recompile them.
This is Edition 0.73, last updated 15 January 2016,
of The GNU Make Manual, for GNU make version 4.1.
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007,
2008, 2009, 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below. A copy of the
license is included in the section entitled "GNU Free Documentation
License."
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 6.0, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU make: Recipes</title>
<meta name="description" content="GNU make: Recipes">
<meta name="keywords" content="GNU make: Recipes">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="Using-Variables.html#Using-Variables" rel="next" title="Using Variables">
<link href="Rules.html#Automatic-Prerequisites" rel="prev" title="Automatic Prerequisites">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space: nowrap}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: serif; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<a name="Recipes"></a>
<div class="header">
<p>
Next: <a href="Using-Variables.html#Using-Variables" accesskey="n" rel="next">Using Variables</a>, Previous: <a href="Rules.html#Rules" accesskey="p" rel="prev">Rules</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Writing-Recipes-in-Rules"></a>
<h2 class="chapter">5 Writing Recipes in Rules</h2>
<a name="index-recipes-1"></a>
<a name="index-recipes_002c-how-to-write"></a>
<a name="index-writing-recipes"></a>
<p>The recipe of a rule consists of one or more shell command lines to
be executed, one at a time, in the order they appear. Typically, the
result of executing these commands is that the target of the rule is
brought up to date.
</p>
<p>Users use many different shell programs, but recipes in makefiles are
always interpreted by <samp>/bin/sh</samp> unless the makefile specifies
otherwise. See <a href="#Execution">Recipe Execution</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Recipe-Syntax" accesskey="1">Recipe Syntax</a>:</td><td> </td><td align="left" valign="top">Recipe syntax features and pitfalls.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Echoing" accesskey="2">Echoing</a>:</td><td> </td><td align="left" valign="top">How to control when recipes are echoed.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Execution" accesskey="3">Execution</a>:</td><td> </td><td align="left" valign="top">How recipes are executed.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Parallel" accesskey="4">Parallel</a>:</td><td> </td><td align="left" valign="top">How recipes can be executed in parallel.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Errors" accesskey="5">Errors</a>:</td><td> </td><td align="left" valign="top">What happens after a recipe execution error.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Interrupts" accesskey="6">Interrupts</a>:</td><td> </td><td align="left" valign="top">What happens when a recipe is interrupted.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Recursion" accesskey="7">Recursion</a>:</td><td> </td><td align="left" valign="top">Invoking <code>make</code> from makefiles.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Canned-Recipes" accesskey="8">Canned Recipes</a>:</td><td> </td><td align="left" valign="top">Defining canned recipes.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Empty-Recipes" accesskey="9">Empty Recipes</a>:</td><td> </td><td align="left" valign="top">Defining useful, do-nothing recipes.
</td></tr>
</table>
<hr>
<a name="Recipe-Syntax"></a>
<div class="header">
<p>
Next: <a href="#Echoing" accesskey="n" rel="next">Echoing</a>, Previous: <a href="#Recipes" accesskey="p" rel="prev">Recipes</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Recipe-Syntax-1"></a>
<h3 class="section">5.1 Recipe Syntax</h3>
<a name="index-recipe-syntax"></a>
<a name="index-syntax-of-recipe"></a>
<p>Makefiles have the unusual property that there are really two distinct
syntaxes in one file. Most of the makefile uses <code>make</code> syntax
(see <a href="Makefiles.html#Makefiles">Writing Makefiles</a>). However, recipes are meant
to be interpreted by the shell and so they are written using shell
syntax. The <code>make</code> program does not try to understand shell
syntax: it performs only a very few specific translations on the
content of the recipe before handing it to the shell.
</p>
<p>Each line in the recipe must start with a tab (or the first character
in the value of the <code>.RECIPEPREFIX</code> variable; see <a href="Using-Variables.html#Special-Variables">Special Variables</a>), except that the first recipe line may be attached to the
target-and-prerequisites line with a semicolon in between. <em>Any</em>
line in the makefile that begins with a tab and appears in a “rule
context” (that is, after a rule has been started until another rule
or variable definition) will be considered part of a recipe for that
rule. Blank lines and lines of just comments may appear among the
recipe lines; they are ignored.
</p>
<p>Some consequences of these rules include:
</p>
<ul>
<li> A blank line that begins with a tab is not blank: it’s an empty
recipe (see <a href="#Empty-Recipes">Empty Recipes</a>).
</li><li> <a name="index-comments_002c-in-recipes"></a>
<a name="index-recipes_002c-comments-in"></a>
<a name="index-_0023-_0028comments_0029_002c-in-recipes"></a>
A comment in a recipe is not a <code>make</code> comment; it will be
passed to the shell as-is. Whether the shell treats it as a comment
or not depends on your shell.
</li><li> A variable definition in a “rule context” which is indented by a tab
as the first character on the line, will be considered part of a
recipe, not a <code>make</code> variable definition, and passed to the
shell.
</li><li> A conditional expression (<code>ifdef</code>, <code>ifeq</code>,
etc. see <a href="Conditionals.html#Conditional-Syntax">Syntax of Conditionals</a>) in a “rule
context” which is indented by a tab as the first character on the
line, will be considered part of a recipe and be passed to the shell.
</li></ul>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Splitting-Recipe-Lines" accesskey="1">Splitting Recipe Lines</a>:</td><td> </td><td align="left" valign="top">Breaking long recipe lines for readability.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Variables-in-Recipes" accesskey="2">Variables in Recipes</a>:</td><td> </td><td align="left" valign="top">Using <code>make</code> variables in recipes.
</td></tr>
</table>
<hr>
<a name="Splitting-Recipe-Lines"></a>
<div class="header">
<p>
Next: <a href="#Variables-in-Recipes" accesskey="n" rel="next">Variables in Recipes</a>, Previous: <a href="#Recipe-Syntax" accesskey="p" rel="prev">Recipe Syntax</a>, Up: <a href="#Recipe-Syntax" accesskey="u" rel="up">Recipe Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Splitting-Recipe-Lines-1"></a>
<h4 class="subsection">5.1.1 Splitting Recipe Lines</h4>
<a name="index-recipes_002c-splitting"></a>
<a name="index-splitting-recipes"></a>
<a name="index-recipes_002c-backslash-_0028_005c_0029-in"></a>
<a name="index-recipes_002c-quoting-newlines-in"></a>
<a name="index-backslash-_0028_005c_0029_002c-in-recipes"></a>
<a name="index-_005c-_0028backslash_0029_002c-in-recipes"></a>
<a name="index-quoting-newline_002c-in-recipes"></a>
<a name="index-newline_002c-quoting_002c-in-recipes"></a>
<p>One of the few ways in which <code>make</code> does interpret recipes is
checking for a backslash just before the newline. As in normal
makefile syntax, a single logical recipe line can be split into
multiple physical lines in the makefile by placing a backslash before
each newline. A sequence of lines like this is considered a single
recipe line, and one instance of the shell will be invoked to run it.
</p>
<p>However, in contrast to how they are treated in other places in a
makefile (see <a href="Makefiles.html#Splitting-Lines">Splitting Long Lines</a>),
backslash/newline pairs are <em>not</em> removed from the recipe. Both
the backslash and the newline characters are preserved and passed to
the shell. How the backslash/newline is interpreted depends on your
shell. If the first character of the next line after the
backslash/newline is the recipe prefix character (a tab by default;
see <a href="Using-Variables.html#Special-Variables">Special Variables</a>), then that character (and only that
character) is removed. Whitespace is never added to the recipe.
</p>
<p>For example, the recipe for the all target in this makefile:
</p>
<div class="example">
<pre class="example">all :
@echo no\
space
@echo no\
space
@echo one \
space
@echo one\
space
</pre></div>
<p>consists of four separate shell commands where the output is:
</p>
<div class="example">
<pre class="example">nospace
nospace
one space
one space
</pre></div>
<p>As a more complex example, this makefile:
</p>
<div class="example">
<pre class="example">all : ; @echo 'hello \
world' ; echo "hello \
world"
</pre></div>
<p>will invoke one shell with a command of:
</p>
<div class="example">
<pre class="example">echo 'hello \
world' ; echo "hello \
world"
</pre></div>
<p>which, according to shell quoting rules, will yield the following output:
</p>
<div class="example">
<pre class="example">hello \
world
hello world
</pre></div>
<p>Notice how the backslash/newline pair was removed inside the string
quoted with double quotes (<code>"…"</code>), but not from the string
quoted with single quotes (<code>'…'</code>). This is the way the
default shell (<samp>/bin/sh</samp>) handles backslash/newline pairs. If
you specify a different shell in your makefiles it may treat them
differently.
</p>
<p>Sometimes you want to split a long line inside of single quotes, but
you don’t want the backslash/newline to appear in the quoted content.
This is often the case when passing scripts to languages such as Perl,
where extraneous backslashes inside the script can change its meaning
or even be a syntax error. One simple way of handling this is to
place the quoted string, or even the entire command, into a
<code>make</code> variable then use the variable in the recipe. In this
situation the newline quoting rules for makefiles will be used, and
the backslash/newline will be removed. If we rewrite our example
above using this method:
</p>
<div class="example">
<pre class="example">HELLO = 'hello \
world'
all : ; @echo $(HELLO)
</pre></div>
<p>we will get output like this:
</p>
<div class="example">
<pre class="example">hello world
</pre></div>
<p>If you like, you can also use target-specific variables
(see <a href="Using-Variables.html#Target_002dspecific">Target-specific Variable Values</a>) to obtain
a tighter correspondence between the variable and the recipe that
uses it.
</p>
<hr>
<a name="Variables-in-Recipes"></a>
<div class="header">
<p>
Previous: <a href="#Splitting-Recipe-Lines" accesskey="p" rel="prev">Splitting Recipe Lines</a>, Up: <a href="#Recipe-Syntax" accesskey="u" rel="up">Recipe Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Using-Variables-in-Recipes"></a>
<h4 class="subsection">5.1.2 Using Variables in Recipes</h4>
<a name="index-variable-references-in-recipes"></a>
<a name="index-recipes_002c-using-variables-in"></a>
<p>The other way in which <code>make</code> processes recipes is by expanding
any variable references in them (see <a href="Using-Variables.html#Reference">Basics of Variable
References</a>). This occurs after make has finished reading all the
makefiles and the target is determined to be out of date; so, the
recipes for targets which are not rebuilt are never expanded.
</p>
<p>Variable and function references in recipes have identical syntax and
semantics to references elsewhere in the makefile. They also have the
same quoting rules: if you want a dollar sign to appear in your
recipe, you must double it (‘<samp>$$</samp>’). For shells like the default
shell, that use dollar signs to introduce variables, it’s important to
keep clear in your mind whether the variable you want to reference is
a <code>make</code> variable (use a single dollar sign) or a shell variable
(use two dollar signs). For example:
</p>
<div class="example">
<pre class="example">LIST = one two three
all:
for i in $(LIST); do \
echo $$i; \
done
</pre></div>
<p>results in the following command being passed to the shell:
</p>
<div class="example">
<pre class="example">for i in one two three; do \
echo $i; \
done
</pre></div>
<p>which generates the expected result:
</p>
<div class="example">
<pre class="example">one
two
three
</pre></div>
<hr>
<a name="Echoing"></a>
<div class="header">
<p>
Next: <a href="#Execution" accesskey="n" rel="next">Execution</a>, Previous: <a href="#Recipe-Syntax" accesskey="p" rel="prev">Recipe Syntax</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Recipe-Echoing"></a>
<h3 class="section">5.2 Recipe Echoing</h3>
<a name="index-echoing-of-recipes"></a>
<a name="index-silent-operation"></a>
<a name="index-_0040-_0028in-recipes_0029"></a>
<a name="index-recipes_002c-echoing"></a>
<a name="index-printing-of-recipes"></a>
<p>Normally <code>make</code> prints each line of the recipe before it is
executed. We call this <em>echoing</em> because it gives the appearance
that you are typing the lines yourself.
</p>
<p>When a line starts with ‘<samp>@</samp>’, the echoing of that line is suppressed.
The ‘<samp>@</samp>’ is discarded before the line is passed to the shell.
Typically you would use this for a command whose only effect is to print
something, such as an <code>echo</code> command to indicate progress through
the makefile:
</p>
<div class="example">
<pre class="example">@echo About to make distribution files
</pre></div>
<a name="index-_002dn"></a>
<a name="index-_002d_002djust_002dprint"></a>
<a name="index-_002d_002ddry_002drun"></a>
<a name="index-_002d_002drecon"></a>
<p>When <code>make</code> is given the flag ‘<samp>-n</samp>’ or ‘<samp>--just-print</samp>’ it
only echoes most recipes, without executing them. See <a href="Running.html#Options-Summary">Summary of Options</a>. In this case even the recipe lines
starting with ‘<samp>@</samp>’ are printed. This flag is useful for finding
out which recipes <code>make</code> thinks are necessary without actually
doing them.
</p>
<a name="index-_002ds"></a>
<a name="index-_002d_002dsilent"></a>
<a name="index-_002d_002dquiet"></a>
<a name="index-_002eSILENT-1"></a>
<p>The ‘<samp>-s</samp>’ or ‘<samp>--silent</samp>’
flag to <code>make</code> prevents all echoing, as if all recipes
started with ‘<samp>@</samp>’. A rule in the makefile for the special target
<code>.SILENT</code> without prerequisites has the same effect
(see <a href="Rules.html#Special-Targets">Special Built-in Target Names</a>).
<code>.SILENT</code> is essentially obsolete since ‘<samp>@</samp>’ is more flexible.
</p>
<hr>
<a name="Execution"></a>
<div class="header">
<p>
Next: <a href="#Parallel" accesskey="n" rel="next">Parallel</a>, Previous: <a href="#Echoing" accesskey="p" rel="prev">Echoing</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Recipe-Execution"></a>
<h3 class="section">5.3 Recipe Execution</h3>
<a name="index-recipe_002c-execution"></a>
<a name="index-execution_002c-of-recipes"></a>
<a name="index-SHELL-_0028recipe-execution_0029"></a>
<p>When it is time to execute recipes to update a target, they are
executed by invoking a new sub-shell for each line of the recipe,
unless the <code>.ONESHELL</code> special target is in effect
(see <a href="#One-Shell">Using One Shell</a>) (In practice, <code>make</code> may
take shortcuts that do not affect the results.)
</p>
<a name="index-cd-_0028shell-command_0029"></a>
<a name="index-shell-variables_002c-setting-in-recipes"></a>
<a name="index-recipes-setting-shell-variables"></a>
<p><strong>Please note:</strong> this implies that setting shell variables and
invoking shell commands such as <code>cd</code> that set a context local to
each process will not affect the following lines in the recipe.<a name="DOCF2" href="#FOOT2"><sup>2</sup></a> If you want to use <code>cd</code> to affect the next statement,
put both statements in a single recipe line. Then <code>make</code> will
invoke one shell to run the entire line, and the shell will execute
the statements in sequence. For example:
</p>
<div class="example">
<pre class="example">foo : bar/lose
cd $(@D) && gobble $(@F) > ../$@
</pre></div>
<p>Here we use the shell AND operator (<code>&&</code>) so that if the
<code>cd</code> command fails, the script will fail without trying to invoke
the <code>gobble</code> command in the wrong directory, which could cause
problems (in this case it would certainly cause <samp>../foo</samp> to be
truncated, at least).
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#One-Shell" accesskey="1">One Shell</a>:</td><td> </td><td align="left" valign="top">One shell for all lines in a recipe.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Choosing-the-Shell" accesskey="2">Choosing the Shell</a>:</td><td> </td><td align="left" valign="top">How <code>make</code> chooses the shell used
to run recipes.
</td></tr>
</table>
<hr>
<a name="One-Shell"></a>
<div class="header">
<p>
Next: <a href="#Choosing-the-Shell" accesskey="n" rel="next">Choosing the Shell</a>, Previous: <a href="#Execution" accesskey="p" rel="prev">Execution</a>, Up: <a href="#Execution" accesskey="u" rel="up">Execution</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Using-One-Shell"></a>
<h4 class="subsection">5.3.1 Using One Shell</h4>
<a name="index-recipe-lines_002c-single-shell"></a>
<a name="index-_002eONESHELL_002c-use-of"></a>
<a name="index-_002eONESHELL-1"></a>
<p>Sometimes you would prefer that all the lines in the recipe be passed
to a single invocation of the shell. There are generally two
situations where this is useful: first, it can improve performance in
makefiles where recipes consist of many command lines, by avoiding
extra processes. Second, you might want newlines to be included in
your recipe command (for example perhaps you are using a very
different interpreter as your <code>SHELL</code>). If the <code>.ONESHELL</code>
special target appears anywhere in the makefile then <em>all</em>
recipe lines for each target will be provided to a single invocation
of the shell. Newlines between recipe lines will be preserved. For
example:
</p>
<div class="example">
<pre class="example">.ONESHELL:
foo : bar/lose
cd $(@D)
gobble $(@F) > ../$@
</pre></div>
<p>would now work as expected even though the commands are on different
recipe lines.
</p>
<p>If <code>.ONESHELL</code> is provided, then only the first line of the
recipe will be checked for the special prefix characters (‘<samp>@</samp>’,
‘<samp>-</samp>’, and ‘<samp>+</samp>’). Subsequent lines will include the special
characters in the recipe line when the <code>SHELL</code> is invoked. If
you want your recipe to start with one of these special characters
you’ll need to arrange for them to not be the first characters on the
first line, perhaps by adding a comment or similar. For example, this
would be a syntax error in Perl because the first ‘<samp>@</samp>’ is removed
by make:
</p>
<div class="example">
<pre class="example">.ONESHELL:
SHELL = /usr/bin/perl
.SHELLFLAGS = -e
show :
@f = qw(a b c);
print "@f\n";
</pre></div>
<p>However, either of these alternatives would work properly:
</p>
<div class="example">
<pre class="example">.ONESHELL:
SHELL = /usr/bin/perl
.SHELLFLAGS = -e
show :
# Make sure "@" is not the first character on the first line
@f = qw(a b c);
print "@f\n";
</pre></div>
<p>or
</p>
<div class="example">
<pre class="example">.ONESHELL:
SHELL = /usr/bin/perl
.SHELLFLAGS = -e
show :
my @f = qw(a b c);
print "@f\n";
</pre></div>
<p>As a special feature, if <code>SHELL</code> is determined to be a
POSIX-style shell, the special prefix characters in “internal”
recipe lines will <em>removed</em> before the recipe is processed. This
feature is intended to allow existing makefiles to add the
<code>.ONESHELL</code> special target and still run properly without
extensive modifications. Since the special prefix characters are not
legal at the beginning of a line in a POSIX shell script this is not a
loss in functionality. For example, this works as expected:
</p>
<div class="example">
<pre class="example">.ONESHELL:
foo : bar/lose
@cd $(@D)
@gobble $(@F) > ../$@
</pre></div>
<p>Even with this special feature, however, makefiles with
<code>.ONESHELL</code> will behave differently in ways that could be
noticeable. For example, normally if any line in the recipe fails,
that causes the rule to fail and no more recipe lines are processed.
Under <code>.ONESHELL</code> a failure of any but the final recipe line will
not be noticed by <code>make</code>. You can modify <code>.SHELLFLAGS</code> to
add the <code>-e</code> option to the shell which will cause any failure
anywhere in the command line to cause the shell to fail, but this
could itself cause your recipe to behave differently. Ultimately you
may need to harden your recipe lines to allow them to work with
<code>.ONESHELL</code>.
</p>
<hr>
<a name="Choosing-the-Shell"></a>
<div class="header">
<p>
Previous: <a href="#One-Shell" accesskey="p" rel="prev">One Shell</a>, Up: <a href="#Execution" accesskey="u" rel="up">Execution</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Choosing-the-Shell-1"></a>
<h4 class="subsection">5.3.2 Choosing the Shell</h4>
<a name="index-shell_002c-choosing-the"></a>
<a name="index-SHELL_002c-value-of"></a>
<a name="index-_002eSHELLFLAGS_002c-value-of"></a>
<a name="index-SHELL"></a>
<a name="index-_002eSHELLFLAGS"></a>
<p>The program used as the shell is taken from the variable <code>SHELL</code>.
If this variable is not set in your makefile, the program
<samp>/bin/sh</samp> is used as the shell. The argument(s) passed to the
shell are taken from the variable <code>.SHELLFLAGS</code>. The default
value of <code>.SHELLFLAGS</code> is <code>-c</code> normally, or <code>-ec</code> in
POSIX-conforming mode.
</p>
<a name="index-environment_002c-SHELL-in"></a>
<p>Unlike most variables, the variable <code>SHELL</code> is never set from the
environment. This is because the <code>SHELL</code> environment variable is
used to specify your personal choice of shell program for interactive
use. It would be very bad for personal choices like this to affect the
functioning of makefiles. See <a href="Using-Variables.html#Environment">Variables from the
Environment</a>.
</p>
<p>Furthermore, when you do set <code>SHELL</code> in your makefile that value
is <em>not</em> exported in the environment to recipe lines that
<code>make</code> invokes. Instead, the value inherited from the user’s
environment, if any, is exported. You can override this behavior by
explicitly exporting <code>SHELL</code> (see <a href="#Variables_002fRecursion">Communicating Variables to a Sub-<code>make</code></a>), forcing it to be
passed in the environment to recipe lines.
</p>
<a name="index-MAKESHELL-_0028MS_002dDOS-alternative-to-SHELL_0029"></a>
<p>However, on MS-DOS and MS-Windows the value of <code>SHELL</code> in the
environment <strong>is</strong> used, since on those systems most users do not
set this variable, and therefore it is most likely set specifically to
be used by <code>make</code>. On MS-DOS, if the setting of <code>SHELL</code> is
not suitable for <code>make</code>, you can set the variable
<code>MAKESHELL</code> to the shell that <code>make</code> should use; if set it
will be used as the shell instead of the value of <code>SHELL</code>.
</p>
<a name="Choosing-a-Shell-in-DOS-and-Windows"></a>
<h4 class="subsubheading">Choosing a Shell in DOS and Windows</h4>
<a name="index-shell_002c-in-DOS-and-Windows"></a>
<a name="index-DOS_002c-choosing-a-shell-in"></a>
<a name="index-Windows_002c-choosing-a-shell-in"></a>
<p>Choosing a shell in MS-DOS and MS-Windows is much more complex than on
other systems.
</p>
<a name="index-COMSPEC"></a>
<p>On MS-DOS, if <code>SHELL</code> is not set, the value of the variable
<code>COMSPEC</code> (which is always set) is used instead.
</p>
<a name="index-SHELL_002c-MS_002dDOS-specifics"></a>
<p>The processing of lines that set the variable <code>SHELL</code> in Makefiles
is different on MS-DOS. The stock shell, <samp>command.com</samp>, is
ridiculously limited in its functionality and many users of <code>make</code>
tend to install a replacement shell. Therefore, on MS-DOS, <code>make</code>
examines the value of <code>SHELL</code>, and changes its behavior based on
whether it points to a Unix-style or DOS-style shell. This allows
reasonable functionality even if <code>SHELL</code> points to
<samp>command.com</samp>.
</p>
<p>If <code>SHELL</code> points to a Unix-style shell, <code>make</code> on MS-DOS
additionally checks whether that shell can indeed be found; if not, it
ignores the line that sets <code>SHELL</code>. In MS-DOS, GNU <code>make</code>
searches for the shell in the following places:
</p>
<ol>
<li> In the precise place pointed to by the value of <code>SHELL</code>. For
example, if the makefile specifies ‘<samp>SHELL = /bin/sh</samp>’, <code>make</code>
will look in the directory <samp>/bin</samp> on the current drive.
</li><li> In the current directory.
</li><li> In each of the directories in the <code>PATH</code> variable, in order.
</li></ol>
<p>In every directory it examines, <code>make</code> will first look for the
specific file (<samp>sh</samp> in the example above). If this is not found,
it will also look in that directory for that file with one of the known
extensions which identify executable files. For example <samp>.exe</samp>,
<samp>.com</samp>, <samp>.bat</samp>, <samp>.btm</samp>, <samp>.sh</samp>, and some others.
</p>
<p>If any of these attempts is successful, the value of <code>SHELL</code> will
be set to the full pathname of the shell as found. However, if none of
these is found, the value of <code>SHELL</code> will not be changed, and thus
the line that sets it will be effectively ignored. This is so
<code>make</code> will only support features specific to a Unix-style shell if
such a shell is actually installed on the system where <code>make</code> runs.
</p>
<p>Note that this extended search for the shell is limited to the cases
where <code>SHELL</code> is set from the Makefile; if it is set in the
environment or command line, you are expected to set it to the full
pathname of the shell, exactly as things are on Unix.
</p>
<p>The effect of the above DOS-specific processing is that a Makefile that
contains ‘<samp>SHELL = /bin/sh</samp>’ (as many Unix makefiles do), will work
on MS-DOS unaltered if you have e.g. <samp>sh.exe</samp> installed in some
directory along your <code>PATH</code>.
</p>
<a name="index-SHELL-1"></a>
<a name="index-_002eSHELLFLAGS-1"></a>
<hr>
<a name="Parallel"></a>
<div class="header">
<p>
Next: <a href="#Errors" accesskey="n" rel="next">Errors</a>, Previous: <a href="#Execution" accesskey="p" rel="prev">Execution</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Parallel-Execution"></a>
<h3 class="section">5.4 Parallel Execution</h3>
<a name="index-recipes_002c-execution-in-parallel"></a>
<a name="index-parallel-execution"></a>
<a name="index-execution_002c-in-parallel"></a>
<a name="index-job-slots"></a>
<a name="index-_002dj"></a>
<a name="index-_002d_002djobs"></a>
<p>GNU <code>make</code> knows how to execute several recipes at once.
Normally, <code>make</code> will execute only one recipe at a time, waiting
for it to finish before executing the next. However, the ‘<samp>-j</samp>’ or
‘<samp>--jobs</samp>’ option tells <code>make</code> to execute many recipes
simultaneously. You can inhibit parallelism in a particular makefile
with the <code>.NOTPARALLEL</code> pseudo-target (see <a href="Rules.html#Special-Targets">Special Built-in Target Names</a>).
</p>
<p>On MS-DOS, the ‘<samp>-j</samp>’ option has no effect, since that system doesn’t
support multi-processing.
</p>
<p>If the ‘<samp>-j</samp>’ option is followed by an integer, this is the number of
recipes to execute at once; this is called the number of <em>job slots</em>.
If there is nothing looking like an integer after the ‘<samp>-j</samp>’ option,
there is no limit on the number of job slots. The default number of job
slots is one, which means serial execution (one thing at a time).
</p>
<p>Handling recursive <code>make</code> invocations raises issues for parallel
execution. For more information on this, see <a href="#Options_002fRecursion">Communicating Options to a Sub-<code>make</code></a>.
</p>
<p>If a recipe fails (is killed by a signal or exits with a nonzero
status), and errors are not ignored for that recipe (see <a href="#Errors">Errors in Recipes</a>), the remaining recipe lines to remake the same
target will not be run. If a recipe fails and the ‘<samp>-k</samp>’ or
‘<samp>--keep-going</samp>’ option was not given (see <a href="Running.html#Options-Summary">Summary of Options</a>), <code>make</code> aborts execution. If make
terminates for any reason (including a signal) with child processes
running, it waits for them to finish before actually exiting.
</p>
<a name="index-load-average"></a>
<a name="index-limiting-jobs-based-on-load"></a>
<a name="index-jobs_002c-limiting-based-on-load"></a>
<a name="index-_002dl-_0028load-average_0029"></a>
<a name="index-_002d_002dmax_002dload"></a>
<a name="index-_002d_002dload_002daverage"></a>
<p>When the system is heavily loaded, you will probably want to run fewer jobs
than when it is lightly loaded. You can use the ‘<samp>-l</samp>’ option to tell
<code>make</code> to limit the number of jobs to run at once, based on the load
average. The ‘<samp>-l</samp>’ or ‘<samp>--max-load</samp>’
option is followed by a floating-point number. For
example,
</p>
<div class="example">
<pre class="example">-l 2.5
</pre></div>
<p>will not let <code>make</code> start more than one job if the load average is
above 2.5. The ‘<samp>-l</samp>’ option with no following number removes the
load limit, if one was given with a previous ‘<samp>-l</samp>’ option.
</p>
<p>More precisely, when <code>make</code> goes to start up a job, and it already has
at least one job running, it checks the current load average; if it is not
lower than the limit given with ‘<samp>-l</samp>’, <code>make</code> waits until the load
average goes below that limit, or until all the other jobs finish.
</p>
<p>By default, there is no load limit.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#Parallel-Output" accesskey="1">Parallel Output</a>:</td><td> </td><td align="left" valign="top">Handling output during parallel execution
</td></tr>
<tr><td align="left" valign="top">• <a href="#Parallel-Input" accesskey="2">Parallel Input</a>:</td><td> </td><td align="left" valign="top">Handling input during parallel execution
</td></tr>
</table>
<hr>
<a name="Parallel-Output"></a>
<div class="header">
<p>
Next: <a href="#Parallel-Input" accesskey="n" rel="next">Parallel Input</a>, Previous: <a href="#Parallel" accesskey="p" rel="prev">Parallel</a>, Up: <a href="#Parallel" accesskey="u" rel="up">Parallel</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Output-During-Parallel-Execution"></a>
<h4 class="subsection">5.4.1 Output During Parallel Execution</h4>
<a name="index-output-during-parallel-execution"></a>
<a name="index-parallel-execution_002c-output-during"></a>
<p>When running several recipes in parallel the output from each
recipe appears as soon as it is generated, with the result that
messages from different recipes may be interspersed, sometimes even
appearing on the same line. This can make reading the output very
difficult.
</p>
<a name="index-_002d_002doutput_002dsync"></a>
<a name="index-_002dO"></a>
<p>To avoid this you can use the ‘<samp>--output-sync</samp>’ (‘<samp>-O</samp>’) option.
This option instructs <code>make</code> to save the output from the commands
it invokes and print it all once the commands are completed.
Additionally, if there are multiple recursive <code>make</code> invocations
running in parallel, they will communicate so that only one of them is
generating output at a time.
</p>
<p>If working directory printing is enabled (see <a href="#g_t_002dw-Option">The
‘<samp>--print-directory</samp>’ Option</a>), the enter/leave messages are
printed around each output grouping. If you prefer not to see these
messages add the ‘<samp>--no-print-directory</samp>’ option to <code>MAKEFLAGS</code>.
</p>
<p>There are four levels of granularity when synchronizing output,
specified by giving an argument to the option (e.g., ‘<samp>-Oline</samp>’ or
‘<samp>--output-sync=recurse</samp>’).
</p>
<dl compact="compact">
<dt><code>none</code></dt>
<dd><p>This is the default: all output is sent directly as it is generated and
no synchronization is performed.
</p>
</dd>
<dt><code>line</code></dt>
<dd><p>Output from each individual line of the recipe is grouped and printed
as soon as that line is complete. If a recipe consists of multiple
lines, they may be interspersed with lines from other recipes.
</p>
</dd>
<dt><code>target</code></dt>
<dd><p>Output from the entire recipe for each target is grouped and printed
once the target is complete. This is the default if the
<code>--output-sync</code> or <code>-O</code> option is given with no argument.
</p>
</dd>
<dt><code>recurse</code></dt>
<dd><p>Output from each recursive invocation of <code>make</code> is grouped and
printed once the recursive invocation is complete.
</p>
</dd>
</dl>
<p>Regardless of the mode chosen, the total build time will be the same.
The only difference is in how the output appears.
</p>
<p>The ‘<samp>target</samp>’ and ‘<samp>recurse</samp>’ modes both collect the output of
the entire recipe of a target and display it uninterrupted when the
recipe completes. The difference between them is in how recipes that
contain recursive invocations of <code>make</code> are treated
(see <a href="#Recursion">Recursive Use of <code>make</code></a>). For all recipes
which have no recursive lines, the ‘<samp>target</samp>’ and ‘<samp>recurse</samp>’
modes behave identically.
</p>
<p>If the ‘<samp>recurse</samp>’ mode is chosen, recipes that contain recursive
<code>make</code> invocations are treated the same as other targets: the
output from the recipe, including the output from the recursive
<code>make</code>, is saved and printed after the entire recipe is complete.
This ensures output from all the targets built by a given recursive
<code>make</code> instance are grouped together, which may make the output
easier to understand. However it also leads to long periods of time
during the build where no output is seen, followed by large bursts of
output. If you are not watching the build as it proceeds, but instead
viewing a log of the build after the fact, this may be the best option
for you.
</p>
<p>If you are watching the output, the long gaps of quiet during the
build can be frustrating. The ‘<samp>target</samp>’ output synchronization
mode detects when <code>make</code> is going to be invoked recursively,
using the standard methods, and it will not synchronize the output of
those lines. The recursive <code>make</code> will perform the
synchronization for its targets and the output from each will be
displayed immediately when it completes. Be aware that output from
recursive lines of the recipe are not synchronized (for example if
the recursive line prints a message before running <code>make</code>, that
message will not be synchronized).
</p>
<p>The ‘<samp>line</samp>’ mode can be useful for front-ends that are watching
the output of <code>make</code> to track when recipes are started and
completed.
</p>
<p>Some programs invoked by <code>make</code> may behave differently if they
determine they’re writing output to a terminal versus a file (often
described as “interactive” vs. “non-interactive” modes). For
example, many programs that can display colorized output will not do
so if they determine they are not writing to a terminal. If your
makefile invokes a program like this then using the output
synchronization options will cause the program to believe it’s running
in “non-interactive” mode even though the output will ultimately go
to the terminal.
</p>
<hr>
<a name="Parallel-Input"></a>
<div class="header">
<p>
Previous: <a href="#Parallel-Output" accesskey="p" rel="prev">Parallel Output</a>, Up: <a href="#Parallel" accesskey="u" rel="up">Parallel</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Input-During-Parallel-Execution"></a>
<h4 class="subsection">5.4.2 Input During Parallel Execution</h4>
<a name="index-input-during-parallel-execution"></a>
<a name="index-parallel-execution_002c-input-during"></a>
<a name="index-standard-input"></a>
<p>Two processes cannot both take input from the same device at the same
time. To make sure that only one recipe tries to take input from the
terminal at once, <code>make</code> will invalidate the standard input
streams of all but one running recipe. If another recipe attempts to
read from standard input it will usually incur a fatal error (a
‘<samp>Broken pipe</samp>’ signal).
<a name="index-broken-pipe"></a>
</p>
<p>It is unpredictable which recipe will have a valid standard input stream
(which will come from the terminal, or wherever you redirect the standard
input of <code>make</code>). The first recipe run will always get it first, and
the first recipe started after that one finishes will get it next, and so
on.
</p>
<p>We will change how this aspect of <code>make</code> works if we find a better
alternative. In the mean time, you should not rely on any recipe using
standard input at all if you are using the parallel execution feature; but
if you are not using this feature, then standard input works normally in
all recipes.
</p>
<hr>
<a name="Errors"></a>
<div class="header">
<p>
Next: <a href="#Interrupts" accesskey="n" rel="next">Interrupts</a>, Previous: <a href="#Parallel" accesskey="p" rel="prev">Parallel</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Errors-in-Recipes"></a>
<h3 class="section">5.5 Errors in Recipes</h3>
<a name="index-errors-_0028in-recipes_0029"></a>
<a name="index-recipes_002c-errors-in"></a>
<a name="index-exit-status-_0028errors_0029"></a>
<p>After each shell invocation returns, <code>make</code> looks at its exit
status. If the shell completed successfully (the exit status is
zero), the next line in the recipe is executed in a new shell; after
the last line is finished, the rule is finished.
</p>
<p>If there is an error (the exit status is nonzero), <code>make</code> gives up on
the current rule, and perhaps on all rules.
</p>
<p>Sometimes the failure of a certain recipe line does not indicate a problem.
For example, you may use the <code>mkdir</code> command to ensure that a
directory exists. If the directory already exists, <code>mkdir</code> will
report an error, but you probably want <code>make</code> to continue regardless.
</p>
<a name="index-_002d-_0028in-recipes_0029"></a>
<p>To ignore errors in a recipe line, write a ‘<samp>-</samp>’ at the beginning
of the line’s text (after the initial tab). The ‘<samp>-</samp>’ is discarded
before the line is passed to the shell for execution.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">clean:
-rm -f *.o
</pre></div>
<a name="index-rm-_0028shell-command_0029-3"></a>
<p>This causes <code>make</code> to continue even if <code>rm</code> is unable to
remove a file.
</p>
<a name="index-_002di"></a>
<a name="index-_002d_002dignore_002derrors"></a>
<a name="index-_002eIGNORE-1"></a>
<p>When you run <code>make</code> with the ‘<samp>-i</samp>’ or ‘<samp>--ignore-errors</samp>’
flag, errors are ignored in all recipes of all rules. A rule in the
makefile for the special target <code>.IGNORE</code> has the same effect, if
there are no prerequisites. These ways of ignoring errors are obsolete
because ‘<samp>-</samp>’ is more flexible.
</p>
<p>When errors are to be ignored, because of either a ‘<samp>-</samp>’ or the
‘<samp>-i</samp>’ flag, <code>make</code> treats an error return just like success,
except that it prints out a message that tells you the status code
the shell exited with, and says that the error has been ignored.
</p>
<p>When an error happens that <code>make</code> has not been told to ignore,
it implies that the current target cannot be correctly remade, and neither
can any other that depends on it either directly or indirectly. No further
recipes will be executed for these targets, since their preconditions
have not been achieved.
</p>
<a name="index-_002dk"></a>
<a name="index-_002d_002dkeep_002dgoing"></a>
<p>Normally <code>make</code> gives up immediately in this circumstance, returning a
nonzero status. However, if the ‘<samp>-k</samp>’ or ‘<samp>--keep-going</samp>’
flag is specified, <code>make</code>
continues to consider the other prerequisites of the pending targets,
remaking them if necessary, before it gives up and returns nonzero status.
For example, after an error in compiling one object file, ‘<samp>make -k</samp>’
will continue compiling other object files even though it already knows
that linking them will be impossible. See <a href="Running.html#Options-Summary">Summary of Options</a>.
</p>
<p>The usual behavior assumes that your purpose is to get the specified
targets up to date; once <code>make</code> learns that this is impossible, it
might as well report the failure immediately. The ‘<samp>-k</samp>’ option says
that the real purpose is to test as many of the changes made in the
program as possible, perhaps to find several independent problems so
that you can correct them all before the next attempt to compile. This
is why Emacs’ <code>compile</code> command passes the ‘<samp>-k</samp>’ flag by
default.
<a name="index-Emacs-_0028M_002dx-compile_0029"></a>
</p>
<a name="index-_002eDELETE_005fON_005fERROR-1"></a>
<a name="index-deletion-of-target-files"></a>
<a name="index-removal-of-target-files"></a>
<a name="index-target_002c-deleting-on-error"></a>
<p>Usually when a recipe line fails, if it has changed the target file at all,
the file is corrupted and cannot be used—or at least it is not
completely updated. Yet the file’s time stamp says that it is now up to
date, so the next time <code>make</code> runs, it will not try to update that
file. The situation is just the same as when the shell is killed by a
signal; see <a href="#Interrupts">Interrupts</a>. So generally the right thing to do is to
delete the target file if the recipe fails after beginning to change
the file. <code>make</code> will do this if <code>.DELETE_ON_ERROR</code> appears
as a target. This is almost always what you want <code>make</code> to do, but
it is not historical practice; so for compatibility, you must explicitly
request it.
</p>
<hr>
<a name="Interrupts"></a>
<div class="header">
<p>
Next: <a href="#Recursion" accesskey="n" rel="next">Recursion</a>, Previous: <a href="#Errors" accesskey="p" rel="prev">Errors</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Interrupting-or-Killing-make"></a>
<h3 class="section">5.6 Interrupting or Killing <code>make</code></h3>
<a name="index-interrupt"></a>
<a name="index-signal"></a>
<a name="index-deletion-of-target-files-1"></a>
<a name="index-removal-of-target-files-1"></a>
<a name="index-target_002c-deleting-on-interrupt"></a>
<a name="index-killing-_0028interruption_0029"></a>
<p>If <code>make</code> gets a fatal signal while a shell is executing, it may
delete the target file that the recipe was supposed to update. This is
done if the target file’s last-modification time has changed since
<code>make</code> first checked it.
</p>
<p>The purpose of deleting the target is to make sure that it is remade from
scratch when <code>make</code> is next run. Why is this? Suppose you type
<kbd>Ctrl-c</kbd> while a compiler is running, and it has begun to write an
object file <samp>foo.o</samp>. The <kbd>Ctrl-c</kbd> kills the compiler, resulting
in an incomplete file whose last-modification time is newer than the source
file <samp>foo.c</samp>. But <code>make</code> also receives the <kbd>Ctrl-c</kbd> signal
and deletes this incomplete file. If <code>make</code> did not do this, the next
invocation of <code>make</code> would think that <samp>foo.o</samp> did not require
updating—resulting in a strange error message from the linker when it
tries to link an object file half of which is missing.
</p>
<a name="index-_002ePRECIOUS-1"></a>
<p>You can prevent the deletion of a target file in this way by making the
special target <code>.PRECIOUS</code> depend on it. Before remaking a target,
<code>make</code> checks to see whether it appears on the prerequisites of
<code>.PRECIOUS</code>, and thereby decides whether the target should be deleted
if a signal happens. Some reasons why you might do this are that the
target is updated in some atomic fashion, or exists only to record a
modification-time (its contents do not matter), or must exist at all
times to prevent other sorts of trouble.
</p>
<hr>
<a name="Recursion"></a>
<div class="header">
<p>
Next: <a href="#Canned-Recipes" accesskey="n" rel="next">Canned Recipes</a>, Previous: <a href="#Interrupts" accesskey="p" rel="prev">Interrupts</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Recursive-Use-of-make"></a>
<h3 class="section">5.7 Recursive Use of <code>make</code></h3>
<a name="index-recursion"></a>
<a name="index-subdirectories_002c-recursion-for"></a>
<p>Recursive use of <code>make</code> means using <code>make</code> as a command in a
makefile. This technique is useful when you want separate makefiles for
various subsystems that compose a larger system. For example, suppose you
have a sub-directory <samp>subdir</samp> which has its own makefile, and you would
like the containing directory’s makefile to run <code>make</code> on the
sub-directory. You can do it by writing this:
</p>
<div class="example">
<pre class="example">subsystem:
cd subdir && $(MAKE)
</pre></div>
<p>or, equivalently, this (see <a href="Running.html#Options-Summary">Summary of Options</a>):
</p>
<div class="example">
<pre class="example">subsystem:
$(MAKE) -C subdir
</pre></div>
<a name="index-_002dC"></a>
<a name="index-_002d_002ddirectory"></a>
<p>You can write recursive <code>make</code> commands just by copying this example,
but there are many things to know about how they work and why, and about
how the sub-<code>make</code> relates to the top-level <code>make</code>. You may
also find it useful to declare targets that invoke recursive
<code>make</code> commands as ‘<samp>.PHONY</samp>’ (for more discussion on when
this is useful, see <a href="Rules.html#Phony-Targets">Phony Targets</a>).
</p>
<a name="index-CURDIR"></a>
<p>For your convenience, when GNU <code>make</code> starts (after it has
processed any <code>-C</code> options) it sets the variable <code>CURDIR</code> to
the pathname of the current working directory. This value is never
touched by <code>make</code> again: in particular note that if you include
files from other directories the value of <code>CURDIR</code> does not
change. The value has the same precedence it would have if it were
set in the makefile (by default, an environment variable <code>CURDIR</code>
will not override this value). Note that setting this variable has no
impact on the operation of <code>make</code> (it does not cause <code>make</code>
to change its working directory, for example).
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">• <a href="#MAKE-Variable" accesskey="1">MAKE Variable</a>:</td><td> </td><td align="left" valign="top">The special effects of using ‘<samp>$(MAKE)</samp>’.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Variables_002fRecursion" accesskey="2">Variables/Recursion</a>:</td><td> </td><td align="left" valign="top">How to communicate variables to a sub-<code>make</code>.
</td></tr>
<tr><td align="left" valign="top">• <a href="#Options_002fRecursion" accesskey="3">Options/Recursion</a>:</td><td> </td><td align="left" valign="top">How to communicate options to a sub-<code>make</code>.
</td></tr>
<tr><td align="left" valign="top">• <a href="#g_t_002dw-Option" accesskey="4">-w Option</a>:</td><td> </td><td align="left" valign="top">How the ‘<samp>-w</samp>’ or ‘<samp>--print-directory</samp>’ option
helps debug use of recursive <code>make</code> commands.
</td></tr>
</table>
<hr>
<a name="MAKE-Variable"></a>
<div class="header">
<p>
Next: <a href="#Variables_002fRecursion" accesskey="n" rel="next">Variables/Recursion</a>, Previous: <a href="#Recursion" accesskey="p" rel="prev">Recursion</a>, Up: <a href="#Recursion" accesskey="u" rel="up">Recursion</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="How-the-MAKE-Variable-Works"></a>
<h4 class="subsection">5.7.1 How the <code>MAKE</code> Variable Works</h4>
<a name="index-MAKE"></a>
<a name="index-recursion_002c-and-MAKE-variable"></a>
<p>Recursive <code>make</code> commands should always use the variable <code>MAKE</code>,
not the explicit command name ‘<samp>make</samp>’, as shown here:
</p>
<div class="example">
<pre class="example">subsystem:
cd subdir && $(MAKE)
</pre></div>
<p>The value of this variable is the file name with which <code>make</code> was
invoked. If this file name was <samp>/bin/make</samp>, then the recipe executed
is ‘<samp>cd subdir && /bin/make</samp>’. If you use a special version of
<code>make</code> to run the top-level makefile, the same special version will be
executed for recursive invocations.
<a name="index-cd-_0028shell-command_0029-1"></a>
</p>
<a name="index-_002b_002c-and-recipes"></a>
<p>As a special feature, using the variable <code>MAKE</code> in the recipe of
a rule alters the effects of the ‘<samp>-t</samp>’ (‘<samp>--touch</samp>’), ‘<samp>-n</samp>’
(‘<samp>--just-print</samp>’), or ‘<samp>-q</samp>’ (‘<samp><span class="nolinebreak">--question</span></samp>’<!-- /@w -->) option.
Using the <code>MAKE</code> variable has the same effect as using a ‘<samp>+</samp>’
character at the beginning of the recipe line. See <a href="Running.html#Instead-of-Execution">Instead of Executing the Recipes</a>. This special feature
is only enabled if the <code>MAKE</code> variable appears directly in the
recipe: it does not apply if the <code>MAKE</code> variable is referenced
through expansion of another variable. In the latter case you must
use the ‘<samp>+</samp>’ token to get these special effects.
</p>
<p>Consider the command ‘<samp>make -t</samp>’ in the above example. (The
‘<samp>-t</samp>’ option marks targets as up to date without actually running
any recipes; see <a href="Running.html#Instead-of-Execution">Instead of Execution</a>.) Following the usual
definition of ‘<samp>-t</samp>’, a ‘<samp>make -t</samp>’ command in the example would
create a file named <samp>subsystem</samp> and do nothing else. What you
really want it to do is run ‘<samp>cd subdir &&<!-- /@w --> make <span class="nolinebreak">-t</span><!-- /@w --></samp>’; but
that would require executing the recipe, and ‘<samp>-t</samp>’ says not to
execute recipes.
<a name="index-_002dt_002c-and-recursion"></a>
<a name="index-recursion_002c-and-_002dt"></a>
<a name="index-_002d_002dtouch_002c-and-recursion"></a>
</p>
<p>The special feature makes this do what you want: whenever a recipe
line of a rule contains the variable <code>MAKE</code>, the flags ‘<samp>-t</samp>’,
‘<samp>-n</samp>’ and ‘<samp>-q</samp>’ do not apply to that line. Recipe lines
containing <code>MAKE</code> are executed normally despite the presence of a
flag that causes most recipes not to be run. The usual
<code>MAKEFLAGS</code> mechanism passes the flags to the sub-<code>make</code>
(see <a href="#Options_002fRecursion">Communicating Options to a
Sub-<code>make</code></a>), so your request to touch the files, or print the
recipes, is propagated to the subsystem.
</p>
<hr>
<a name="Variables_002fRecursion"></a>
<div class="header">
<p>
Next: <a href="#Options_002fRecursion" accesskey="n" rel="next">Options/Recursion</a>, Previous: <a href="#MAKE-Variable" accesskey="p" rel="prev">MAKE Variable</a>, Up: <a href="#Recursion" accesskey="u" rel="up">Recursion</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Communicating-Variables-to-a-Sub_002dmake"></a>
<h4 class="subsection">5.7.2 Communicating Variables to a Sub-<code>make</code></h4>
<a name="index-sub_002dmake"></a>
<a name="index-environment_002c-and-recursion"></a>
<a name="index-exporting-variables"></a>
<a name="index-variables_002c-environment"></a>
<a name="index-variables_002c-exporting"></a>
<a name="index-recursion_002c-and-environment"></a>
<a name="index-recursion_002c-and-variables"></a>
<p>Variable values of the top-level <code>make</code> can be passed to the
sub-<code>make</code> through the environment by explicit request. These
variables are defined in the sub-<code>make</code> as defaults, but they do
not override variables defined in the makefile used by
the sub-<code>make</code> unless you use the ‘<samp>-e</samp>’ switch (see <a href="Running.html#Options-Summary">Summary of Options</a>).
</p>
<p>To pass down, or <em>export</em>, a variable, <code>make</code> adds the
variable and its value to the environment for running each line of the
recipe. The sub-<code>make</code>, in turn, uses the environment to
initialize its table of variable values. See <a href="Using-Variables.html#Environment">Variables from the Environment</a>.
</p>
<p>Except by explicit request, <code>make</code> exports a variable only if it
is either defined in the environment initially or set on the command
line, and if its name consists only of letters, numbers, and underscores.
Some shells cannot cope with environment variable names consisting of
characters other than letters, numbers, and underscores.
</p>
<a name="index-SHELL_002c-exported-value"></a>
<p>The value of the <code>make</code> variable <code>SHELL</code> is not exported.
Instead, the value of the <code>SHELL</code> variable from the invoking
environment is passed to the sub-<code>make</code>. You can force
<code>make</code> to export its value for <code>SHELL</code> by using the
<code>export</code> directive, described below. See <a href="#Choosing-the-Shell">Choosing the Shell</a>.
</p>
<p>The special variable <code>MAKEFLAGS</code> is always exported (unless you
unexport it). <code>MAKEFILES</code> is exported if you set it to anything.
</p>
<p><code>make</code> automatically passes down variable values that were defined
on the command line, by putting them in the <code>MAKEFLAGS</code> variable.
See <a href="#Options_002fRecursion">Options/Recursion</a>.
</p>
<p>Variables are <em>not</em> normally passed down if they were created by
default by <code>make</code> (see <a href="Implicit-Rules.html#Implicit-Variables">Variables Used by
Implicit Rules</a>). The sub-<code>make</code> will define these for
itself.
</p>
<a name="index-export"></a>
<p>If you want to export specific variables to a sub-<code>make</code>, use the
<code>export</code> directive, like this:
</p>
<div class="example">
<pre class="example">export <var>variable</var> …
</pre></div>
<a name="index-unexport"></a>
<p>If you want to <em>prevent</em> a variable from being exported, use the
<code>unexport</code> directive, like this:
</p>
<div class="example">
<pre class="example">unexport <var>variable</var> …
</pre></div>
<p>In both of these forms, the arguments to <code>export</code> and
<code>unexport</code> are expanded, and so could be variables or functions
which expand to a (list of) variable names to be (un)exported.
</p>
<p>As a convenience, you can define a variable and export it at the same
time by doing:
</p>
<div class="example">
<pre class="example">export <var>variable</var> = value
</pre></div>
<p>has the same result as:
</p>
<div class="example">
<pre class="example"><var>variable</var> = value
export <var>variable</var>
</pre></div>
<p>and
</p>
<div class="example">
<pre class="example">export <var>variable</var> := value
</pre></div>
<p>has the same result as:
</p>
<div class="example">
<pre class="example"><var>variable</var> := value
export <var>variable</var>
</pre></div>
<p>Likewise,
</p>
<div class="example">
<pre class="example">export <var>variable</var> += value
</pre></div>
<p>is just like:
</p>
<div class="example">
<pre class="example"><var>variable</var> += value
export <var>variable</var>
</pre></div>
<p>See <a href="Using-Variables.html#Appending">Appending More Text to Variables</a>.
</p>
<p>You may notice that the <code>export</code> and <code>unexport</code> directives
work in <code>make</code> in the same way they work in the shell, <code>sh</code>.
</p>
<p>If you want all variables to be exported by default, you can use
<code>export</code> by itself:
</p>
<div class="example">
<pre class="example">export
</pre></div>
<p>This tells <code>make</code> that variables which are not explicitly mentioned
in an <code>export</code> or <code>unexport</code> directive should be exported.
Any variable given in an <code>unexport</code> directive will still <em>not</em>
be exported. If you use <code>export</code> by itself to export variables by
default, variables whose names contain characters other than
alphanumerics and underscores will not be exported unless specifically
mentioned in an <code>export</code> directive.
</p>
<a name="index-_002eEXPORT_005fALL_005fVARIABLES-1"></a>
<p>The behavior elicited by an <code>export</code> directive by itself was the
default in older versions of GNU <code>make</code>. If your makefiles depend
on this behavior and you want to be compatible with old versions of
<code>make</code>, you can write a rule for the special target
<code>.EXPORT_ALL_VARIABLES</code> instead of using the <code>export</code> directive.
This will be ignored by old <code>make</code>s, while the <code>export</code>
directive will cause a syntax error.
<a name="index-compatibility-in-exporting"></a>
</p>
<p>Likewise, you can use <code>unexport</code> by itself to tell <code>make</code>
<em>not</em> to export variables by default. Since this is the default
behavior, you would only need to do this if <code>export</code> had been used
by itself earlier (in an included makefile, perhaps). You
<strong>cannot</strong> use <code>export</code> and <code>unexport</code> by themselves to
have variables exported for some recipes and not for others. The last
<code>export</code> or <code>unexport</code> directive that appears by itself
determines the behavior for the entire run of <code>make</code>.
</p>
<a name="index-MAKELEVEL"></a>
<a name="index-recursion_002c-level-of"></a>
<p>As a special feature, the variable <code>MAKELEVEL</code> is changed when it
is passed down from level to level. This variable’s value is a string
which is the depth of the level as a decimal number. The value is
‘<samp>0</samp>’ for the top-level <code>make</code>; ‘<samp>1</samp>’ for a sub-<code>make</code>,
‘<samp>2</samp>’ for a sub-sub-<code>make</code>, and so on. The incrementation
happens when <code>make</code> sets up the environment for a recipe.
</p>
<p>The main use of <code>MAKELEVEL</code> is to test it in a conditional
directive (see <a href="Conditionals.html#Conditionals">Conditional Parts of Makefiles</a>); this
way you can write a makefile that behaves one way if run recursively and
another way if run directly by you.
</p>
<a name="index-MAKEFILES-1"></a>
<p>You can use the variable <code>MAKEFILES</code> to cause all sub-<code>make</code>
commands to use additional makefiles. The value of <code>MAKEFILES</code> is
a whitespace-separated list of file names. This variable, if defined in
the outer-level makefile, is passed down through the environment; then
it serves as a list of extra makefiles for the sub-<code>make</code> to read
before the usual or specified ones. See <a href="Makefiles.html#MAKEFILES-Variable">The
Variable <code>MAKEFILES</code></a>.
</p>
<hr>
<a name="Options_002fRecursion"></a>
<div class="header">
<p>
Next: <a href="#g_t_002dw-Option" accesskey="n" rel="next">-w Option</a>, Previous: <a href="#Variables_002fRecursion" accesskey="p" rel="prev">Variables/Recursion</a>, Up: <a href="#Recursion" accesskey="u" rel="up">Recursion</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Communicating-Options-to-a-Sub_002dmake"></a>
<h4 class="subsection">5.7.3 Communicating Options to a Sub-<code>make</code></h4>
<a name="index-options_002c-and-recursion"></a>
<a name="index-recursion_002c-and-options"></a>
<a name="index-MAKEFLAGS"></a>
<p>Flags such as ‘<samp>-s</samp>’ and ‘<samp>-k</samp>’ are passed automatically to the
sub-<code>make</code> through the variable <code>MAKEFLAGS</code>. This variable is
set up automatically by <code>make</code> to contain the flag letters that
<code>make</code> received. Thus, if you do ‘<samp>make <span class="nolinebreak">-ks</span></samp>’<!-- /@w --> then
<code>MAKEFLAGS</code> gets the value ‘<samp>ks</samp>’.
</p>
<p>As a consequence, every sub-<code>make</code> gets a value for <code>MAKEFLAGS</code>
in its environment. In response, it takes the flags from that value and
processes them as if they had been given as arguments.
See <a href="Running.html#Options-Summary">Summary of Options</a>.
</p>
<a name="index-command-line-variable-definitions_002c-and-recursion"></a>
<a name="index-variables_002c-command-line_002c-and-recursion"></a>
<a name="index-recursion_002c-and-command-line-variable-definitions"></a>
<p>Likewise variables defined on the command line are passed to the
sub-<code>make</code> through <code>MAKEFLAGS</code>. Words in the value of
<code>MAKEFLAGS</code> that contain ‘<samp>=</samp>’, <code>make</code> treats as variable
definitions just as if they appeared on the command line.
See <a href="Running.html#Overriding">Overriding Variables</a>.
</p>
<a name="index-_002dC_002c-and-recursion"></a>
<a name="index-_002df_002c-and-recursion"></a>
<a name="index-_002do_002c-and-recursion"></a>
<a name="index-_002dW_002c-and-recursion"></a>
<a name="index-_002d_002ddirectory_002c-and-recursion"></a>
<a name="index-_002d_002dfile_002c-and-recursion"></a>
<a name="index-_002d_002dold_002dfile_002c-and-recursion"></a>
<a name="index-_002d_002dassume_002dold_002c-and-recursion"></a>
<a name="index-_002d_002dassume_002dnew_002c-and-recursion"></a>
<a name="index-_002d_002dnew_002dfile_002c-and-recursion"></a>
<a name="index-recursion_002c-and-_002dC"></a>
<a name="index-recursion_002c-and-_002df"></a>
<a name="index-recursion_002c-and-_002do"></a>
<a name="index-recursion_002c-and-_002dW"></a>
<p>The options ‘<samp>-C</samp>’, ‘<samp>-f</samp>’, ‘<samp>-o</samp>’, and ‘<samp>-W</samp>’ are not put
into <code>MAKEFLAGS</code>; these options are not passed down.
</p>
<a name="index-_002dj_002c-and-recursion"></a>
<a name="index-_002d_002djobs_002c-and-recursion"></a>
<a name="index-recursion_002c-and-_002dj"></a>
<a name="index-job-slots_002c-and-recursion"></a>
<p>The ‘<samp>-j</samp>’ option is a special case (see <a href="#Parallel">Parallel Execution</a>).
If you set it to some numeric value ‘<samp>N</samp>’ and your operating system
supports it (most any UNIX system will; others typically won’t), the
parent <code>make</code> and all the sub-<code>make</code>s will communicate to
ensure that there are only ‘<samp>N</samp>’ jobs running at the same time
between them all. Note that any job that is marked recursive
(see <a href="Running.html#Instead-of-Execution">Instead of Executing Recipes</a>)
doesn’t count against the total jobs (otherwise we could get ‘<samp>N</samp>’
sub-<code>make</code>s running and have no slots left over for any real work!)
</p>
<p>If your operating system doesn’t support the above communication, then
‘<samp>-j 1</samp>’ is always put into <code>MAKEFLAGS</code> instead of the value you
specified. This is because if the ‘<samp><span class="nolinebreak">-j</span></samp>’<!-- /@w --> option were passed down
to sub-<code>make</code>s, you would get many more jobs running in parallel
than you asked for. If you give ‘<samp>-j</samp>’ with no numeric argument,
meaning to run as many jobs as possible in parallel, this is passed
down, since multiple infinities are no more than one.
</p>
<p>If you do not want to pass the other flags down, you must change the
value of <code>MAKEFLAGS</code>, like this:
</p>
<div class="example">
<pre class="example">subsystem:
cd subdir && $(MAKE) MAKEFLAGS=
</pre></div>
<a name="index-MAKEOVERRIDES"></a>
<p>The command line variable definitions really appear in the variable
<code>MAKEOVERRIDES</code>, and <code>MAKEFLAGS</code> contains a reference to this
variable. If you do want to pass flags down normally, but don’t want to
pass down the command line variable definitions, you can reset
<code>MAKEOVERRIDES</code> to empty, like this:
</p>
<div class="example">
<pre class="example">MAKEOVERRIDES =
</pre></div>
<a name="index-Arg-list-too-long"></a>
<a name="index-E2BIG"></a>
<p>This is not usually useful to do. However, some systems have a small
fixed limit on the size of the environment, and putting so much
information into the value of <code>MAKEFLAGS</code> can exceed it. If you
see the error message ‘<samp>Arg list too long</samp>’, this may be the problem.
<a name="index-_002ePOSIX-1"></a>
<a name="index-POSIX-1"></a>
(For strict compliance with POSIX.2, changing <code>MAKEOVERRIDES</code> does
not affect <code>MAKEFLAGS</code> if the special target ‘<samp>.POSIX</samp>’ appears
in the makefile. You probably do not care about this.)
</p>
<a name="index-MFLAGS"></a>
<p>A similar variable <code>MFLAGS</code> exists also, for historical
compatibility. It has the same value as <code>MAKEFLAGS</code> except that it
does not contain the command line variable definitions, and it always
begins with a hyphen unless it is empty (<code>MAKEFLAGS</code> begins with a
hyphen only when it begins with an option that has no single-letter
version, such as ‘<samp>--warn-undefined-variables</samp>’). <code>MFLAGS</code> was
traditionally used explicitly in the recursive <code>make</code> command, like
this:
</p>
<div class="example">
<pre class="example">subsystem:
cd subdir && $(MAKE) $(MFLAGS)
</pre></div>
<p>but now <code>MAKEFLAGS</code> makes this usage redundant. If you want your
makefiles to be compatible with old <code>make</code> programs, use this
technique; it will work fine with more modern <code>make</code> versions too.
</p>
<a name="index-setting-options-from-environment"></a>
<a name="index-options_002c-setting-from-environment"></a>
<a name="index-setting-options-in-makefiles"></a>
<a name="index-options_002c-setting-in-makefiles"></a>
<p>The <code>MAKEFLAGS</code> variable can also be useful if you want to have
certain options, such as ‘<samp>-k</samp>’ (see <a href="Running.html#Options-Summary">Summary of
Options</a>), set each time you run <code>make</code>. You simply put a value for
<code>MAKEFLAGS</code> in your environment. You can also set <code>MAKEFLAGS</code> in
a makefile, to specify additional flags that should also be in effect for
that makefile. (Note that you cannot use <code>MFLAGS</code> this way. That
variable is set only for compatibility; <code>make</code> does not interpret a
value you set for it in any way.)
</p>
<p>When <code>make</code> interprets the value of <code>MAKEFLAGS</code> (either from the
environment or from a makefile), it first prepends a hyphen if the value
does not already begin with one. Then it chops the value into words
separated by blanks, and parses these words as if they were options given
on the command line (except that ‘<samp>-C</samp>’, ‘<samp>-f</samp>’, ‘<samp>-h</samp>’,
‘<samp>-o</samp>’, ‘<samp>-W</samp>’, and their long-named versions are ignored; and there
is no error for an invalid option).
</p>
<p>If you do put <code>MAKEFLAGS</code> in your environment, you should be sure not
to include any options that will drastically affect the actions of
<code>make</code> and undermine the purpose of makefiles and of <code>make</code>
itself. For instance, the ‘<samp>-t</samp>’, ‘<samp>-n</samp>’, and ‘<samp>-q</samp>’ options, if
put in one of these variables, could have disastrous consequences and would
certainly have at least surprising and probably annoying effects.
</p>
<p>If you’d like to run other implementations of <code>make</code> in addition
to GNU <code>make</code>, and hence do not want to add GNU
<code>make</code>-specific flags to the <code>MAKEFLAGS</code> variable, you can
add them to the <code>GNUMAKEFLAGS</code> variable instead. This variable
is parsed just before <code>MAKEFLAGS</code>, in the same way as
<code>MAKEFLAGS</code>. When <code>make</code> constructs <code>MAKEFLAGS</code> to
pass to a recursive <code>make</code> it will include all flags, even those
taken from <code>GNUMAKEFLAGS</code>. As a result, after parsing
<code>GNUMAKEFLAGS</code> GNU <code>make</code> sets this variable to the empty
string to avoid duplicating flags during recursion.
</p>
<p>It’s best to use <code>GNUMAKEFLAGS</code> only with flags which won’t
materially change the behavior of your makefiles. If your makefiles
require GNU make anyway then simply use <code>MAKEFLAGS</code>. Flags such
as ‘<samp>--no-print-directory</samp>’ or ‘<samp>--output-sync</samp>’ may be
appropriate for <code>GNUMAKEFLAGS</code>.
</p>
<hr>
<a name="g_t_002dw-Option"></a>
<div class="header">
<p>
Previous: <a href="#Options_002fRecursion" accesskey="p" rel="prev">Options/Recursion</a>, Up: <a href="#Recursion" accesskey="u" rel="up">Recursion</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-_002d_002dprint_002ddirectory-Option"></a>
<h4 class="subsection">5.7.4 The ‘<samp>--print-directory</samp>’ Option</h4>
<a name="index-directories_002c-printing-them"></a>
<a name="index-printing-directories"></a>
<a name="index-recursion_002c-and-printing-directories"></a>
<p>If you use several levels of recursive <code>make</code> invocations, the
‘<samp>-w</samp>’ or ‘<samp><span class="nolinebreak">--print-directory</span></samp>’<!-- /@w --> option can make the output a
lot easier to understand by showing each directory as <code>make</code>
starts processing it and as <code>make</code> finishes processing it. For
example, if ‘<samp>make -w</samp>’ is run in the directory <samp>/u/gnu/make</samp>,
<code>make</code> will print a line of the form:
</p>
<div class="example">
<pre class="example">make: Entering directory `/u/gnu/make'.
</pre></div>
<p>before doing anything else, and a line of the form:
</p>
<div class="example">
<pre class="example">make: Leaving directory `/u/gnu/make'.
</pre></div>
<p>when processing is completed.
</p>
<a name="index-_002dC_002c-and-_002dw"></a>
<a name="index-_002d_002ddirectory_002c-and-_002d_002dprint_002ddirectory"></a>
<a name="index-recursion_002c-and-_002dw"></a>
<a name="index-_002dw_002c-and-_002dC"></a>
<a name="index-_002dw_002c-and-recursion"></a>
<a name="index-_002d_002dprint_002ddirectory_002c-and-_002d_002ddirectory"></a>
<a name="index-_002d_002dprint_002ddirectory_002c-and-recursion"></a>
<a name="index-_002d_002dno_002dprint_002ddirectory"></a>
<a name="index-_002d_002dprint_002ddirectory_002c-disabling"></a>
<a name="index-_002dw_002c-disabling"></a>
<p>Normally, you do not need to specify this option because ‘<samp>make</samp>’
does it for you: ‘<samp>-w</samp>’ is turned on automatically when you use the
‘<samp>-C</samp>’ option, and in sub-<code>make</code>s. <code>make</code> will not
automatically turn on ‘<samp>-w</samp>’ if you also use ‘<samp>-s</samp>’, which says to
be silent, or if you use ‘<samp>--no-print-directory</samp>’ to explicitly
disable it.
</p>
<hr>
<a name="Canned-Recipes"></a>
<div class="header">
<p>
Next: <a href="#Empty-Recipes" accesskey="n" rel="next">Empty Recipes</a>, Previous: <a href="#Recursion" accesskey="p" rel="prev">Recursion</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Defining-Canned-Recipes"></a>
<h3 class="section">5.8 Defining Canned Recipes</h3>
<a name="index-canned-recipes"></a>
<a name="index-recipes_002c-canned"></a>
<a name="index-sequences-of-commands"></a>
<a name="index-commands_002c-sequences-of"></a>
<p>When the same sequence of commands is useful in making various
targets, you can define it as a canned sequence with the <code>define</code>
directive, and refer to the canned sequence from the recipes for those
targets. The canned sequence is actually a variable, so the name must
not conflict with other variable names.
</p>
<p>Here is an example of defining a canned recipe:
</p>
<div class="example">
<pre class="example">define run-yacc =
yacc $(firstword $^)
mv y.tab.c $@
endef
</pre></div>
<a name="index-yacc"></a>
<p>Here <code>run-yacc</code> is the name of the variable being defined;
<code>endef</code> marks the end of the definition; the lines in between are the
commands. The <code>define</code> directive does not expand variable references
and function calls in the canned sequence; the ‘<samp>$</samp>’ characters,
parentheses, variable names, and so on, all become part of the value of the
variable you are defining.
See <a href="Using-Variables.html#Multi_002dLine">Defining Multi-Line Variables</a>,
for a complete explanation of <code>define</code>.
</p>
<p>The first command in this example runs Yacc on the first prerequisite of
whichever rule uses the canned sequence. The output file from Yacc is
always named <samp>y.tab.c</samp>. The second command moves the output to the
rule’s target file name.
</p>
<p>To use the canned sequence, substitute the variable into the recipe of a
rule. You can substitute it like any other variable
(see <a href="Using-Variables.html#Reference">Basics of Variable References</a>).
Because variables defined by <code>define</code> are recursively expanded
variables, all the variable references you wrote inside the <code>define</code>
are expanded now. For example:
</p>
<div class="example">
<pre class="example">foo.c : foo.y
$(run-yacc)
</pre></div>
<p>‘<samp>foo.y</samp>’ will be substituted for the variable ‘<samp>$^</samp>’ when it occurs in
<code>run-yacc</code>’s value, and ‘<samp>foo.c</samp>’ for ‘<samp>$@</samp>’.
</p>
<p>This is a realistic example, but this particular one is not needed in
practice because <code>make</code> has an implicit rule to figure out these
commands based on the file names involved
(see <a href="Implicit-Rules.html#Implicit-Rules">Using Implicit Rules</a>).
</p>
<a name="index-_0040_002c-and-define"></a>
<a name="index-_002d_002c-and-define"></a>
<a name="index-_002b_002c-and-define"></a>
<p>In recipe execution, each line of a canned sequence is treated just as
if the line appeared on its own in the rule, preceded by a tab. In
particular, <code>make</code> invokes a separate sub-shell for each line. You
can use the special prefix characters that affect command lines
(‘<samp>@</samp>’, ‘<samp>-</samp>’, and ‘<samp>+</samp>’) on each line of a canned sequence.
See <a href="#Recipes">Writing Recipes in Rules</a>.
For example, using this canned sequence:
</p>
<div class="example">
<pre class="example">define frobnicate =
@echo "frobnicating target $@"
frob-step-1 $< -o $@-step-1
frob-step-2 $@-step-1 -o $@
endef
</pre></div>
<p><code>make</code> will not echo the first line, the <code>echo</code> command.
But it <em>will</em> echo the following two recipe lines.
</p>
<p>On the other hand, prefix characters on the recipe line that refers to
a canned sequence apply to every line in the sequence. So the rule:
</p>
<div class="example">
<pre class="example">frob.out: frob.in
@$(frobnicate)
</pre></div>
<p>does not echo <em>any</em> recipe lines.
(See <a href="#Echoing">Recipe Echoing</a>, for a full explanation of ‘<samp>@</samp>’.)
</p>
<hr>
<a name="Empty-Recipes"></a>
<div class="header">
<p>
Previous: <a href="#Canned-Recipes" accesskey="p" rel="prev">Canned Recipes</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Using-Empty-Recipes"></a>
<h3 class="section">5.9 Using Empty Recipes</h3>
<a name="index-empty-recipes"></a>
<a name="index-recipes_002c-empty"></a>
<p>It is sometimes useful to define recipes which do nothing. This is done
simply by giving a recipe that consists of nothing but whitespace. For
example:
</p>
<div class="example">
<pre class="example">target: ;
</pre></div>
<p>defines an empty recipe for <samp>target</samp>. You could also use a line
beginning with a recipe prefix character to define an empty recipe,
but this would be confusing because such a line looks empty.
</p>
<a name="index-_002eDEFAULT_002c-and-empty-recipes"></a>
<p>You may be wondering why you would want to define a recipe that
does nothing. The only reason this is useful is to prevent a target
from getting implicit recipes (from implicit rules or the
<code>.DEFAULT</code> special target; see <a href="Implicit-Rules.html#Implicit-Rules">Implicit Rules</a> and
see <a href="Implicit-Rules.html#Last-Resort">Defining Last-Resort Default Rules</a>).
</p>
<p>You may be inclined to define empty recipes for targets that are
not actual files, but only exist so that their prerequisites can be
remade. However, this is not the best way to do that, because the
prerequisites may not be remade properly if the target file actually does exist.
See <a href="Rules.html#Phony-Targets">Phony Targets</a>, for a better way to do this.
</p>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>
<h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
<p>On
MS-DOS, the value of current working directory is <strong>global</strong>, so
changing it <em>will</em> affect the following recipe lines on those
systems.</p>
</div>
<hr>
<div class="header">
<p>
Previous: <a href="#Canned-Recipes" accesskey="p" rel="prev">Canned Recipes</a>, Up: <a href="#Recipes" accesskey="u" rel="up">Recipes</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|