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