|
|
1.1 ! root 1: .TH USGMAKE 1 ! 2: .SH NAME ! 3: usgmake \- maintain, update, and regenerate groups of programs ! 4: .SH SYNOPSIS ! 5: .B usgmake ! 6: .RB ! 7: [ ! 8: .I \-f " makefile ! 9: ] ! 10: .I " ! 11: .RB ! 12: [ ! 13: .I \-p ! 14: ] ! 15: .RB ! 16: [ ! 17: .I \-i ! 18: ] ! 19: .RB ! 20: [ ! 21: .I \-k ! 22: ] ! 23: .RB ! 24: [ ! 25: .I \-s ! 26: ] ! 27: .RB ! 28: [ ! 29: .I \-r ! 30: ] ! 31: .RB ! 32: [ ! 33: .I \-n ! 34: ] ! 35: .RB ! 36: [ ! 37: .I \-b ! 38: ] ! 39: .RB ! 40: [ ! 41: .I \-e ! 42: ] ! 43: .RB ! 44: [ ! 45: .I \-m ! 46: ] ! 47: .RB ! 48: [ ! 49: .I \-t ! 50: ] ! 51: .RB ! 52: [ ! 53: .I \-d ! 54: ] ! 55: .RB ! 56: [ ! 57: .I \-q ! 58: ] ! 59: [ ! 60: .I \|names\| ! 61: ] ! 62: .SH DESCRIPTION ! 63: The following is a brief description of all options and some special ! 64: names: ! 65: .TP "\w'\f3\-f\fP makefile\ \ 'u" ! 66: .BI \-f " makefile\^" ! 67: Description file name. ! 68: .I Makefile\^ ! 69: is assumed to ! 70: be the name of a description file. ! 71: A file name of ! 72: .B \- ! 73: denotes the standard input. ! 74: The contents of ! 75: .I makefile\^ ! 76: override the built-in rules if they ! 77: are present. ! 78: .TP ! 79: .B \-p ! 80: Print out the complete set of macro definitions and target descriptions. ! 81: .TP ! 82: .B \-i ! 83: Ignore error codes returned by invoked commands. ! 84: This ! 85: mode is entered if the fake target name ! 86: .B \&.\s-1IGNORE\s+1 ! 87: appears in the description file. ! 88: .TP ! 89: .B \-k ! 90: Abandon work on the current ! 91: entry, but continue on other branches ! 92: that do not depend on that entry. ! 93: .TP ! 94: .B \-s ! 95: Silent mode. ! 96: Do not print command lines before executing. ! 97: This mode is also entered if the fake target name ! 98: .B \&.\s-1SILENT\s+1 ! 99: appears in the description file. ! 100: .TP ! 101: .B \-r ! 102: Do not use the built-in rules. ! 103: .TP ! 104: .B \-n ! 105: No execute mode. ! 106: Print commands, but do not execute ! 107: them. ! 108: Even lines beginning with an ! 109: .B @ ! 110: are printed. ! 111: .TP ! 112: .B \-b ! 113: Compatibility mode for old makefiles. ! 114: .TP ! 115: .B \-e ! 116: Environment variables override assignments within makefiles. ! 117: .TP ! 118: .B \-m ! 119: Print a memory map showing text, data, and stack. ! 120: This option ! 121: is a no-operation on systems without the \f2getu\^\fP system call. ! 122: .TP ! 123: .B \-t ! 124: Touch the target files (causing them to be up-to-date) ! 125: rather than issue the usual commands. ! 126: .TP ! 127: .B \-d ! 128: Debug mode. ! 129: Print out detailed information on files ! 130: and times examined. ! 131: .TP ! 132: .B \-q ! 133: Question. ! 134: The \f2make\^\fP command returns a zero or non-zero ! 135: status code depending on whether the target file is or ! 136: is not up-to-date. ! 137: .TP ! 138: .B \&.\s-1DEFAULT\s+1 ! 139: If a file must be made but there are no explicit commands ! 140: or relevant built-in rules, the commands associated ! 141: with the name ! 142: .B \&.\s-1DEFAULT\s+1 ! 143: are used if it exists. ! 144: .TP ! 145: .B \&.\s-1PRECIOUS\s+1 ! 146: Dependents of this target will not be removed when ! 147: quit or interrupt are hit. ! 148: .TP ! 149: .B \&.\s-1SILENT\s+1 ! 150: Same effect as the \f3\-s\fP option. ! 151: .TP ! 152: .B \&.\s-1IGNORE\s+1 ! 153: Same effect as the \f3\-i\fP option. ! 154: .PP ! 155: .I Make\^ ! 156: executes commands in ! 157: .I makefile\^ ! 158: to update ! 159: one or more target ! 160: .IR names . ! 161: .I Name\^ ! 162: is typically a program. ! 163: If no ! 164: .B \-f ! 165: option is present, \f3makefile\fP, \f3Makefile\fP, \f3s.makefile\fP, ! 166: and \f3s.Makefile\fP are ! 167: tried in order. ! 168: If ! 169: .I makefile\^ ! 170: is ! 171: .BR \- , ! 172: the standard input is taken. ! 173: More than one ! 174: .BI \- " makefile" ! 175: argument pair may appear. ! 176: .PP ! 177: .I Make\^ ! 178: updates a target only if it depends on files that are ! 179: newer than the target. ! 180: All prerequisite files of a target are added recursively to ! 181: the list of targets. ! 182: Missing files are deemed to be out of date. ! 183: .PP ! 184: .I Makefile\^ ! 185: contains a sequence of entries that specify dependencies. ! 186: The first line of an entry is a ! 187: blank-separated, non-null list of targets, then a ! 188: .BR : , ! 189: then a (possibly null) list of prerequisite files or dependencies. ! 190: Text following a ! 191: .B ; ! 192: and all following lines ! 193: that begin with a tab are shell commands ! 194: to be executed to update the target. ! 195: The first line that does not begin with a tab or ! 196: .B # ! 197: begins ! 198: a new dependency or macro definition. ! 199: Shell commands may ! 200: be continued across lines with the <backslash><new-line> sequence. ! 201: Everything printed by make (except the initial tab) is passed ! 202: directly to the shell as is. ! 203: Thus, ! 204: .PP ! 205: .ss 18 ! 206: .RS ! 207: .PD 0 ! 208: echo a\\ ! 209: .br ! 210: b ! 211: .RE ! 212: .ss 12 ! 213: .PD ! 214: .PP ! 215: will produce ! 216: .PP ! 217: .ss 18 ! 218: .RS ! 219: .PD 0 ! 220: ab ! 221: .RE ! 222: .ss 12 ! 223: .PD ! 224: .PP ! 225: exactly the same as the shell would. ! 226: .PP ! 227: Sharp ! 228: .RB ( # ) ! 229: and new-line surround comments. ! 230: .PP ! 231: The following ! 232: .I makefile\^ ! 233: says that ! 234: .B pgm ! 235: depends on two ! 236: files ! 237: .B a.o ! 238: and ! 239: .BR b.o , ! 240: and that they in turn depend on ! 241: their corresponding source files ! 242: .RB ( a.c ! 243: and ! 244: .BR b.c ) ! 245: and a common file ! 246: .BR incl.h : ! 247: .PP ! 248: .ss 18 ! 249: .RS ! 250: .PD 0 ! 251: .TP ! 252: pgm: a.o b.o ! 253: cc a.o b.o \-o pgm ! 254: .TP ! 255: a.o: incl.h a.c ! 256: cc \-c a.c ! 257: .TP ! 258: b.o: incl.h b.c ! 259: cc \-c b.c ! 260: .PD ! 261: .RE ! 262: .ss 12 ! 263: .PP ! 264: Command lines are executed one at a time, each by its ! 265: own shell. ! 266: The first one or two characters in a command can be ! 267: the following: \f3-\fP, \f3@\fP, \f3-@\fP, or \f3@-\fP. ! 268: If \f3@\fP is present, printing of the command is suppressed. ! 269: If \f3-\fP is present, \f2make\^\fP ignores an error. ! 270: A line is printed when it is executed unless the ! 271: .B \-s ! 272: option is present, or the entry ! 273: .B \&.\s-1SILENT\s+1: ! 274: is in ! 275: .IR makefile , ! 276: or unless the initial character sequence contains a \f3@\fP. ! 277: The ! 278: .B \-n ! 279: option specifies printing without execution; however, if the ! 280: command line has the string ! 281: .B $(\s-1MAKE\s+1) ! 282: in it, ! 283: the line is ! 284: always executed (see discussion of the ! 285: .SM ! 286: .B MAKEFLAGS ! 287: macro under ! 288: .IR Environment ). ! 289: The ! 290: .B \-t ! 291: (touch) option updates the modified date of a ! 292: file without executing any commands. ! 293: .PP ! 294: Commands returning non-zero status normally terminate ! 295: .IR make . ! 296: If the ! 297: .B \-i ! 298: option is present, or the entry \f3.\s-1IGNORE\s+1:\fP appears in ! 299: .IR makefile , ! 300: or the initial character sequence of the command contains ! 301: \f3-\fP. ! 302: the error is ignored. ! 303: If the ! 304: .B \-k ! 305: option is present, ! 306: work is abandoned on the current ! 307: entry, but continues on other branches ! 308: that do not depend on that entry. ! 309: .PP ! 310: The ! 311: .B \-b ! 312: option allows old makefiles (those written for the old version ! 313: of \f2make\^\fP) to run without errors. ! 314: The difference between the old version ! 315: of \f2make\^\fP and this version is that this version requires all dependency ! 316: lines to have a (possibly null or implicit) command associated with them. ! 317: The previous version of ! 318: .I make\^ ! 319: assumed if no command was specified explicitly ! 320: that the command was null. ! 321: .PP ! 322: Interrupt and quit cause the target to be deleted ! 323: unless the target is a dependency of the special name \f3.\s-1PRECIOUS\s+1\fP. ! 324: .SS Environment ! 325: The environment is read by \f2make\^\fP. ! 326: All variables are assumed to be macro ! 327: definitions and processed as such. ! 328: The environment variables are processed ! 329: before any makefile and after the internal rules; ! 330: thus, macro assignments ! 331: in a makefile override environment variables. ! 332: The ! 333: .B \-e ! 334: option causes ! 335: the environment to override the macro assignments in a makefile. ! 336: .PP ! 337: The \f3\s-1MAKEFLAGS\s+1\fP environment variable ! 338: is processed by \f2make\^\fP as containing ! 339: any legal input option (except \f3\-f\fP, \f3\-p\fP, and \f3\-d\fP) defined ! 340: for the command line. ! 341: Further, ! 342: upon invocation, \f2make\^\fP ``invents'' the variable if it is not in the ! 343: environment, puts the current options into it, and passes it on to ! 344: invocations of commands. ! 345: Thus, \f3\s-1MAKEFLAGS\s+1\fP always contains the ! 346: current input options. ! 347: This proves very useful for ``super-makes''. ! 348: In fact, as noted above, ! 349: when the \f3\-n\fP option is used, the command ! 350: .B $(\s-1MAKE\s+1) ! 351: is executed ! 352: anyway; hence, one can perform a \f3make \-n\fP recursively on a whole software ! 353: system to see what would have been executed. ! 354: This is because the \f3\-n\fP ! 355: is put in \f3\s-1MAKEFLAGS\s+1\fP and passed to further invocations of ! 356: .BR $(\s-1MAKE\s+1) . ! 357: This is one way of debugging ! 358: all of the makefiles for a software project without actually doing anything. ! 359: .PP ! 360: .SS Macros ! 361: Entries of the form ! 362: .IB string1 " = " string2\^ ! 363: are macro definitions. ! 364: .I String2 ! 365: is defined as all characters up to a comment character or ! 366: an unescaped newline. ! 367: Subsequent appearances of ! 368: .RI $( string1 [: subst1 =[ subst2\^\fP]]) ! 369: are replaced by ! 370: .IR string2 . ! 371: The parentheses are optional if a single character macro name is used and ! 372: there is no substitute sequence. ! 373: The optional ! 374: .RI : subst1 = subst2\^ ! 375: is a substitute sequence. ! 376: If it is specified, all non-overlapping occurrences of \f2subst1\^\fP in the ! 377: named macro are replaced by \f2subst2\^\fP. ! 378: Strings (for the purposes of this ! 379: type of substitution) are delimited by ! 380: blanks, tabs, new-line characters, and beginnings of lines. ! 381: An example of the use of the substitute sequence is shown under ! 382: .IR Libraries . ! 383: .SS Internal Macros ! 384: There are five internally maintained macros which are useful ! 385: for writing rules for building targets. ! 386: .TP 5 ! 387: \f3$\(**\fP ! 388: The macro \f3$\(**\fP stands for ! 389: the file name part of the current dependent with the suffix deleted. ! 390: It is ! 391: evaluated only for inference rules. ! 392: .TP ! 393: \f3$@\fP ! 394: The \f3$@\fP macro stands for ! 395: the full target name of the current target. ! 396: It is evaluated ! 397: only for explicitly named dependencies. ! 398: .TP ! 399: \f3$<\fP ! 400: The \f3$<\fP macro is only evaluated for inference rules or ! 401: the \f3.\s-1DEFAULT\s+1\fP rule. ! 402: It is ! 403: the module which is out of date with respect to the target (i.e., ! 404: the ``manufactured'' dependent file name). ! 405: Thus, in the \f3.c.o\fP rule, the \f3$<\fP macro would evaluate to ! 406: the \f3.c\fP file. ! 407: An example for making ! 408: optimized \f3.o\fP files from \f3.c\fP files is: ! 409: .PP ! 410: .PD 0 ! 411: .ss 18 ! 412: .RS ! 413: .RS ! 414: .TP ! 415: \&.c.o: ! 416: .br ! 417: cc \-c \-O $\(**.c ! 418: .RE ! 419: .RE ! 420: .PD ! 421: .TP 5 ! 422: \& ! 423: or: ! 424: .PP ! 425: .PD 0 ! 426: .RS ! 427: .RS ! 428: .TP ! 429: \&.c.o: ! 430: .br ! 431: cc \-c \-O $< ! 432: .RE ! 433: .RE ! 434: .ss 12 ! 435: .PD ! 436: .TP 5 ! 437: \f3$?\fP ! 438: The \f3$?\fP macro is evaluated when explicit rules from the makefile ! 439: are evaluated. ! 440: It is ! 441: the list of prerequisites that are out of date with respect to ! 442: the target; ! 443: essentially, those modules which must be rebuilt. ! 444: .TP ! 445: \f3$%\fP ! 446: The \f3$%\fP macro is only evaluated when the target is an ! 447: archive library member of the form \f3lib(file.o)\fP. ! 448: In this case, ! 449: \f3$@\fP evaluates to \f3lib\fP and \f3$%\fP evaluates to the ! 450: library member, \f3file.o\fP. ! 451: .PP ! 452: Four of the five macros can have alternative forms. ! 453: When an upper case \f3D\fP or \f3F\fP is appended to any of the four ! 454: macros the meaning is changed to ``directory part'' for \f3D\fP ! 455: and ``file part'' for \f3F\fP. ! 456: Thus, \f3$(@D)\fP refers to the directory ! 457: part of the string \f3$@\fP. ! 458: If there is no directory part, ! 459: \f3./\fP is generated. ! 460: The only macro excluded from this ! 461: alternative form is \f3$?\fP. ! 462: The reasons for this are debatable. ! 463: .SS Suffixes ! 464: Certain names (for instance, those ending with \f3.o\fP) ! 465: have inferable prerequisites such as \f3.c\fP, \f3.s\fP, etc. ! 466: If no update commands for such a file appear in ! 467: .IR makefile , ! 468: and if an inferable prerequisite ! 469: exists, that prerequisite is compiled to make the target. ! 470: In this case, ! 471: .I make\^ ! 472: has ! 473: inference rules ! 474: which allow building files from other files ! 475: by examining the suffixes and determining an ! 476: appropriate ! 477: inference rule ! 478: to use. ! 479: The current default inference rules ! 480: are: ! 481: .PP ! 482: .RS ! 483: \&.c \|.c~ \|.sh \|.sh~ \|.c.o \|.c~.o \|.c~.c \|.s.o \|.s~.o \|.y.o \|.y~.o \|.l.o \|.l~.o ! 484: .br ! 485: \&.y.c \|.y~.c \|.l.c \|.c.a \|.c~.a \|.s~.a \|.h~.h ! 486: .RE ! 487: .PP ! 488: The internal rules for \f2make\^\fP are contained in the source ! 489: file \f3rules.c\fP for the \f2make\^\fP program. ! 490: These rules can be ! 491: locally modified. ! 492: To print out the rules compiled into ! 493: the \f2make\^\fP on any machine in a form suitable for recompilation, ! 494: the following command is used: ! 495: .PP ! 496: .RS ! 497: make \|\-fp \|\- \|2>/dev/null \|</dev/null ! 498: .RE ! 499: .PP ! 500: The only peculiarity in this output is the ! 501: .B (null) ! 502: string which ! 503: .IR printf (3S) ! 504: prints when handed a null string. ! 505: .PP ! 506: A tilde in the above rules refers to an \s-1SCCS\s+1 file ! 507: (see ! 508: .IR sccsfile (5)). ! 509: Thus, the ! 510: rule \f3.c~.o\fP would transform an \s-1SCCS\s+1 C source file into an ! 511: object file (\f3.o\fP). ! 512: Because the \f3s.\fP of the \s-1SCCS\s+1 files is a prefix ! 513: it is incompatible with \f2make\^\fP's suffix point-of-view. ! 514: Hence, ! 515: the tilde is a way of changing any file reference into an \s-1SCCS\s+1 ! 516: file reference. ! 517: .PP ! 518: A rule with only one suffix (i.e. \f3.c:\fP) is the definition ! 519: of how to build \f2x\^\fP from \f2x\^\fP\f3.c\fP. ! 520: In effect, the other suffix is null. ! 521: This is useful for building targets ! 522: from only one source file (e.g., shell procedures, simple C programs). ! 523: .PP ! 524: Additional suffixes are given as the ! 525: dependency list for \f3.\s-1SUFFIXES\s+1\fP. ! 526: Order is significant; the first possible name for which both ! 527: a file and a rule exist is inferred as a prerequisite. ! 528: The default list is: ! 529: .PP ! 530: .RS ! 531: \&\f3.\s-1SUFFIXES\s+1\fP: \|.o \|.c \|.y \|.l \|.s ! 532: .RE ! 533: .PP ! 534: Here again, the above command for printing the internal rules will ! 535: display the list of suffixes implemented on the current machine. ! 536: Multiple suffix lists accumulate; \f3.\s-1SUFFIXES\s+1:\fP with no dependencies ! 537: clears the list of suffixes. ! 538: .SS Inference Rules ! 539: The first example can be done more briefly: ! 540: .PP ! 541: .ss 18 ! 542: .RS ! 543: .PD 0 ! 544: .TP ! 545: pgm: a.o b.o ! 546: .br ! 547: cc a.o b.o \-o pgm ! 548: .TP ! 549: a.o b.o: incl.h ! 550: .RE ! 551: .ss 12 ! 552: .PD ! 553: .PP ! 554: This is because \f2make\^\fP has a set of internal rules for building ! 555: files. ! 556: The user may add rules to this list by simply putting ! 557: them in the \f2makefile\^\fP. ! 558: .PP ! 559: Certain macros are used by the default inference rules ! 560: to permit the inclusion of optional matter in ! 561: any resulting commands. ! 562: For example, ! 563: .SM ! 564: .BR CFLAGS\*S , ! 565: .SM ! 566: .BR LFLAGS\*S , ! 567: and ! 568: .SM ! 569: .B YFLAGS ! 570: are used for compiler options to ! 571: .IR cc (1), ! 572: .IR lex (1), ! 573: and ! 574: .IR yacc (1) ! 575: respectively. ! 576: Again, the previous method for examining ! 577: the current rules is recommended. ! 578: .PP ! 579: The inference of prerequisites can be controlled. ! 580: The rule to create a file with suffix ! 581: .B \&.o ! 582: from a file with suffix ! 583: .B \&.c ! 584: is specified as an entry with \f3.c.o:\fP as the target and no dependents. ! 585: Shell commands associated with the target define the ! 586: rule for making a \f3.o\fP file from a \f3.c\fP file. ! 587: Any target that has no slashes in it and starts with a dot ! 588: is identified as a rule and not a true target. ! 589: .SS Libraries ! 590: If a target or dependency name contains parenthesis, it is ! 591: assumed to be an archive library, the string within parenthesis ! 592: referring to a member within the library. ! 593: Thus \f3lib(file.o)\fP and \f3$(\s-1LIB\s+1)(file.o)\fP both refer to ! 594: an archive library which contains \f3file.o\fP. (This assumes ! 595: the ! 596: .SM ! 597: .B LIB ! 598: macro has been previously defined.)\ ! 599: The expression \f3$(\s-1LIB\s+1)(file1.o file2.o)\fP is not legal. ! 600: Rules pertaining to archive libraries have the form ! 601: .BI \&. \s-1XX\s+1 .a ! 602: where the ! 603: .SM ! 604: .I XX\^ ! 605: is the suffix from which the archive member ! 606: is to be made. ! 607: An unfortunate byproduct of the current implementation ! 608: requires the ! 609: .SM ! 610: .I XX\^ ! 611: to be different from the suffix of the archive ! 612: member. ! 613: Thus, one cannot have \f3lib(file.o)\fP depend upon \f3file.o\fP explicitly. ! 614: The most common use of the archive interface follows. ! 615: Here, we assume the source files are all C type source: ! 616: .PP ! 617: .ss 18 ! 618: .RS ! 619: .PD 0 ! 620: .TP ! 621: lib: ! 622: lib(file1.o) lib(file2.o) lib(file3.o) ! 623: .br ! 624: @echo lib is now up to date ! 625: .TP ! 626: \&.c.a: ! 627: .br ! 628: $(\s-1CC\s+1) \-c $(\s-1CFLAGS\s+1) $< ! 629: .br ! 630: ar rv $@ $*.o ! 631: .br ! 632: rm \-f $*.o ! 633: .RE ! 634: .ss 12 ! 635: .PD ! 636: .PP ! 637: In fact, the \f3.c.a\fP rule listed above is built into \f2make\^\fP and ! 638: is unnecessary in this example. ! 639: A more interesting, but more limited example of an archive library ! 640: maintenance construction follows: ! 641: .PP ! 642: .ss 18 ! 643: .RS ! 644: .PD 0 ! 645: .TP ! 646: lib: ! 647: lib(file1.o) lib(file2.o) lib(file3.o) ! 648: .br ! 649: $(\s-1CC\s+1) \-c $(\s-1CFLAGS\s+1) $(?:.o=.c) ! 650: .br ! 651: ar rv lib $? ! 652: .br ! 653: rm $? ! 654: @echo lib is now up to date ! 655: .TP ! 656: \&.c.a:; ! 657: .RE ! 658: .ss 12 ! 659: .PD ! 660: .PP ! 661: Here the substitution mode of the macro expansions is used. ! 662: The \f3$?\fP ! 663: list is defined to be the set of object file names (inside \f3lib\fP) whose C ! 664: source files are out of date. ! 665: The substitution mode ! 666: translates the \f3.o\fP to \f3.c\fP. ! 667: (Unfortunately, one cannot as yet transform ! 668: to \f3.c~\fP; however, this may become possible in the future.)\ ! 669: Note also, the disabling of the ! 670: \&\f3.c.a:\fP rule, which would have created each object file, one by one. ! 671: This particular construct speeds up archive library maintenance considerably. ! 672: This type of construct becomes very cumbersome if the archive library ! 673: contains a mix of assembly programs and C programs. ! 674: .SH FILES ! 675: [Mm]akefile and s\f3.\fP[Mm]akefile ! 676: .SH SEE ALSO ! 677: .IR sh (1), ! 678: .IR mk (8). ! 679: .br ! 680: .I "Make\-A Program for Maintaining Computer Programs\^" ! 681: by ! 682: S. I. Feldman. ! 683: .br ! 684: .I "An Augmented Version of Make\^" ! 685: by ! 686: E. G. Bradford. ! 687: .SH BUGS ! 688: Some commands return non-zero status inappropriately; ! 689: use ! 690: .B \-i ! 691: to overcome the difficulty. ! 692: Commands that are directly executed by the shell, ! 693: notably ! 694: .IR cd (1), ! 695: are ineffectual across new-lines in ! 696: .IR make . ! 697: The syntax \f3(lib(file1.o file2.o file3.o)\fP is illegal. ! 698: You cannot build \f3lib(file.o)\fP from \f3file.o\fP. ! 699: The macro \f3$(a:.o=.c~)\fP doesn't work. ! 700: .br
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.