1@comment This file is included by both standards.texi and make.texinfo. 2@comment It was broken out of standards.texi on 1/6/93 by roland. 3 4@node Makefile Conventions 5@chapter Makefile Conventions 6@comment standards.texi does not print an index, but make.texinfo does. 7@cindex makefile, conventions for 8@cindex conventions for makefiles 9@cindex standards for makefiles 10 11@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free 12@c Software Foundation, Inc. 13 14@c Permission is granted to copy, distribute and/or modify this document 15@c under the terms of the GNU Free Documentation License, Version 1.1 16@c or any later version published by the Free Software Foundation; 17@c with no Invariant Sections, with no 18@c Front-Cover Texts, and with no Back-Cover Texts. 19@c A copy of the license is included in the section entitled ``GNU 20@c Free Documentation License''. 21 22This 23@ifinfo 24node 25@end ifinfo 26@iftex 27@ifset CODESTD 28section 29@end ifset 30@ifclear CODESTD 31chapter 32@end ifclear 33@end iftex 34describes conventions for writing the Makefiles for GNU programs. 35Using Automake will help you write a Makefile that follows these 36conventions. 37 38@menu 39* Makefile Basics:: General Conventions for Makefiles 40* Utilities in Makefiles:: Utilities in Makefiles 41* Command Variables:: Variables for Specifying Commands 42* Directory Variables:: Variables for Installation Directories 43* Standard Targets:: Standard Targets for Users 44* Install Command Categories:: Three categories of commands in the `install' 45 rule: normal, pre-install and post-install. 46@end menu 47 48@node Makefile Basics 49@section General Conventions for Makefiles 50 51Every Makefile should contain this line: 52 53@example 54SHELL = /bin/sh 55@end example 56 57@noindent 58to avoid trouble on systems where the @code{SHELL} variable might be 59inherited from the environment. (This is never a problem with GNU 60@code{make}.) 61 62Different @code{make} programs have incompatible suffix lists and 63implicit rules, and this sometimes creates confusion or misbehavior. So 64it is a good idea to set the suffix list explicitly using only the 65suffixes you need in the particular Makefile, like this: 66 67@example 68.SUFFIXES: 69.SUFFIXES: .c .o 70@end example 71 72@noindent 73The first line clears out the suffix list, the second introduces all 74suffixes which may be subject to implicit rules in this Makefile. 75 76Don't assume that @file{.} is in the path for command execution. When 77you need to run programs that are a part of your package during the 78make, please make sure that it uses @file{./} if the program is built as 79part of the make or @file{$(srcdir)/} if the file is an unchanging part 80of the source code. Without one of these prefixes, the current search 81path is used. 82 83The distinction between @file{./} (the @dfn{build directory}) and 84@file{$(srcdir)/} (the @dfn{source directory}) is important because 85users can build in a separate directory using the @samp{--srcdir} option 86to @file{configure}. A rule of the form: 87 88@smallexample 89foo.1 : foo.man sedscript 90 sed -e sedscript foo.man > foo.1 91@end smallexample 92 93@noindent 94will fail when the build directory is not the source directory, because 95@file{foo.man} and @file{sedscript} are in the source directory. 96 97When using GNU @code{make}, relying on @samp{VPATH} to find the source 98file will work in the case where there is a single dependency file, 99since the @code{make} automatic variable @samp{$<} will represent the 100source file wherever it is. (Many versions of @code{make} set @samp{$<} 101only in implicit rules.) A Makefile target like 102 103@smallexample 104foo.o : bar.c 105 $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o 106@end smallexample 107 108@noindent 109should instead be written as 110 111@smallexample 112foo.o : bar.c 113 $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ 114@end smallexample 115 116@noindent 117in order to allow @samp{VPATH} to work correctly. When the target has 118multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest 119way to make the rule work well. For example, the target above for 120@file{foo.1} is best written as: 121 122@smallexample 123foo.1 : foo.man sedscript 124 sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ 125@end smallexample 126 127GNU distributions usually contain some files which are not source 128files---for example, Info files, and the output from Autoconf, Automake, 129Bison or Flex. Since these files normally appear in the source 130directory, they should always appear in the source directory, not in the 131build directory. So Makefile rules to update them should put the 132updated files in the source directory. 133 134However, if a file does not appear in the distribution, then the 135Makefile should not put it in the source directory, because building a 136program in ordinary circumstances should not modify the source directory 137in any way. 138 139Try to make the build and installation targets, at least (and all their 140subtargets) work correctly with a parallel @code{make}. 141 142@node Utilities in Makefiles 143@section Utilities in Makefiles 144 145Write the Makefile commands (and any shell scripts, such as 146@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any 147special features of @code{ksh} or @code{bash}. 148 149The @code{configure} script and the Makefile rules for building and 150installation should not use any utilities directly except these: 151 152@c dd find 153@c gunzip gzip md5sum 154@c mkfifo mknod tee uname 155 156@example 157cat cmp cp diff echo egrep expr false grep install-info 158ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true 159@end example 160 161The compression program @code{gzip} can be used in the @code{dist} rule. 162 163Stick to the generally supported options for these programs. For 164example, don't use @samp{mkdir -p}, convenient as it may be, because 165most systems don't support it. 166 167It is a good idea to avoid creating symbolic links in makefiles, since a 168few systems don't support them. 169 170The Makefile rules for building and installation can also use compilers 171and related programs, but should do so via @code{make} variables so that the 172user can substitute alternatives. Here are some of the programs we 173mean: 174 175@example 176ar bison cc flex install ld ldconfig lex 177make makeinfo ranlib texi2dvi yacc 178@end example 179 180Use the following @code{make} variables to run those programs: 181 182@example 183$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) 184$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) 185@end example 186 187When you use @code{ranlib} or @code{ldconfig}, you should make sure 188nothing bad happens if the system does not have the program in question. 189Arrange to ignore an error from that command, and print a message before 190the command to tell the user that failure of this command does not mean 191a problem. (The Autoconf @samp{AC_PROG_RANLIB} macro can help with 192this.) 193 194If you use symbolic links, you should implement a fallback for systems 195that don't have symbolic links. 196 197Additional utilities that can be used via Make variables are: 198 199@example 200chgrp chmod chown mknod 201@end example 202 203It is ok to use other utilities in Makefile portions (or scripts) 204intended only for particular systems where you know those utilities 205exist. 206 207@node Command Variables 208@section Variables for Specifying Commands 209 210Makefiles should provide variables for overriding certain commands, options, 211and so on. 212 213In particular, you should run most utility programs via variables. 214Thus, if you use Bison, have a variable named @code{BISON} whose default 215value is set with @samp{BISON = bison}, and refer to it with 216@code{$(BISON)} whenever you need to use Bison. 217 218File management utilities such as @code{ln}, @code{rm}, @code{mv}, and 219so on, need not be referred to through variables in this way, since users 220don't need to replace them with other programs. 221 222Each program-name variable should come with an options variable that is 223used to supply options to the program. Append @samp{FLAGS} to the 224program-name variable name to get the options variable name---for 225example, @code{BISONFLAGS}. (The names @code{CFLAGS} for the C 226compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are 227exceptions to this rule, but we keep them because they are standard.) 228Use @code{CPPFLAGS} in any compilation command that runs the 229preprocessor, and use @code{LDFLAGS} in any compilation command that 230does linking as well as in any direct use of @code{ld}. 231 232If there are C compiler options that @emph{must} be used for proper 233compilation of certain files, do not include them in @code{CFLAGS}. 234Users expect to be able to specify @code{CFLAGS} freely themselves. 235Instead, arrange to pass the necessary options to the C compiler 236independently of @code{CFLAGS}, by writing them explicitly in the 237compilation commands or by defining an implicit rule, like this: 238 239@smallexample 240CFLAGS = -g 241ALL_CFLAGS = -I. $(CFLAGS) 242.c.o: 243 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< 244@end smallexample 245 246Do include the @samp{-g} option in @code{CFLAGS}, because that is not 247@emph{required} for proper compilation. You can consider it a default 248that is only recommended. If the package is set up so that it is 249compiled with GCC by default, then you might as well include @samp{-O} 250in the default value of @code{CFLAGS} as well. 251 252Put @code{CFLAGS} last in the compilation command, after other variables 253containing compiler options, so the user can use @code{CFLAGS} to 254override the others. 255 256@code{CFLAGS} should be used in every invocation of the C compiler, 257both those which do compilation and those which do linking. 258 259Every Makefile should define the variable @code{INSTALL}, which is the 260basic command for installing a file into the system. 261 262Every Makefile should also define the variables @code{INSTALL_PROGRAM} 263and @code{INSTALL_DATA}. (The default for @code{INSTALL_PROGRAM} should 264be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be 265@code{$@{INSTALL@} -m 644}.) Then it should use those variables as the 266commands for actual installation, for executables and nonexecutables 267respectively. Use these variables as follows: 268 269@example 270$(INSTALL_PROGRAM) foo $(bindir)/foo 271$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a 272@end example 273 274Optionally, you may prepend the value of @code{DESTDIR} to the target 275filename. Doing this allows the installer to create a snapshot of the 276installation to be copied onto the real target filesystem later. Do not 277set the value of @code{DESTDIR} in your Makefile, and do not include it 278in any installed files. With support for @code{DESTDIR}, the above 279examples become: 280 281@example 282$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo 283$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a 284@end example 285 286@noindent 287Always use a file name, not a directory name, as the second argument of 288the installation commands. Use a separate command for each file to be 289installed. 290 291@node Directory Variables 292@section Variables for Installation Directories 293 294Installation directories should always be named by variables, so it is 295easy to install in a nonstandard place. The standard names for these 296variables are described below. They are based on a standard filesystem 297layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4, 298and other modern operating systems. 299 300These two variables set the root for the installation. All the other 301installation directories should be subdirectories of one of these two, 302and nothing should be directly installed into these two directories. 303 304@table @code 305@item prefix 306@vindex prefix 307A prefix used in constructing the default values of the variables listed 308below. The default value of @code{prefix} should be @file{/usr/local}. 309When building the complete GNU system, the prefix will be empty and 310@file{/usr} will be a symbolic link to @file{/}. 311(If you are using Autoconf, write it as @samp{@@prefix@@}.) 312 313Running @samp{make install} with a different value of @code{prefix} from 314the one used to build the program should @emph{not} recompile the 315program. 316 317@item exec_prefix 318@vindex exec_prefix 319A prefix used in constructing the default values of some of the 320variables listed below. The default value of @code{exec_prefix} should 321be @code{$(prefix)}. 322(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) 323 324Generally, @code{$(exec_prefix)} is used for directories that contain 325machine-specific files (such as executables and subroutine libraries), 326while @code{$(prefix)} is used directly for other directories. 327 328Running @samp{make install} with a different value of @code{exec_prefix} 329from the one used to build the program should @emph{not} recompile the 330program. 331@end table 332 333Executable programs are installed in one of the following directories. 334 335@table @code 336@item bindir 337@vindex bindir 338The directory for installing executable programs that users can run. 339This should normally be @file{/usr/local/bin}, but write it as 340@file{$(exec_prefix)/bin}. 341(If you are using Autoconf, write it as @samp{@@bindir@@}.) 342 343@item sbindir 344@vindex sbindir 345The directory for installing executable programs that can be run from 346the shell, but are only generally useful to system administrators. This 347should normally be @file{/usr/local/sbin}, but write it as 348@file{$(exec_prefix)/sbin}. 349(If you are using Autoconf, write it as @samp{@@sbindir@@}.) 350 351@item libexecdir 352@vindex libexecdir 353@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 354The directory for installing executable programs to be run by other 355programs rather than by users. This directory should normally be 356@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. 357(If you are using Autoconf, write it as @samp{@@libexecdir@@}.) 358@end table 359 360Data files used by the program during its execution are divided into 361categories in two ways. 362 363@itemize @bullet 364@item 365Some files are normally modified by programs; others are never normally 366modified (though users may edit some of these). 367 368@item 369Some files are architecture-independent and can be shared by all 370machines at a site; some are architecture-dependent and can be shared 371only by machines of the same kind and operating system; others may never 372be shared between two machines. 373@end itemize 374 375This makes for six different possibilities. However, we want to 376discourage the use of architecture-dependent files, aside from object 377files and libraries. It is much cleaner to make other data files 378architecture-independent, and it is generally not hard. 379 380Therefore, here are the variables Makefiles should use to specify 381directories: 382 383@table @samp 384@item datadir 385The directory for installing read-only architecture independent data 386files. This should normally be @file{/usr/local/share}, but write it as 387@file{$(prefix)/share}. 388(If you are using Autoconf, write it as @samp{@@datadir@@}.) 389As a special exception, see @file{$(infodir)} 390and @file{$(includedir)} below. 391 392@item sysconfdir 393The directory for installing read-only data files that pertain to a 394single machine--that is to say, files for configuring a host. Mailer 395and network configuration files, @file{/etc/passwd}, and so forth belong 396here. All the files in this directory should be ordinary ASCII text 397files. This directory should normally be @file{/usr/local/etc}, but 398write it as @file{$(prefix)/etc}. 399(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) 400 401Do not install executables here in this directory (they probably belong 402in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install 403files that are modified in the normal course of their use (programs 404whose purpose is to change the configuration of the system excluded). 405Those probably belong in @file{$(localstatedir)}. 406 407@item sharedstatedir 408The directory for installing architecture-independent data files which 409the programs modify while they run. This should normally be 410@file{/usr/local/com}, but write it as @file{$(prefix)/com}. 411(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) 412 413@item localstatedir 414The directory for installing data files which the programs modify while 415they run, and that pertain to one specific machine. Users should never 416need to modify files in this directory to configure the package's 417operation; put such configuration information in separate files that go 418in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} 419should normally be @file{/usr/local/var}, but write it as 420@file{$(prefix)/var}. 421(If you are using Autoconf, write it as @samp{@@localstatedir@@}.) 422 423@item libdir 424The directory for object files and libraries of object code. Do not 425install executables here, they probably ought to go in @file{$(libexecdir)} 426instead. The value of @code{libdir} should normally be 427@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. 428(If you are using Autoconf, write it as @samp{@@libdir@@}.) 429 430@item infodir 431The directory for installing the Info files for this package. By 432default, it should be @file{/usr/local/info}, but it should be written 433as @file{$(prefix)/info}. 434(If you are using Autoconf, write it as @samp{@@infodir@@}.) 435 436@item lispdir 437The directory for installing any Emacs Lisp files in this package. By 438default, it should be @file{/usr/local/share/emacs/site-lisp}, but it 439should be written as @file{$(prefix)/share/emacs/site-lisp}. 440 441If you are using Autoconf, write the default as @samp{@@lispdir@@}. 442In order to make @samp{@@lispdir@@} work, you need the following lines 443in your @file{configure.in} file: 444 445@example 446lispdir='$@{datadir@}/emacs/site-lisp' 447AC_SUBST(lispdir) 448@end example 449 450@item includedir 451@c rewritten to avoid overfull hbox --roland 452The directory for installing header files to be included by user 453programs with the C @samp{#include} preprocessor directive. This 454should normally be @file{/usr/local/include}, but write it as 455@file{$(prefix)/include}. 456(If you are using Autoconf, write it as @samp{@@includedir@@}.) 457 458Most compilers other than GCC do not look for header files in directory 459@file{/usr/local/include}. So installing the header files this way is 460only useful with GCC. Sometimes this is not a problem because some 461libraries are only really intended to work with GCC. But some libraries 462are intended to work with other compilers. They should install their 463header files in two places, one specified by @code{includedir} and one 464specified by @code{oldincludedir}. 465 466@item oldincludedir 467The directory for installing @samp{#include} header files for use with 468compilers other than GCC. This should normally be @file{/usr/include}. 469(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) 470 471The Makefile commands should check whether the value of 472@code{oldincludedir} is empty. If it is, they should not try to use 473it; they should cancel the second installation of the header files. 474 475A package should not replace an existing header in this directory unless 476the header came from the same package. Thus, if your Foo package 477provides a header file @file{foo.h}, then it should install the header 478file in the @code{oldincludedir} directory if either (1) there is no 479@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo 480package. 481 482To tell whether @file{foo.h} came from the Foo package, put a magic 483string in the file---part of a comment---and @code{grep} for that string. 484@end table 485 486Unix-style man pages are installed in one of the following: 487 488@table @samp 489@item mandir 490The top-level directory for installing the man pages (if any) for this 491package. It will normally be @file{/usr/local/man}, but you should 492write it as @file{$(prefix)/man}. 493(If you are using Autoconf, write it as @samp{@@mandir@@}.) 494 495@item man1dir 496The directory for installing section 1 man pages. Write it as 497@file{$(mandir)/man1}. 498@item man2dir 499The directory for installing section 2 man pages. Write it as 500@file{$(mandir)/man2} 501@item @dots{} 502 503@strong{Don't make the primary documentation for any GNU software be a 504man page. Write a manual in Texinfo instead. Man pages are just for 505the sake of people running GNU software on Unix, which is a secondary 506application only.} 507 508@item manext 509The file name extension for the installed man page. This should contain 510a period followed by the appropriate digit; it should normally be @samp{.1}. 511 512@item man1ext 513The file name extension for installed section 1 man pages. 514@item man2ext 515The file name extension for installed section 2 man pages. 516@item @dots{} 517Use these names instead of @samp{manext} if the package needs to install man 518pages in more than one section of the manual. 519@end table 520 521And finally, you should set the following variable: 522 523@table @samp 524@item srcdir 525The directory for the sources being compiled. The value of this 526variable is normally inserted by the @code{configure} shell script. 527(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.) 528@end table 529 530For example: 531 532@smallexample 533@c I have changed some of the comments here slightly to fix an overfull 534@c hbox, so the make manual can format correctly. --roland 535# Common prefix for installation directories. 536# NOTE: This directory must exist when you start the install. 537prefix = /usr/local 538exec_prefix = $(prefix) 539# Where to put the executable for the command `gcc'. 540bindir = $(exec_prefix)/bin 541# Where to put the directories used by the compiler. 542libexecdir = $(exec_prefix)/libexec 543# Where to put the Info files. 544infodir = $(prefix)/info 545@end smallexample 546 547If your program installs a large number of files into one of the 548standard user-specified directories, it might be useful to group them 549into a subdirectory particular to that program. If you do this, you 550should write the @code{install} rule to create these subdirectories. 551 552Do not expect the user to include the subdirectory name in the value of 553any of the variables listed above. The idea of having a uniform set of 554variable names for installation directories is to enable the user to 555specify the exact same values for several different GNU packages. In 556order for this to be useful, all the packages must be designed so that 557they will work sensibly when the user does so. 558 559@node Standard Targets 560@section Standard Targets for Users 561 562All GNU programs should have the following targets in their Makefiles: 563 564@table @samp 565@item all 566Compile the entire program. This should be the default target. This 567target need not rebuild any documentation files; Info files should 568normally be included in the distribution, and DVI files should be made 569only when explicitly asked for. 570 571By default, the Make rules should compile and link with @samp{-g}, so 572that executable programs have debugging symbols. Users who don't mind 573being helpless can strip the executables later if they wish. 574 575@item install 576Compile the program and copy the executables, libraries, and so on to 577the file names where they should reside for actual use. If there is a 578simple test to verify that a program is properly installed, this target 579should run that test. 580 581Do not strip executables when installing them. Devil-may-care users can 582use the @code{install-strip} target to do that. 583 584If possible, write the @code{install} target rule so that it does not 585modify anything in the directory where the program was built, provided 586@samp{make all} has just been done. This is convenient for building the 587program under one user name and installing it under another. 588 589The commands should create all the directories in which files are to be 590installed, if they don't already exist. This includes the directories 591specified as the values of the variables @code{prefix} and 592@code{exec_prefix}, as well as all subdirectories that are needed. 593One way to do this is by means of an @code{installdirs} target 594as described below. 595 596Use @samp{-} before any command for installing a man page, so that 597@code{make} will ignore any errors. This is in case there are systems 598that don't have the Unix man page documentation system installed. 599 600The way to install Info files is to copy them into @file{$(infodir)} 601with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run 602the @code{install-info} program if it is present. @code{install-info} 603is a program that edits the Info @file{dir} file to add or update the 604menu entry for the given Info file; it is part of the Texinfo package. 605Here is a sample rule to install an Info file: 606 607@comment This example has been carefully formatted for the Make manual. 608@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. 609@smallexample 610$(DESTDIR)$(infodir)/foo.info: foo.info 611 $(POST_INSTALL) 612# There may be a newer info file in . than in srcdir. 613 -if test -f foo.info; then d=.; \ 614 else d=$(srcdir); fi; \ 615 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \ 616# Run install-info only if it exists. 617# Use `if' instead of just prepending `-' to the 618# line so we notice real errors from install-info. 619# We use `$(SHELL) -c' because some shells do not 620# fail gracefully when there is an unknown command. 621 if $(SHELL) -c 'install-info --version' \ 622 >/dev/null 2>&1; then \ 623 install-info --dir-file=$(DESTDIR)$(infodir)/dir \ 624 $(DESTDIR)$(infodir)/foo.info; \ 625 else true; fi 626@end smallexample 627 628When writing the @code{install} target, you must classify all the 629commands into three categories: normal ones, @dfn{pre-installation} 630commands and @dfn{post-installation} commands. @xref{Install Command 631Categories}. 632 633@item uninstall 634Delete all the installed files---the copies that the @samp{install} 635target creates. 636 637This rule should not modify the directories where compilation is done, 638only the directories where files are installed. 639 640The uninstallation commands are divided into three categories, just like 641the installation commands. @xref{Install Command Categories}. 642 643@item install-strip 644Like @code{install}, but strip the executable files while installing 645them. In simple cases, this target can use the @code{install} target in 646a simple way: 647 648@smallexample 649install-strip: 650 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ 651 install 652@end smallexample 653 654But if the package installs scripts as well as real executables, the 655@code{install-strip} target can't just refer to the @code{install} 656target; it has to strip the executables but not the scripts. 657 658@code{install-strip} should not strip the executables in the build 659directory which are being copied for installation. It should only strip 660the copies that are installed. 661 662Normally we do not recommend stripping an executable unless you are sure 663the program has no bugs. However, it can be reasonable to install a 664stripped executable for actual execution while saving the unstripped 665executable elsewhere in case there is a bug. 666 667@comment The gratuitous blank line here is to make the table look better 668@comment in the printed Make manual. Please leave it in. 669@item clean 670 671Delete all files from the current directory that are normally created by 672building the program. Don't delete the files that record the 673configuration. Also preserve files that could be made by building, but 674normally aren't because the distribution comes with them. 675 676Delete @file{.dvi} files here if they are not part of the distribution. 677 678@item distclean 679Delete all files from the current directory that are created by 680configuring or building the program. If you have unpacked the source 681and built the program without creating any other files, @samp{make 682distclean} should leave only the files that were in the distribution. 683 684@item mostlyclean 685Like @samp{clean}, but may refrain from deleting a few files that people 686normally don't want to recompile. For example, the @samp{mostlyclean} 687target for GCC does not delete @file{libgcc.a}, because recompiling it 688is rarely necessary and takes a lot of time. 689 690@item maintainer-clean 691Delete almost everything from the current directory that can be 692reconstructed with this Makefile. This typically includes everything 693deleted by @code{distclean}, plus more: C source files produced by 694Bison, tags tables, Info files, and so on. 695 696The reason we say ``almost everything'' is that running the command 697@samp{make maintainer-clean} should not delete @file{configure} even if 698@file{configure} can be remade using a rule in the Makefile. More generally, 699@samp{make maintainer-clean} should not delete anything that needs to 700exist in order to run @file{configure} and then begin to build the 701program. This is the only exception; @code{maintainer-clean} should 702delete everything else that can be rebuilt. 703 704The @samp{maintainer-clean} target is intended to be used by a maintainer of 705the package, not by ordinary users. You may need special tools to 706reconstruct some of the files that @samp{make maintainer-clean} deletes. 707Since these files are normally included in the distribution, we don't 708take care to make them easy to reconstruct. If you find you need to 709unpack the full distribution again, don't blame us. 710 711To help make users aware of this, the commands for the special 712@code{maintainer-clean} target should start with these two: 713 714@smallexample 715@@echo 'This command is intended for maintainers to use; it' 716@@echo 'deletes files that may need special tools to rebuild.' 717@end smallexample 718 719@item TAGS 720Update a tags table for this program. 721@c ADR: how? 722 723@item info 724Generate any Info files needed. The best way to write the rules is as 725follows: 726 727@smallexample 728info: foo.info 729 730foo.info: foo.texi chap1.texi chap2.texi 731 $(MAKEINFO) $(srcdir)/foo.texi 732@end smallexample 733 734@noindent 735You must define the variable @code{MAKEINFO} in the Makefile. It should 736run the @code{makeinfo} program, which is part of the Texinfo 737distribution. 738 739Normally a GNU distribution comes with Info files, and that means the 740Info files are present in the source directory. Therefore, the Make 741rule for an info file should update it in the source directory. When 742users build the package, ordinarily Make will not update the Info files 743because they will already be up to date. 744 745@item dvi 746Generate DVI files for all Texinfo documentation. 747For example: 748 749@smallexample 750dvi: foo.dvi 751 752foo.dvi: foo.texi chap1.texi chap2.texi 753 $(TEXI2DVI) $(srcdir)/foo.texi 754@end smallexample 755 756@noindent 757You must define the variable @code{TEXI2DVI} in the Makefile. It should 758run the program @code{texi2dvi}, which is part of the Texinfo 759distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work 760of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, 761write just the dependencies, and allow GNU @code{make} to provide the command. 762 763@item dist 764Create a distribution tar file for this program. The tar file should be 765set up so that the file names in the tar file start with a subdirectory 766name which is the name of the package it is a distribution for. This 767name can include the version number. 768 769For example, the distribution tar file of GCC version 1.40 unpacks into 770a subdirectory named @file{gcc-1.40}. 771 772The easiest way to do this is to create a subdirectory appropriately 773named, use @code{ln} or @code{cp} to install the proper files in it, and 774then @code{tar} that subdirectory. 775 776Compress the tar file with @code{gzip}. For example, the actual 777distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. 778 779The @code{dist} target should explicitly depend on all non-source files 780that are in the distribution, to make sure they are up to date in the 781distribution. 782@ifset CODESTD 783@xref{Releases, , Making Releases}. 784@end ifset 785@ifclear CODESTD 786@xref{Releases, , Making Releases, standards, GNU Coding Standards}. 787@end ifclear 788 789@item check 790Perform self-tests (if any). The user must build the program before 791running the tests, but need not install the program; you should write 792the self-tests so that they work when the program is built but not 793installed. 794@end table 795 796The following targets are suggested as conventional names, for programs 797in which they are useful. 798 799@table @code 800@item installcheck 801Perform installation tests (if any). The user must build and install 802the program before running the tests. You should not assume that 803@file{$(bindir)} is in the search path. 804 805@item installdirs 806It's useful to add a target named @samp{installdirs} to create the 807directories where files are installed, and their parent directories. 808There is a script called @file{mkinstalldirs} which is convenient for 809this; you can find it in the Texinfo package. 810@c It's in /gd/gnu/lib/mkinstalldirs. 811You can use a rule like this: 812 813@comment This has been carefully formatted to look decent in the Make manual. 814@comment Please be sure not to make it extend any further to the right.--roland 815@smallexample 816# Make sure all installation directories (e.g. $(bindir)) 817# actually exist by making them if necessary. 818installdirs: mkinstalldirs 819 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ 820 $(libdir) $(infodir) \ 821 $(mandir) 822@end smallexample 823 824@noindent 825or, if you wish to support @env{DESTDIR}, 826 827@smallexample 828# Make sure all installation directories (e.g. $(bindir)) 829# actually exist by making them if necessary. 830installdirs: mkinstalldirs 831 $(srcdir)/mkinstalldirs \ 832 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ 833 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ 834 $(DESTDIR)$(mandir) 835@end smallexample 836 837This rule should not modify the directories where compilation is done. 838It should do nothing but create installation directories. 839@end table 840 841@node Install Command Categories 842@section Install Command Categories 843 844@cindex pre-installation commands 845@cindex post-installation commands 846When writing the @code{install} target, you must classify all the 847commands into three categories: normal ones, @dfn{pre-installation} 848commands and @dfn{post-installation} commands. 849 850Normal commands move files into their proper places, and set their 851modes. They may not alter any files except the ones that come entirely 852from the package they belong to. 853 854Pre-installation and post-installation commands may alter other files; 855in particular, they can edit global configuration files or data bases. 856 857Pre-installation commands are typically executed before the normal 858commands, and post-installation commands are typically run after the 859normal commands. 860 861The most common use for a post-installation command is to run 862@code{install-info}. This cannot be done with a normal command, since 863it alters a file (the Info directory) which does not come entirely and 864solely from the package being installed. It is a post-installation 865command because it needs to be done after the normal command which 866installs the package's Info files. 867 868Most programs don't need any pre-installation commands, but we have the 869feature just in case it is needed. 870 871To classify the commands in the @code{install} rule into these three 872categories, insert @dfn{category lines} among them. A category line 873specifies the category for the commands that follow. 874 875A category line consists of a tab and a reference to a special Make 876variable, plus an optional comment at the end. There are three 877variables you can use, one for each category; the variable name 878specifies the category. Category lines are no-ops in ordinary execution 879because these three Make variables are normally undefined (and you 880@emph{should not} define them in the makefile). 881 882Here are the three possible category lines, each with a comment that 883explains what it means: 884 885@smallexample 886 $(PRE_INSTALL) # @r{Pre-install commands follow.} 887 $(POST_INSTALL) # @r{Post-install commands follow.} 888 $(NORMAL_INSTALL) # @r{Normal commands follow.} 889@end smallexample 890 891If you don't use a category line at the beginning of the @code{install} 892rule, all the commands are classified as normal until the first category 893line. If you don't use any category lines, all the commands are 894classified as normal. 895 896These are the category lines for @code{uninstall}: 897 898@smallexample 899 $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.} 900 $(POST_UNINSTALL) # @r{Post-uninstall commands follow.} 901 $(NORMAL_UNINSTALL) # @r{Normal commands follow.} 902@end smallexample 903 904Typically, a pre-uninstall command would be used for deleting entries 905from the Info directory. 906 907If the @code{install} or @code{uninstall} target has any dependencies 908which act as subroutines of installation, then you should start 909@emph{each} dependency's commands with a category line, and start the 910main target's commands with a category line also. This way, you can 911ensure that each command is placed in the right category regardless of 912which of the dependencies actually run. 913 914Pre-installation and post-installation commands should not run any 915programs except for these: 916 917@example 918[ basename bash cat chgrp chmod chown cmp cp dd diff echo 919egrep expand expr false fgrep find getopt grep gunzip gzip 920hostname install install-info kill ldconfig ln ls md5sum 921mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee 922test touch true uname xargs yes 923@end example 924 925@cindex binary packages 926The reason for distinguishing the commands in this way is for the sake 927of making binary packages. Typically a binary package contains all the 928executables and other files that need to be installed, and has its own 929method of installing them---so it does not need to run the normal 930installation commands. But installing the binary package does need to 931execute the pre-installation and post-installation commands. 932 933Programs to build binary packages work by extracting the 934pre-installation and post-installation commands. Here is one way of 935extracting the pre-installation commands: 936 937@smallexample 938make -n install -o all \ 939 PRE_INSTALL=pre-install \ 940 POST_INSTALL=post-install \ 941 NORMAL_INSTALL=normal-install \ 942 | gawk -f pre-install.awk 943@end smallexample 944 945@noindent 946where the file @file{pre-install.awk} could contain this: 947 948@smallexample 949$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@} 950on @{print $0@} 951$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@} 952@end smallexample 953 954The resulting file of pre-installation commands is executed as a shell 955script as part of installing the binary package. 956