This file is indexed.

/usr/share/doc/make-doc/make.html/Functions.html is in make-doc 4.2.1-1.

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
<!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.74, last updated 21 May 2016,
of The GNU Make Manual, for GNU make version 4.2.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, 2015, 2016 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.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Functions (GNU make)</title>

<meta name="description" content="Functions (GNU make)">
<meta name="keywords" content="Functions (GNU make)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<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="Running.html#Running" rel="next" title="Running">
<link href="Conditionals.html#Testing-Flags" rel="prev" title="Testing Flags">
<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.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; 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="Functions"></a>
<div class="header">
<p>
Next: <a href="Running.html#Running" accesskey="n" rel="next">Running</a>, Previous: <a href="Conditionals.html#Conditionals" accesskey="p" rel="prev">Conditionals</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<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="Functions-for-Transforming-Text"></a>
<h2 class="chapter">8 Functions for Transforming Text</h2>
<a name="index-functions"></a>

<p><em>Functions</em> allow you to do text processing in the makefile to
compute the files to operate on or the commands to use in recipes.
You use a function in a <em>function call</em>, where you give the name
of the function and some text (the <em>arguments</em>) for the function
to operate on.  The result of the function&rsquo;s processing is substituted
into the makefile at the point of the call, just as a variable might
be substituted.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Syntax-of-Functions" accesskey="1">Syntax of Functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">How to write a function call.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Text-Functions" accesskey="2">Text Functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">General-purpose text manipulation functions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#File-Name-Functions" accesskey="3">File Name Functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Functions for manipulating file names.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Conditional-Functions" accesskey="4">Conditional Functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Functions that implement conditions.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreach-Function" accesskey="5">Foreach Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Repeat some text with controlled variation.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#File-Function" accesskey="6">File Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Write text to a file.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Call-Function" accesskey="7">Call Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Expand a user-defined function.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Value-Function" accesskey="8">Value Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Return the un-expanded value of a variable.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Eval-Function" accesskey="9">Eval Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Evaluate the arguments as makefile syntax.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Origin-Function">Origin Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Find where a variable got its value.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Flavor-Function">Flavor Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Find out the flavor of a variable.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Make-Control-Functions">Make Control Functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Functions that control how make runs.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Shell-Function">Shell Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Substitute the output of a shell command.
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Guile-Function">Guile Function</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Use GNU Guile embedded scripting language.
</td></tr>
</table>

<hr>
<a name="Syntax-of-Functions"></a>
<div class="header">
<p>
Next: <a href="#Text-Functions" accesskey="n" rel="next">Text Functions</a>, Previous: <a href="#Functions" accesskey="p" rel="prev">Functions</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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="Function-Call-Syntax"></a>
<h3 class="section">8.1 Function Call Syntax</h3>
<a name="index-_0024_002c-in-function-call"></a>
<a name="index-dollar-sign-_0028_0024_0029_002c-in-function-call"></a>
<a name="index-arguments-of-functions"></a>
<a name="index-functions_002c-syntax-of"></a>

<p>A function call resembles a variable reference.  It can appear
anywhere a variable reference can appear, and it is expanded using the
same rules as variable references.  A function call looks like this:
</p>
<div class="example">
<pre class="example">$(<var>function</var> <var>arguments</var>)
</pre></div>

<p>or like this:
</p>
<div class="example">
<pre class="example">${<var>function</var> <var>arguments</var>}
</pre></div>

<p>Here <var>function</var> is a function name; one of a short list of names
that are part of <code>make</code>.  You can also essentially create your own
functions by using the <code>call</code> built-in function.
</p>
<p>The <var>arguments</var> are the arguments of the function.  They are
separated from the function name by one or more spaces or tabs, and if
there is more than one argument, then they are separated by commas.
Such whitespace and commas are not part of an argument&rsquo;s value.  The
delimiters which you use to surround the function call, whether
parentheses or braces, can appear in an argument only in matching pairs;
the other kind of delimiters may appear singly.  If the arguments
themselves contain other function calls or variable references, it is
wisest to use the same kind of delimiters for all the references; write
&lsquo;<samp>$(subst&nbsp;a,b,$(x))</samp>&rsquo;<!-- /@w -->, not &lsquo;<samp>$(subst&nbsp;a,b,${x})</samp>&rsquo;<!-- /@w -->.  This
is because it is clearer, and because only one type of delimiter is
matched to find the end of the reference.
</p>
<p>The text written for each argument is processed by substitution of
variables and function calls to produce the argument value, which
is the text on which the function acts.  The substitution is done in the
order in which the arguments appear.
</p>
<p>Commas and unmatched parentheses or braces cannot appear in the text of an
argument as written; leading spaces cannot appear in the text of the first
argument as written.  These characters can be put into the argument value
by variable substitution.  First define variables <code>comma</code> and
<code>space</code> whose values are isolated comma and space characters, then
substitute these variables where such characters are wanted, like this:
</p>
<div class="example">
<pre class="example">comma:= ,
empty:=
space:= $(empty) $(empty)
foo:= a b c
bar:= $(subst $(space),$(comma),$(foo))
# <span class="roman">bar is now &lsquo;a,b,c&rsquo;.</span>
</pre></div>

<p>Here the <code>subst</code> function replaces each space with a comma, through
the value of <code>foo</code>, and substitutes the result.
</p>
<hr>
<a name="Text-Functions"></a>
<div class="header">
<p>
Next: <a href="#File-Name-Functions" accesskey="n" rel="next">File Name Functions</a>, Previous: <a href="#Syntax-of-Functions" accesskey="p" rel="prev">Syntax of Functions</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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="Functions-for-String-Substitution-and-Analysis"></a>
<h3 class="section">8.2 Functions for String Substitution and Analysis</h3>
<a name="index-functions_002c-for-text"></a>

<p>Here are some functions that operate on strings:
</p>
<dl compact="compact">
<dt><code>$(subst <var>from</var>,<var>to</var>,<var>text</var>)</code></dt>
<dd><a name="index-subst-1"></a>
<p>Performs a textual replacement on the text <var>text</var>: each occurrence
of <var>from</var> is replaced by <var>to</var>.  The result is substituted for
the function call.  For example,
</p>
<div class="example">
<pre class="example">$(subst ee,EE,feet on the street)
</pre></div>

<p>substitutes the string &lsquo;<samp>fEEt on the strEEt</samp>&rsquo;.
</p>
</dd>
<dt><code>$(patsubst <var>pattern</var>,<var>replacement</var>,<var>text</var>)</code></dt>
<dd><a name="index-patsubst-1"></a>
<p>Finds whitespace-separated words in <var>text</var> that match
<var>pattern</var> and replaces them with <var>replacement</var>.  Here
<var>pattern</var> may contain a &lsquo;<samp>%</samp>&rsquo; which acts as a wildcard,
matching any number of any characters within a word.  If
<var>replacement</var> also contains a &lsquo;<samp>%</samp>&rsquo;, the &lsquo;<samp>%</samp>&rsquo; is replaced
by the text that matched the &lsquo;<samp>%</samp>&rsquo; in <var>pattern</var>.  Only the first
&lsquo;<samp>%</samp>&rsquo; in the <var>pattern</var> and <var>replacement</var> is treated this
way; any subsequent &lsquo;<samp>%</samp>&rsquo; is unchanged.
</p>
<a name="index-_0025_002c-quoting-in-patsubst"></a>
<a name="index-_0025_002c-quoting-with-_005c-_0028backslash_0029-2"></a>
<a name="index-_005c-_0028backslash_0029_002c-to-quote-_0025-2"></a>
<a name="index-backslash-_0028_005c_0029_002c-to-quote-_0025-2"></a>
<a name="index-quoting-_0025_002c-in-patsubst"></a>
<p>&lsquo;<samp>%</samp>&rsquo; characters in <code>patsubst</code> function invocations can be
quoted with preceding backslashes (&lsquo;<samp>\</samp>&rsquo;).  Backslashes that would
otherwise quote &lsquo;<samp>%</samp>&rsquo; characters can be quoted with more backslashes.
Backslashes that quote &lsquo;<samp>%</samp>&rsquo; characters or other backslashes are
removed from the pattern before it is compared file names or has a stem
substituted into it.  Backslashes that are not in danger of quoting
&lsquo;<samp>%</samp>&rsquo; characters go unmolested.  For example, the pattern
<samp>the\%weird\\%pattern\\</samp> has &lsquo;<samp>the%weird\</samp>&rsquo; preceding the
operative &lsquo;<samp>%</samp>&rsquo; character, and &lsquo;<samp>pattern\\</samp>&rsquo; following it.  The
final two backslashes are left alone because they cannot affect any
&lsquo;<samp>%</samp>&rsquo; character.
</p>
<p>Whitespace between words is folded into single space characters;
leading and trailing whitespace is discarded.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">$(patsubst %.c,%.o,x.c.c bar.c)
</pre></div>

<p>produces the value &lsquo;<samp>x.c.o bar.o</samp>&rsquo;.
</p>
<p>Substitution references (see <a href="Using-Variables.html#Substitution-Refs">Substitution
References</a>) are a simpler way to get the effect of the <code>patsubst</code>
function:
</p>
<div class="example">
<pre class="example">$(<var>var</var>:<var>pattern</var>=<var>replacement</var>)
</pre></div>

<p>is equivalent to
</p>
<div class="example">
<pre class="example">$(patsubst <var>pattern</var>,<var>replacement</var>,$(<var>var</var>))
</pre></div>

<p>The second shorthand simplifies one of the most common uses of
<code>patsubst</code>: replacing the suffix at the end of file names.
</p>
<div class="example">
<pre class="example">$(<var>var</var>:<var>suffix</var>=<var>replacement</var>)
</pre></div>

<p>is equivalent to
</p>
<div class="example">
<pre class="example">$(patsubst %<var>suffix</var>,%<var>replacement</var>,$(<var>var</var>))
</pre></div>

<p>For example, you might have a list of object files:
</p>
<div class="example">
<pre class="example">objects = foo.o bar.o baz.o
</pre></div>

<p>To get the list of corresponding source files, you could simply write:
</p>
<div class="example">
<pre class="example">$(objects:.o=.c)
</pre></div>

<p>instead of using the general form:
</p>
<div class="example">
<pre class="example">$(patsubst %.o,%.c,$(objects))
</pre></div>

</dd>
<dt><code>$(strip <var>string</var>)</code></dt>
<dd><a name="index-stripping-whitespace"></a>
<a name="index-whitespace_002c-stripping"></a>
<a name="index-spaces_002c-stripping"></a>
<a name="index-strip"></a>
<p>Removes leading and trailing whitespace from <var>string</var> and replaces
each internal sequence of one or more whitespace characters with a
single space.  Thus, &lsquo;<samp>$(strip a b  c )</samp>&rsquo; results in &lsquo;<samp>a&nbsp;b&nbsp;c</samp>&rsquo;<!-- /@w -->.
</p>
<p>The function <code>strip</code> can be very useful when used in conjunction
with conditionals.  When comparing something with the empty string
&lsquo;<samp></samp>&rsquo; using <code>ifeq</code> or <code>ifneq</code>, you usually want a string of
just whitespace to match the empty string (see <a href="Conditionals.html#Conditionals">Conditionals</a>).
</p>
<p>Thus, the following may fail to have the desired results:
</p>
<div class="example">
<pre class="example">.PHONY: all
ifneq   &quot;$(needs_made)&quot; &quot;&quot;
all: $(needs_made)
else
all:;@echo 'Nothing to make!'
endif
</pre></div>

<p>Replacing the variable reference &lsquo;<samp><span class="nolinebreak">$(needs_made)</span></samp>&rsquo;<!-- /@w --> with the
function call &lsquo;<samp>$(strip&nbsp;<span class="nolinebreak">$(needs_made))</span></samp>&rsquo;<!-- /@w --> in the <code>ifneq</code>
directive would make it more robust.
</p>
</dd>
<dt><code>$(findstring <var>find</var>,<var>in</var>)</code></dt>
<dd><a name="index-findstring"></a>
<a name="index-searching-for-strings"></a>
<a name="index-finding-strings"></a>
<a name="index-strings_002c-searching-for"></a>
<p>Searches <var>in</var> for an occurrence of <var>find</var>.  If it occurs, the
value is <var>find</var>; otherwise, the value is empty.  You can use this
function in a conditional to test for the presence of a specific
substring in a given string.  Thus, the two examples,
</p>
<div class="example">
<pre class="example">$(findstring a,a b c)
$(findstring a,b c)
</pre></div>

<p>produce the values &lsquo;<samp>a</samp>&rsquo; and &lsquo;<samp></samp>&rsquo; (the empty string),
respectively.  See <a href="Conditionals.html#Testing-Flags">Testing Flags</a>, for a practical application of
<code>findstring</code>.
</p>
<a name="index-filter"></a>
<a name="index-filtering-words"></a>
<a name="index-words_002c-filtering"></a>
</dd>
<dt><code>$(filter <var>pattern</var>&hellip;,<var>text</var>)</code></dt>
<dd><p>Returns all whitespace-separated words in <var>text</var> that <em>do</em> match
any of the <var>pattern</var> words, removing any words that <em>do not</em>
match.  The patterns are written using &lsquo;<samp>%</samp>&rsquo;, just like the patterns
used in the <code>patsubst</code> function above.
</p>
<p>The <code>filter</code> function can be used to separate out different types
of strings (such as file names) in a variable.  For example:
</p>
<div class="example">
<pre class="example">sources := foo.c bar.c baz.s ugh.h
foo: $(sources)
        cc $(filter %.c %.s,$(sources)) -o foo
</pre></div>

<p>says that <samp>foo</samp> depends of <samp>foo.c</samp>, <samp>bar.c</samp>,
<samp>baz.s</samp> and <samp>ugh.h</samp> but only <samp>foo.c</samp>, <samp>bar.c</samp> and
<samp>baz.s</samp> should be specified in the command to the
compiler.
</p>
</dd>
<dt><code>$(filter-out <var>pattern</var>&hellip;,<var>text</var>)</code></dt>
<dd><a name="index-filter_002dout"></a>
<a name="index-filtering-out-words"></a>
<a name="index-words_002c-filtering-out"></a>
<p>Returns all whitespace-separated words in <var>text</var> that <em>do not</em>
match any of the <var>pattern</var> words, removing the words that <em>do</em>
match one or more.  This is the exact opposite of the <code>filter</code>
function.
</p>
<p>For example, given:
</p>
<div class="example">
<pre class="example">objects=main1.o foo.o main2.o bar.o
mains=main1.o main2.o
</pre></div>

<p>the following generates a list which contains all the object files not
in &lsquo;<samp>mains</samp>&rsquo;:
</p>
<div class="example">
<pre class="example">$(filter-out $(mains),$(objects))
</pre></div>

<a name="index-sort"></a>
<a name="index-sorting-words"></a>
</dd>
<dt><code>$(sort <var>list</var>)</code></dt>
<dd><p>Sorts the words of <var>list</var> in lexical order, removing duplicate
words.  The output is a list of words separated by single spaces.
Thus,
</p>
<div class="example">
<pre class="example">$(sort foo bar lose)
</pre></div>

<p>returns the value &lsquo;<samp>bar foo lose</samp>&rsquo;.
</p>
<a name="index-removing-duplicate-words"></a>
<a name="index-duplicate-words_002c-removing"></a>
<a name="index-words_002c-removing-duplicates"></a>
<p>Incidentally, since <code>sort</code> removes duplicate words, you can use
it for this purpose even if you don&rsquo;t care about the sort order.
</p>
</dd>
<dt><code>$(word <var>n</var>,<var>text</var>)</code></dt>
<dd><a name="index-word"></a>
<a name="index-word_002c-selecting-a"></a>
<a name="index-selecting-a-word"></a>
<p>Returns the <var>n</var>th word of <var>text</var>.  The legitimate values of
<var>n</var> start from 1.  If <var>n</var> is bigger than the number of words
in <var>text</var>, the value is empty.  For example,
</p>
<div class="example">
<pre class="example">$(word 2, foo bar baz)
</pre></div>

<p>returns &lsquo;<samp>bar</samp>&rsquo;.
</p>
</dd>
<dt><code>$(wordlist <var>s</var>,<var>e</var>,<var>text</var>)</code></dt>
<dd><a name="index-wordlist"></a>
<a name="index-words_002c-selecting-lists-of"></a>
<a name="index-selecting-word-lists"></a>
<p>Returns the list of words in <var>text</var> starting with word <var>s</var> and
ending with word <var>e</var> (inclusive).  The legitimate values of <var>s</var>
start from 1; <var>e</var> may start from 0.  If <var>s</var> is bigger than the
number of words in <var>text</var>, the value is empty.  If <var>e</var> is
bigger than the number of words in <var>text</var>, words up to the end of
<var>text</var> are returned.  If <var>s</var> is greater than <var>e</var>, nothing
is returned.  For example,
</p>
<div class="example">
<pre class="example">$(wordlist 2, 3, foo bar baz)
</pre></div>

<p>returns &lsquo;<samp>bar baz</samp>&rsquo;.
</p>
</dd>
<dt><code>$(words <var>text</var>)</code></dt>
<dd><a name="index-words"></a>
<a name="index-words_002c-finding-number"></a>
<p>Returns the number of words in <var>text</var>.
Thus, the last word of <var>text</var> is
<code>$(word&nbsp;$(words&nbsp;<var>text</var>),<var>text</var>)</code><!-- /@w -->.
</p>
</dd>
<dt><code>$(firstword <var>names</var>&hellip;)</code></dt>
<dd><a name="index-firstword"></a>
<a name="index-words_002c-extracting-first"></a>
<p>The argument <var>names</var> is regarded as a series of names, separated
by whitespace.  The value is the first name in the series.  The rest
of the names are ignored.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">$(firstword foo bar)
</pre></div>

<p>produces the result &lsquo;<samp>foo</samp>&rsquo;.  Although <code>$(firstword
<var>text</var>)</code> is the same as <code>$(word 1,<var>text</var>)</code>, the
<code>firstword</code> function is retained for its simplicity.
</p>

</dd>
<dt><code>$(lastword <var>names</var>&hellip;)</code></dt>
<dd><a name="index-lastword"></a>
<a name="index-words_002c-extracting-last"></a>
<p>The argument <var>names</var> is regarded as a series of names, separated
by whitespace.  The value is the last name in the series.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">$(lastword foo bar)
</pre></div>

<p>produces the result &lsquo;<samp>bar</samp>&rsquo;.  Although <code>$(lastword
<var>text</var>)</code> is the same as <code>$(word $(words <var>text</var>),<var>text</var>)</code>,
the <code>lastword</code> function was added for its simplicity and better
performance.
</p></dd>
</dl>


<p>Here is a realistic example of the use of <code>subst</code> and
<code>patsubst</code>.  Suppose that a makefile uses the <code>VPATH</code> variable
to specify a list of directories that <code>make</code> should search for
prerequisite files
(see <a href="Rules.html#General-Search"><code>VPATH</code> Search Path for All Prerequisites</a>).
This example shows how to
tell the C compiler to search for header files in the same list of
directories.
</p>
<p>The value of <code>VPATH</code> is a list of directories separated by colons,
such as &lsquo;<samp>src:../headers</samp>&rsquo;.  First, the <code>subst</code> function is used to
change the colons to spaces:
</p>
<div class="example">
<pre class="example">$(subst :, ,$(VPATH))
</pre></div>

<p>This produces &lsquo;<samp>src ../headers</samp>&rsquo;.  Then <code>patsubst</code> is used to turn
each directory name into a &lsquo;<samp>-I</samp>&rsquo; flag.  These can be added to the
value of the variable <code>CFLAGS</code>, which is passed automatically to the C
compiler, like this:
</p>
<div class="example">
<pre class="example">override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
</pre></div>

<p>The effect is to append the text &lsquo;<samp>-Isrc -I../headers</samp>&rsquo; to the
previously given value of <code>CFLAGS</code>.  The <code>override</code> directive is
used so that the new value is assigned even if the previous value of
<code>CFLAGS</code> was specified with a command argument (see <a href="Using-Variables.html#Override-Directive">The <code>override</code> Directive</a>).
</p>
<hr>
<a name="File-Name-Functions"></a>
<div class="header">
<p>
Next: <a href="#Conditional-Functions" accesskey="n" rel="next">Conditional Functions</a>, Previous: <a href="#Text-Functions" accesskey="p" rel="prev">Text Functions</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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="Functions-for-File-Names"></a>
<h3 class="section">8.3 Functions for File Names</h3>
<a name="index-functions_002c-for-file-names"></a>
<a name="index-file-name-functions"></a>

<p>Several of the built-in expansion functions relate specifically to
taking apart file names or lists of file names.
</p>
<p>Each of the following functions performs a specific transformation on a
file name.  The argument of the function is regarded as a series of file
names, separated by whitespace.  (Leading and trailing whitespace is
ignored.)  Each file name in the series is transformed in the same way and
the results are concatenated with single spaces between them.
</p>
<dl compact="compact">
<dt><code>$(dir <var>names</var>&hellip;)</code></dt>
<dd><a name="index-dir"></a>
<a name="index-directory-part"></a>
<a name="index-file-name_002c-directory-part"></a>
<p>Extracts the directory-part of each file name in <var>names</var>.  The
directory-part of the file name is everything up through (and
including) the last slash in it.  If the file name contains no slash,
the directory part is the string &lsquo;<samp>./</samp>&rsquo;.  For example,
</p>
<div class="example">
<pre class="example">$(dir src/foo.c hacks)
</pre></div>

<p>produces the result &lsquo;<samp>src/ ./</samp>&rsquo;.
</p>
</dd>
<dt><code>$(notdir <var>names</var>&hellip;)</code></dt>
<dd><a name="index-notdir"></a>
<a name="index-file-name_002c-nondirectory-part"></a>
<a name="index-nondirectory-part"></a>
<p>Extracts all but the directory-part of each file name in <var>names</var>.
If the file name contains no slash, it is left unchanged.  Otherwise,
everything through the last slash is removed from it.
</p>
<p>A file name that ends with a slash becomes an empty string.  This is
unfortunate, because it means that the result does not always have the
same number of whitespace-separated file names as the argument had;
but we do not see any other valid alternative.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">$(notdir src/foo.c hacks)
</pre></div>

<p>produces the result &lsquo;<samp>foo.c hacks</samp>&rsquo;.
</p>
</dd>
<dt><code>$(suffix <var>names</var>&hellip;)</code></dt>
<dd><a name="index-suffix"></a>
<a name="index-suffix_002c-function-to-find"></a>
<a name="index-file-name-suffix"></a>
<p>Extracts the suffix of each file name in <var>names</var>.  If the file name
contains a period, the suffix is everything starting with the last
period.  Otherwise, the suffix is the empty string.  This frequently
means that the result will be empty when <var>names</var> is not, and if
<var>names</var> contains multiple file names, the result may contain fewer
file names.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">$(suffix src/foo.c src-1.0/bar.c hacks)
</pre></div>

<p>produces the result &lsquo;<samp>.c .c</samp>&rsquo;.
</p>
</dd>
<dt><code>$(basename <var>names</var>&hellip;)</code></dt>
<dd><a name="index-basename-1"></a>
<a name="index-basename"></a>
<a name="index-file-name_002c-basename-of"></a>
<p>Extracts all but the suffix of each file name in <var>names</var>.  If the
file name contains a period, the basename is everything starting up to
(and not including) the last period.  Periods in the directory part are
ignored.  If there is no period, the basename is the entire file name.
For example,
</p>
<div class="example">
<pre class="example">$(basename src/foo.c src-1.0/bar hacks)
</pre></div>

<p>produces the result &lsquo;<samp>src/foo src-1.0/bar hacks</samp>&rsquo;.
</p>
</dd>
<dt><code>$(addsuffix <var>suffix</var>,<var>names</var>&hellip;)</code></dt>
<dd><a name="index-addsuffix"></a>
<a name="index-suffix_002c-adding"></a>
<a name="index-file-name-suffix_002c-adding"></a>
<p>The argument <var>names</var> is regarded as a series of names, separated
by whitespace; <var>suffix</var> is used as a unit.  The value of
<var>suffix</var> is appended to the end of each individual name and the
resulting larger names are concatenated with single spaces between
them.  For example,
</p>
<div class="example">
<pre class="example">$(addsuffix .c,foo bar)
</pre></div>

<p>produces the result &lsquo;<samp>foo.c bar.c</samp>&rsquo;.
</p>
</dd>
<dt><code>$(addprefix <var>prefix</var>,<var>names</var>&hellip;)</code></dt>
<dd><a name="index-addprefix"></a>
<a name="index-prefix_002c-adding"></a>
<a name="index-file-name-prefix_002c-adding"></a>
<p>The argument <var>names</var> is regarded as a series of names, separated
by whitespace; <var>prefix</var> is used as a unit.  The value of
<var>prefix</var> is prepended to the front of each individual name and the
resulting larger names are concatenated with single spaces between
them.  For example,
</p>
<div class="example">
<pre class="example">$(addprefix src/,foo bar)
</pre></div>

<p>produces the result &lsquo;<samp>src/foo src/bar</samp>&rsquo;.
</p>
</dd>
<dt><code>$(join <var>list1</var>,<var>list2</var>)</code></dt>
<dd><a name="index-join"></a>
<a name="index-joining-lists-of-words"></a>
<a name="index-words_002c-joining-lists"></a>
<p>Concatenates the two arguments word by word: the two first words (one
from each argument) concatenated form the first word of the result, the
two second words form the second word of the result, and so on.  So the
<var>n</var>th word of the result comes from the <var>n</var>th word of each
argument.  If one argument has more words that the other, the extra
words are copied unchanged into the result.
</p>
<p>For example, &lsquo;<samp>$(join a b,.c .o)</samp>&rsquo; produces &lsquo;<samp>a.c b.o</samp>&rsquo;.
</p>
<p>Whitespace between the words in the lists is not preserved; it is
replaced with a single space.
</p>
<p>This function can merge the results of the <code>dir</code> and
<code>notdir</code> functions, to produce the original list of files which
was given to those two functions.
</p>
</dd>
<dt><code>$(wildcard <var>pattern</var>)</code></dt>
<dd><a name="index-wildcard-2"></a>
<a name="index-wildcard_002c-function"></a>
<p>The argument <var>pattern</var> is a file name pattern, typically containing
wildcard characters (as in shell file name patterns).  The result of
<code>wildcard</code> is a space-separated list of the names of existing files
that match the pattern.
See <a href="Rules.html#Wildcards">Using Wildcard Characters in File Names</a>.
</p>
</dd>
<dt><code>$(realpath <var>names</var>&hellip;)</code></dt>
<dd><a name="index-realpath-1"></a>
<a name="index-realpath"></a>
<a name="index-file-name_002c-realpath-of"></a>
<p>For each file name in <var>names</var> return the canonical absolute name.
A canonical name does not contain any <code>.</code> or <code>..</code> components,
nor any repeated path separators (<code>/</code>) or symlinks.  In case of a
failure the empty string is returned.  Consult the <code>realpath(3)</code>
documentation for a list of possible failure causes.
</p>
</dd>
<dt><code>$(abspath <var>names</var>&hellip;)</code></dt>
<dd><a name="index-abspath-1"></a>
<a name="index-abspath"></a>
<a name="index-file-name_002c-abspath-of"></a>
<p>For each file name in <var>names</var> return an absolute name that does
not contain any <code>.</code> or <code>..</code> components, nor any repeated path
separators (<code>/</code>).  Note that, in contrast to <code>realpath</code>
function, <code>abspath</code> does not resolve symlinks and does not require
the file names to refer to an existing file or directory.  Use the
<code>wildcard</code> function to test for existence.
</p></dd>
</dl>

<hr>
<a name="Conditional-Functions"></a>
<div class="header">
<p>
Next: <a href="#Foreach-Function" accesskey="n" rel="next">Foreach Function</a>, Previous: <a href="#File-Name-Functions" accesskey="p" rel="prev">File Name Functions</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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="Functions-for-Conditionals"></a>
<h3 class="section">8.4 Functions for Conditionals</h3>
<a name="index-if"></a>
<a name="index-conditional-expansion"></a>
<p>There are three functions that provide conditional expansion.  A key
aspect of these functions is that not all of the arguments are
expanded initially.  Only those arguments which need to be expanded,
will be expanded.
</p>
<dl compact="compact">
<dt><code>$(if <var>condition</var>,<var>then-part</var>[,<var>else-part</var>])</code></dt>
<dd><a name="index-if-1"></a>
<p>The <code>if</code> function provides support for conditional expansion in a
functional context (as opposed to the GNU <code>make</code> makefile
conditionals such as <code>ifeq</code> (see <a href="Conditionals.html#Conditional-Syntax">Syntax of
Conditionals</a>).
</p>
<p>The first argument, <var>condition</var>, first has all preceding and
trailing whitespace stripped, then is expanded.  If it expands to any
non-empty string, then the condition is considered to be true.  If it
expands to an empty string, the condition is considered to be false.
</p>
<p>If the condition is true then the second argument, <var>then-part</var>, is
evaluated and this is used as the result of the evaluation of the entire
<code>if</code> function.
</p>
<p>If the condition is false then the third argument, <var>else-part</var>, is
evaluated and this is the result of the <code>if</code> function.  If there is
no third argument, the <code>if</code> function evaluates to nothing (the
empty string).
</p>
<p>Note that only one of the <var>then-part</var> or the <var>else-part</var> will be
evaluated, never both.  Thus, either can contain side-effects (such as
<code>shell</code> function calls, etc.)
</p>
</dd>
<dt><code>$(or <var>condition1</var>[,<var>condition2</var>[,<var>condition3</var>&hellip;]])</code></dt>
<dd><a name="index-or"></a>
<p>The <code>or</code> function provides a &ldquo;short-circuiting&rdquo; OR operation.
Each argument is expanded, in order.  If an argument expands to a
non-empty string the processing stops and the result of the expansion
is that string.  If, after all arguments are expanded, all of them are
false (empty), then the result of the expansion is the empty string.
</p>
</dd>
<dt><code>$(and <var>condition1</var>[,<var>condition2</var>[,<var>condition3</var>&hellip;]])</code></dt>
<dd><a name="index-and"></a>
<p>The <code>and</code> function provides a &ldquo;short-circuiting&rdquo; AND operation.
Each argument is expanded, in order.  If an argument expands to an
empty string the processing stops and the result of the expansion is
the empty string.  If all arguments expand to a non-empty string then
the result of the expansion is the expansion of the last argument.
</p>
</dd>
</dl>

<hr>
<a name="Foreach-Function"></a>
<div class="header">
<p>
Next: <a href="#File-Function" accesskey="n" rel="next">File Function</a>, Previous: <a href="#Conditional-Functions" accesskey="p" rel="prev">Conditional Functions</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-foreach-Function"></a>
<h3 class="section">8.5 The <code>foreach</code> Function</h3>
<a name="index-foreach"></a>
<a name="index-words_002c-iterating-over"></a>

<p>The <code>foreach</code> function is very different from other functions.  It
causes one piece of text to be used repeatedly, each time with a different
substitution performed on it.  It resembles the <code>for</code> command in the
shell <code>sh</code> and the <code>foreach</code> command in the C-shell <code>csh</code>.
</p>
<p>The syntax of the <code>foreach</code> function is:
</p>
<div class="example">
<pre class="example">$(foreach <var>var</var>,<var>list</var>,<var>text</var>)
</pre></div>

<p>The first two arguments, <var>var</var> and <var>list</var>, are expanded before
anything else is done; note that the last argument, <var>text</var>, is
<strong>not</strong> expanded at the same time.  Then for each word of the expanded
value of <var>list</var>, the variable named by the expanded value of <var>var</var>
is set to that word, and <var>text</var> is expanded.  Presumably <var>text</var>
contains references to that variable, so its expansion will be different
each time.
</p>
<p>The result is that <var>text</var> is expanded as many times as there are
whitespace-separated words in <var>list</var>.  The multiple expansions of
<var>text</var> are concatenated, with spaces between them, to make the result
of <code>foreach</code>.
</p>
<p>This simple example sets the variable &lsquo;<samp>files</samp>&rsquo; to the list of all files
in the directories in the list &lsquo;<samp>dirs</samp>&rsquo;:
</p>
<div class="example">
<pre class="example">dirs := a b c d
files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
</pre></div>

<p>Here <var>text</var> is &lsquo;<samp>$(wildcard $(dir)/*)</samp>&rsquo;.  The first repetition
finds the value &lsquo;<samp>a</samp>&rsquo; for <code>dir</code>, so it produces the same result
as &lsquo;<samp>$(wildcard a/*)</samp>&rsquo;; the second repetition produces the result
of &lsquo;<samp>$(wildcard b/*)</samp>&rsquo;; and the third, that of &lsquo;<samp>$(wildcard c/*)</samp>&rsquo;.
</p>
<p>This example has the same result (except for setting &lsquo;<samp>dirs</samp>&rsquo;) as
the following example:
</p>
<div class="example">
<pre class="example">files := $(wildcard a/* b/* c/* d/*)
</pre></div>

<p>When <var>text</var> is complicated, you can improve readability by giving it
a name, with an additional variable:
</p>
<div class="example">
<pre class="example">find_files = $(wildcard $(dir)/*)
dirs := a b c d
files := $(foreach dir,$(dirs),$(find_files))
</pre></div>

<p>Here we use the variable <code>find_files</code> this way.  We use plain &lsquo;<samp>=</samp>&rsquo;
to define a recursively-expanding variable, so that its value contains an
actual function call to be re-expanded under the control of <code>foreach</code>;
a simply-expanded variable would not do, since <code>wildcard</code> would be
called only once at the time of defining <code>find_files</code>.
</p>
<p>The <code>foreach</code> function has no permanent effect on the variable
<var>var</var>; its value and flavor after the <code>foreach</code> function call are
the same as they were beforehand.  The other values which are taken from
<var>list</var> are in effect only temporarily, during the execution of
<code>foreach</code>.  The variable <var>var</var> is a simply-expanded variable
during the execution of <code>foreach</code>.  If <var>var</var> was undefined
before the <code>foreach</code> function call, it is undefined after the call.
See <a href="Using-Variables.html#Flavors">The Two Flavors of Variables</a>.
</p>
<p>You must take care when using complex variable expressions that result in
variable names because many strange things are valid variable names, but
are probably not what you intended.  For example,
</p>
<div class="smallexample">
<pre class="smallexample">files := $(foreach Esta-escrito-en-espanol!,b c ch,$(find_files))
</pre></div>

<p>might be useful if the value of <code>find_files</code> references the variable
whose name is &lsquo;<samp>Esta-escrito-en-espanol!</samp>&rsquo; (es un nombre bastante largo,
no?), but it is more likely to be a mistake.
</p>
<hr>
<a name="File-Function"></a>
<div class="header">
<p>
Next: <a href="#Call-Function" accesskey="n" rel="next">Call Function</a>, Previous: <a href="#Foreach-Function" accesskey="p" rel="prev">Foreach Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-file-Function"></a>
<h3 class="section">8.6 The <code>file</code> Function</h3>
<a name="index-file"></a>
<a name="index-writing-to-a-file"></a>
<a name="index-file_002c-writing-to"></a>
<a name="index-reading-from-a-file"></a>
<a name="index-file_002c-reading-from"></a>

<p>The <code>file</code> function allows the makefile to write to or read from
a file.  Two modes of writing are supported: overwrite, where the text
is written to the beginning of the file and any existing content is
lost, and append, where the text is written to the end of the file,
preserving the existing content.  In both cases the file is created if
it does not exist.  It is a fatal error if the file cannot be opened
for writing, or if the write operation fails.  The <code>file</code>
function expands to the empty string when writing to a file.
</p>
<p>When reading from a file, the <code>file</code> function expands to the
verbatim contents of the file, except that the final newline (if there
is one) will be stripped.  Attempting to read from a non-existent file
expands to the empty string.
</p>
<p>The syntax of the <code>file</code> function is:
</p>
<div class="example">
<pre class="example">$(file <var>op</var> <var>filename</var>[,<var>text</var>])
</pre></div>

<p>When the <code>file</code> function is evaluated all its arguments are
expanded first, then the file indicated by <var>filename</var> will be
opened in the mode described by <var>op</var>.
</p>
<p>The operator <var>op</var> can be <code>&gt;</code> to indicate the file will be
overwritten with new content, <code>&gt;&gt;</code> to indicate the current
contents of the file will be appended to, or <code>&lt;</code> to indicate the
contents of the file will be read in.  The <var>filename</var> specifies
the file to be written to or read from.  There may optionally be
whitespace between the operator and the file name.
</p>
<p>When reading files, it is an error to provide a <var>text</var> value.
</p>
<p>When writing files, <var>text</var> will be written to the file.  If
<var>text</var> does not already end in a newline a final newline will be
written (even if <var>text</var> is the empty string).  If the <var>text</var>
argument is not given at all, nothing will be written.
</p>
<p>For example, the <code>file</code> function can be useful if your build
system has a limited command line size and your recipe runs a command
that can accept arguments from a file as well.  Many commands use the
convention that an argument prefixed with an <code>@</code> specifies a
file containing more arguments.  Then you might write your recipe in
this way:
</p>
<div class="example">
<pre class="example">program: $(OBJECTS)
        $(file &gt;$@.in,$^)
        $(CMD) $(CMDFLAGS) @$@.in
        @rm $@.in
</pre></div>

<p>If the command required each argument to be on a separate line of the
input file, you might write your recipe like this:
</p>
<div class="example">
<pre class="example">program: $(OBJECTS)
        $(file &gt;$@.in) $(foreach O,$^,$(file &gt;&gt;$@.in,$O))
        $(CMD) $(CMDFLAGS) @$@.in
        @rm $@.in
</pre></div>

<hr>
<a name="Call-Function"></a>
<div class="header">
<p>
Next: <a href="#Value-Function" accesskey="n" rel="next">Value Function</a>, Previous: <a href="#File-Function" accesskey="p" rel="prev">File Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-call-Function"></a>
<h3 class="section">8.7 The <code>call</code> Function</h3>
<a name="index-call"></a>
<a name="index-functions_002c-user-defined"></a>
<a name="index-user-defined-functions"></a>

<p>The <code>call</code> function is unique in that it can be used to create new
parameterized functions.  You can write a complex expression as the
value of a variable, then use <code>call</code> to expand it with different
values.
</p>
<p>The syntax of the <code>call</code> function is:
</p>
<div class="example">
<pre class="example">$(call <var>variable</var>,<var>param</var>,<var>param</var>,&hellip;)
</pre></div>

<p>When <code>make</code> expands this function, it assigns each <var>param</var> to
temporary variables <code>$(1)</code>, <code>$(2)</code>, etc.  The variable
<code>$(0)</code> will contain <var>variable</var>.  There is no maximum number of
parameter arguments.  There is no minimum, either, but it doesn&rsquo;t make
sense to use <code>call</code> with no parameters.
</p>
<p>Then <var>variable</var> is expanded as a <code>make</code> variable in the context
of these temporary assignments.  Thus, any reference to <code>$(1)</code> in
the value of <var>variable</var> will resolve to the first <var>param</var> in the
invocation of <code>call</code>.
</p>
<p>Note that <var>variable</var> is the <em>name</em> of a variable, not a
<em>reference</em> to that variable.  Therefore you would not normally use
a &lsquo;<samp>$</samp>&rsquo; or parentheses when writing it.  (You can, however, use a
variable reference in the name if you want the name not to be a
constant.)
</p>
<p>If <var>variable</var> is the name of a built-in function, the built-in function
is always invoked (even if a <code>make</code> variable by that name also
exists).
</p>
<p>The <code>call</code> function expands the <var>param</var> arguments before
assigning them to temporary variables.  This means that <var>variable</var>
values containing references to built-in functions that have special
expansion rules, like <code>foreach</code> or <code>if</code>, may not work as you
expect.
</p>
<p>Some examples may make this clearer.
</p>
<p>This macro simply reverses its arguments:
</p>
<div class="smallexample">
<pre class="smallexample">reverse = $(2) $(1)

foo = $(call reverse,a,b)
</pre></div>

<p>Here <var>foo</var> will contain &lsquo;<samp>b a</samp>&rsquo;.
</p>
<p>This one is slightly more interesting: it defines a macro to search for
the first instance of a program in <code>PATH</code>:
</p>
<div class="smallexample">
<pre class="smallexample">pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))

LS := $(call pathsearch,ls)
</pre></div>

<p>Now the variable LS contains <code>/bin/ls</code> or similar.
</p>
<p>The <code>call</code> function can be nested.  Each recursive invocation gets
its own local values for <code>$(1)</code>, etc. that mask the values of
higher-level <code>call</code>.  For example, here is an implementation of a
<em>map</em> function:
</p>
<div class="smallexample">
<pre class="smallexample">map = $(foreach a,$(2),$(call $(1),$(a)))
</pre></div>

<p>Now you can <var>map</var> a function that normally takes only one argument,
such as <code>origin</code>, to multiple values in one step:
</p>
<div class="smallexample">
<pre class="smallexample">o = $(call map,origin,o map MAKE)
</pre></div>

<p>and end up with <var>o</var> containing something like &lsquo;<samp>file file default</samp>&rsquo;.
</p>
<p>A final caution: be careful when adding whitespace to the arguments to
<code>call</code>.  As with other functions, any whitespace contained in the
second and subsequent arguments is kept; this can cause strange
effects.  It&rsquo;s generally safest to remove all extraneous whitespace when
providing parameters to <code>call</code>.
</p>
<hr>
<a name="Value-Function"></a>
<div class="header">
<p>
Next: <a href="#Eval-Function" accesskey="n" rel="next">Eval Function</a>, Previous: <a href="#Call-Function" accesskey="p" rel="prev">Call Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-value-Function"></a>
<h3 class="section">8.8 The <code>value</code> Function</h3>
<a name="index-value-1"></a>
<a name="index-variables_002c-unexpanded-value"></a>

<p>The <code>value</code> function provides a way for you to use the value of a
variable <em>without</em> having it expanded.  Please note that this
does not undo expansions which have already occurred; for example if
you create a simply expanded variable its value is expanded during the
definition; in that case the <code>value</code> function will return the
same result as using the variable directly.
</p>
<p>The syntax of the <code>value</code> function is:
</p>
<div class="example">
<pre class="example">$(value <var>variable</var>)
</pre></div>

<p>Note that <var>variable</var> is the <em>name</em> of a variable, not a
<em>reference</em> to that variable.  Therefore you would not normally
use a &lsquo;<samp>$</samp>&rsquo; or parentheses when writing it.  (You can, however, use
a variable reference in the name if you want the name not to be a
constant.)
</p>
<p>The result of this function is a string containing the value of
<var>variable</var>, without any expansion occurring.  For example, in this
makefile:
</p>
<div class="example">
<pre class="example">FOO = $PATH

all:
        @echo $(FOO)
        @echo $(value FOO)
</pre></div>

<p>The first output line would be <code>ATH</code>, since the &ldquo;$P&rdquo; would be
expanded as a <code>make</code> variable, while the second output line would
be the current value of your <code>$PATH</code> environment variable, since
the <code>value</code> function avoided the expansion.
</p>
<p>The <code>value</code> function is most often used in conjunction with the
<code>eval</code> function (see <a href="#Eval-Function">Eval Function</a>).
</p>
<hr>
<a name="Eval-Function"></a>
<div class="header">
<p>
Next: <a href="#Origin-Function" accesskey="n" rel="next">Origin Function</a>, Previous: <a href="#Value-Function" accesskey="p" rel="prev">Value Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-eval-Function"></a>
<h3 class="section">8.9 The <code>eval</code> Function</h3>
<a name="index-eval"></a>
<a name="index-evaluating-makefile-syntax"></a>
<a name="index-makefile-syntax_002c-evaluating"></a>

<p>The <code>eval</code> function is very special: it allows you to define new
makefile constructs that are not constant; which are the result of
evaluating other variables and functions.  The argument to the
<code>eval</code> function is expanded, then the results of that expansion
are parsed as makefile syntax.  The expanded results can define new
<code>make</code> variables, targets, implicit or explicit rules, etc.
</p>
<p>The result of the <code>eval</code> function is always the empty string;
thus, it can be placed virtually anywhere in a makefile without
causing syntax errors.
</p>
<p>It&rsquo;s important to realize that the <code>eval</code> argument is expanded
<em>twice</em>; first by the <code>eval</code> function, then the results of
that expansion are expanded again when they are parsed as makefile
syntax.  This means you may need to provide extra levels of escaping
for &ldquo;$&rdquo; characters when using <code>eval</code>.  The <code>value</code>
function (see <a href="#Value-Function">Value Function</a>) can sometimes be useful in these
situations, to circumvent unwanted expansions.
</p>
<p>Here is an example of how <code>eval</code> can be used; this example
combines a number of concepts and other functions.  Although it might
seem overly complex to use <code>eval</code> in this example, rather than
just writing out the rules, consider two things: first, the template
definition (in <code>PROGRAM_template</code>) could need to be much more
complex than it is here; and second, you might put the complex,
&ldquo;generic&rdquo; part of this example into another makefile, then include
it in all the individual makefiles.  Now your individual makefiles are
quite straightforward.
</p>
<div class="example">
<pre class="example">PROGRAMS    = server client

server_OBJS = server.o server_priv.o server_access.o
server_LIBS = priv protocol

client_OBJS = client.o client_api.o client_mem.o
client_LIBS = protocol

# Everything after this is generic

.PHONY: all
all: $(PROGRAMS)

define PROGRAM_template =
 $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
 ALL_OBJS   += $$($(1)_OBJS)
endef

$(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))

$(PROGRAMS):
        $(LINK.o) $^ $(LDLIBS) -o $@

clean:
        rm -f $(ALL_OBJS) $(PROGRAMS)
</pre></div>

<hr>
<a name="Origin-Function"></a>
<div class="header">
<p>
Next: <a href="#Flavor-Function" accesskey="n" rel="next">Flavor Function</a>, Previous: <a href="#Eval-Function" accesskey="p" rel="prev">Eval Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-origin-Function"></a>
<h3 class="section">8.10 The <code>origin</code> Function</h3>
<a name="index-origin"></a>
<a name="index-variables_002c-origin-of"></a>
<a name="index-origin-of-variable"></a>

<p>The <code>origin</code> function is unlike most other functions in that it does
not operate on the values of variables; it tells you something <em>about</em>
a variable.  Specifically, it tells you where it came from.
</p>
<p>The syntax of the <code>origin</code> function is:
</p>
<div class="example">
<pre class="example">$(origin <var>variable</var>)
</pre></div>

<p>Note that <var>variable</var> is the <em>name</em> of a variable to inquire about,
not a <em>reference</em> to that variable.  Therefore you would not normally
use a &lsquo;<samp>$</samp>&rsquo; or parentheses when writing it.  (You can, however, use a
variable reference in the name if you want the name not to be a constant.)
</p>
<p>The result of this function is a string telling you how the variable
<var>variable</var> was defined:
</p>
<dl compact="compact">
<dt>&lsquo;<samp>undefined</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> was never defined.
</p>
</dd>
<dt>&lsquo;<samp>default</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> has a default definition, as is usual with <code>CC</code>
and so on.  See <a href="Implicit-Rules.html#Implicit-Variables">Variables Used by Implicit Rules</a>.
Note that if you have redefined a default variable, the <code>origin</code>
function will return the origin of the later definition.
</p>
</dd>
<dt>&lsquo;<samp>environment</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> was inherited from the environment provided to
<code>make</code>.
</p>
</dd>
<dt>&lsquo;<samp>environment override</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> was inherited from the environment provided to
<code>make</code>, and is overriding a setting for <var>variable</var> in the
makefile as a result of the &lsquo;<samp><span class="nolinebreak">-e</span></samp>&rsquo;<!-- /@w --> option (see <a href="Running.html#Options-Summary">Summary of Options</a>).
</p>
</dd>
<dt>&lsquo;<samp>file</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> was defined in a makefile.
</p>
</dd>
<dt>&lsquo;<samp>command line</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> was defined on the command line.
</p>
</dd>
<dt>&lsquo;<samp>override</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> was defined with an <code>override</code> directive in a
makefile (see <a href="Using-Variables.html#Override-Directive">The <code>override</code> Directive</a>).
</p>
</dd>
<dt>&lsquo;<samp>automatic</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> is an automatic variable defined for the execution
of the recipe for each rule (see <a href="Implicit-Rules.html#Automatic-Variables">Automatic Variables</a>).
</p></dd>
</dl>

<p>This information is primarily useful (other than for your curiosity) to
determine if you want to believe the value of a variable.  For example,
suppose you have a makefile <samp>foo</samp> that includes another makefile
<samp>bar</samp>.  You want a variable <code>bletch</code> to be defined in <samp>bar</samp>
if you run the command &lsquo;<samp>make&nbsp;<span class="nolinebreak">-f</span>&nbsp;bar</samp>&rsquo;<!-- /@w -->, even if the environment contains
a definition of <code>bletch</code>.  However, if <samp>foo</samp> defined
<code>bletch</code> before including <samp>bar</samp>, you do not want to override that
definition.  This could be done by using an <code>override</code> directive in
<samp>foo</samp>, giving that definition precedence over the later definition in
<samp>bar</samp>; unfortunately, the <code>override</code> directive would also
override any command line definitions.  So, <samp>bar</samp> could
include:
</p>
<div class="example">
<pre class="example">ifdef bletch
ifeq &quot;$(origin bletch)&quot; &quot;environment&quot;
bletch = barf, gag, etc.
endif
endif
</pre></div>

<p>If <code>bletch</code> has been defined from the environment, this will redefine
it.
</p>
<p>If you want to override a previous definition of <code>bletch</code> if it came
from the environment, even under &lsquo;<samp>-e</samp>&rsquo;, you could instead write:
</p>
<div class="example">
<pre class="example">ifneq &quot;$(findstring environment,$(origin bletch))&quot; &quot;&quot;
bletch = barf, gag, etc.
endif
</pre></div>

<p>Here the redefinition takes place if &lsquo;<samp>$(origin bletch)</samp>&rsquo; returns either
&lsquo;<samp>environment</samp>&rsquo; or &lsquo;<samp>environment override</samp>&rsquo;.
See <a href="#Text-Functions">Functions for String Substitution and Analysis</a>.
</p>
<hr>
<a name="Flavor-Function"></a>
<div class="header">
<p>
Next: <a href="#Make-Control-Functions" accesskey="n" rel="next">Make Control Functions</a>, Previous: <a href="#Origin-Function" accesskey="p" rel="prev">Origin Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-flavor-Function"></a>
<h3 class="section">8.11 The <code>flavor</code> Function</h3>
<a name="index-flavor"></a>
<a name="index-variables_002c-flavor-of"></a>
<a name="index-flavor-of-variable"></a>

<p>The <code>flavor</code> function, like the <code>origin</code> function, does not
operate on the values of variables but rather it tells you something
<em>about</em> a variable.  Specifically, it tells you the flavor of a
variable (see <a href="Using-Variables.html#Flavors">The Two Flavors of Variables</a>).
</p>
<p>The syntax of the <code>flavor</code> function is:
</p>
<div class="example">
<pre class="example">$(flavor <var>variable</var>)
</pre></div>

<p>Note that <var>variable</var> is the <em>name</em> of a variable to inquire about,
not a <em>reference</em> to that variable.  Therefore you would not normally
use a &lsquo;<samp>$</samp>&rsquo; or parentheses when writing it.  (You can, however, use a
variable reference in the name if you want the name not to be a constant.)
</p>
<p>The result of this function is a string that identifies the flavor of the
variable <var>variable</var>:
</p>
<dl compact="compact">
<dt>&lsquo;<samp>undefined</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> was never defined.
</p>
</dd>
<dt>&lsquo;<samp>recursive</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> is a recursively expanded variable.
</p>
</dd>
<dt>&lsquo;<samp>simple</samp>&rsquo;</dt>
<dd>
<p>if <var>variable</var> is a simply expanded variable.
</p>
</dd>
</dl>

<hr>
<a name="Make-Control-Functions"></a>
<div class="header">
<p>
Next: <a href="#Shell-Function" accesskey="n" rel="next">Shell Function</a>, Previous: <a href="#Flavor-Function" accesskey="p" rel="prev">Flavor Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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="Functions-That-Control-Make"></a>
<h3 class="section">8.12 Functions That Control Make</h3>
<a name="index-functions_002c-for-controlling-make"></a>
<a name="index-controlling-make"></a>

<p>These functions control the way make runs.  Generally, they are used to
provide information to the user of the makefile or to cause make to stop
if some sort of environmental error is detected.
</p>
<dl compact="compact">
<dt><code>$(error <var>text</var>&hellip;)</code></dt>
<dd><a name="index-error"></a>
<a name="index-error_002c-stopping-on"></a>
<a name="index-stopping-make"></a>
<p>Generates a fatal error where the message is <var>text</var>.  Note that
the error is generated whenever this function is evaluated.  So, if
you put it inside a recipe or on the right side of a recursive
variable assignment, it won&rsquo;t be evaluated until later.  The
<var>text</var> will be expanded before the error is generated.
</p>
<p>For example,
</p>
<div class="example">
<pre class="example">ifdef ERROR1
$(error error is $(ERROR1))
endif
</pre></div>

<p>will generate a fatal error during the read of the makefile if the
<code>make</code> variable <code>ERROR1</code> is defined.  Or,
</p>
<div class="example">
<pre class="example">ERR = $(error found an error!)

.PHONY: err
err: ; $(ERR)
</pre></div>

<p>will generate a fatal error while <code>make</code> is running, if the
<code>err</code> target is invoked.
</p>
</dd>
<dt><code>$(warning <var>text</var>&hellip;)</code></dt>
<dd><a name="index-warning"></a>
<a name="index-warnings_002c-printing"></a>
<a name="index-printing-user-warnings"></a>
<p>This function works similarly to the <code>error</code> function, above,
except that <code>make</code> doesn&rsquo;t exit.  Instead, <var>text</var> is expanded
and the resulting message is displayed, but processing of the makefile
continues.
</p>
<p>The result of the expansion of this function is the empty string.
</p>
</dd>
<dt><code>$(info <var>text</var>&hellip;)</code></dt>
<dd><a name="index-info"></a>
<a name="index-printing-messages"></a>
<p>This function does nothing more than print its (expanded) argument(s)
to standard output.  No makefile name or line number is added.  The
result of the expansion of this function is the empty string.
</p></dd>
</dl>

<hr>
<a name="Shell-Function"></a>
<div class="header">
<p>
Next: <a href="#Guile-Function" accesskey="n" rel="next">Guile Function</a>, Previous: <a href="#Make-Control-Functions" accesskey="p" rel="prev">Make Control Functions</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-shell-Function"></a>
<h3 class="section">8.13 The <code>shell</code> Function</h3>
<a name="index-shell"></a>
<a name="index-command-expansion"></a>
<a name="index-backquotes"></a>
<a name="index-shell-command_002c-function-for"></a>

<p>The <code>shell</code> function is unlike any other function other than the
<code>wildcard</code> function
(see <a href="Rules.html#Wildcard-Function">The Function <code>wildcard</code></a>) in that it
communicates with the world outside of <code>make</code>.
</p>
<p>The <code>shell</code> function performs the same function that backquotes
(&lsquo;<samp>`</samp>&rsquo;) perform in most shells: it does <em>command expansion</em>.
This means that it takes as an argument a shell command and evaluates
to the output of the command.  The only processing <code>make</code> does on
the result is to convert each newline (or carriage-return / newline
pair) to a single space.  If there is a trailing (carriage-return
and) newline it will simply be removed.
</p>
<p>The commands run by calls to the <code>shell</code> function are run when the
function calls are expanded (see <a href="Makefiles.html#Reading-Makefiles">How
<code>make</code> Reads a Makefile</a>).  Because this function involves
spawning a new shell, you should carefully consider the performance
implications of using the <code>shell</code> function within recursively
expanded variables vs. simply expanded variables (see <a href="Using-Variables.html#Flavors">The
Two Flavors of Variables</a>).
</p>
<a name="index-_002eSHELLSTATUS"></a>
<p>After the <code>shell</code> function or &lsquo;<samp>!=</samp>&rsquo; assignment operator is
used, its exit status is placed in the <code>.SHELLSTATUS</code> variable.
</p>
<p>Here are some examples of the use of the <code>shell</code> function:
</p>
<div class="example">
<pre class="example">contents := $(shell cat foo)
</pre></div>

<p>sets <code>contents</code> to the contents of the file <samp>foo</samp>, with a space
(rather than a newline) separating each line.
</p>
<div class="example">
<pre class="example">files := $(shell echo *.c)
</pre></div>

<p>sets <code>files</code> to the expansion of &lsquo;<samp>*.c</samp>&rsquo;.  Unless <code>make</code> is
using a very strange shell, this has the same result as
&lsquo;<samp>$(wildcard&nbsp;*.c)</samp>&rsquo;<!-- /@w --> (as long as at least one &lsquo;<samp>.c</samp>&rsquo; file
exists).
</p>
<hr>
<a name="Guile-Function"></a>
<div class="header">
<p>
Previous: <a href="#Shell-Function" accesskey="p" rel="prev">Shell Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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-guile-Function"></a>
<h3 class="section">8.14 The <code>guile</code> Function</h3>
<a name="index-guile"></a>
<a name="index-Guile"></a>

<p>If GNU <code>make</code> is built with support for GNU Guile as an embedded
extension language then the <code>guile</code> function will be available.
The <code>guile</code> function takes one argument which is first expanded
by <code>make</code> in the normal fashion, then passed to the GNU Guile
evaluator.  The result of the evaluator is converted into a string and
used as the expansion of the <code>guile</code> function in the makefile.
See <a href="Extending-make.html#Guile-Integration">GNU Guile Integration</a> for details on
writing extensions to <code>make</code> in Guile.
</p>
<p>You can determine whether GNU Guile support is available by checking
the <code>.FEATURES</code> variable for the word <var>guile</var>.
</p>
<hr>
<div class="header">
<p>
Previous: <a href="#Shell-Function" accesskey="p" rel="prev">Shell Function</a>, Up: <a href="#Functions" accesskey="u" rel="up">Functions</a> &nbsp; [<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>