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 (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001, 12@c 2004, 2005 Free 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 and the values they should have in GNU packages are 297described below. They are based on a standard filesystem layout; 298variants of it are used in GNU/Linux and other modern operating 299systems. 300 301Installers are expected to override these values when calling 302@command{make} (e.g., @kbd{make prefix=/usr install} or 303@command{configure} (e.g., @kbd{configure --prefix=/usr}). GNU 304packages should not try to guess which value should be appropriate for 305these variables on the system they are being installed onto: use the 306default settings specified here so that all GNU packages behave 307identically, allowing the installer to achieve any desired layout. 308 309These two variables set the root for the installation. All the other 310installation directories should be subdirectories of one of these two, 311and nothing should be directly installed into these two directories. 312 313@table @code 314@item prefix 315@vindex prefix 316A prefix used in constructing the default values of the variables listed 317below. The default value of @code{prefix} should be @file{/usr/local}. 318When building the complete GNU system, the prefix will be empty and 319@file{/usr} will be a symbolic link to @file{/}. 320(If you are using Autoconf, write it as @samp{@@prefix@@}.) 321 322Running @samp{make install} with a different value of @code{prefix} from 323the one used to build the program should @emph{not} recompile the 324program. 325 326@item exec_prefix 327@vindex exec_prefix 328A prefix used in constructing the default values of some of the 329variables listed below. The default value of @code{exec_prefix} should 330be @code{$(prefix)}. 331(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) 332 333Generally, @code{$(exec_prefix)} is used for directories that contain 334machine-specific files (such as executables and subroutine libraries), 335while @code{$(prefix)} is used directly for other directories. 336 337Running @samp{make install} with a different value of @code{exec_prefix} 338from the one used to build the program should @emph{not} recompile the 339program. 340@end table 341 342Executable programs are installed in one of the following directories. 343 344@table @code 345@item bindir 346@vindex bindir 347The directory for installing executable programs that users can run. 348This should normally be @file{/usr/local/bin}, but write it as 349@file{$(exec_prefix)/bin}. 350(If you are using Autoconf, write it as @samp{@@bindir@@}.) 351 352@item sbindir 353@vindex sbindir 354The directory for installing executable programs that can be run from 355the shell, but are only generally useful to system administrators. This 356should normally be @file{/usr/local/sbin}, but write it as 357@file{$(exec_prefix)/sbin}. 358(If you are using Autoconf, write it as @samp{@@sbindir@@}.) 359 360@item libexecdir 361@vindex libexecdir 362@comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 363The directory for installing executable programs to be run by other 364programs rather than by users. This directory should normally be 365@file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. 366(If you are using Autoconf, write it as @samp{@@libexecdir@@}.) 367 368The definition of @samp{libexecdir} is the same for all packages, so 369you should install your data in a subdirectory thereof. Most packages 370install their data under @file{$(libexecdir)/@var{package-name}/}, 371possibly within additional subdirectories thereof, such as 372@file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}. 373@end table 374 375Data files used by the program during its execution are divided into 376categories in two ways. 377 378@itemize @bullet 379@item 380Some files are normally modified by programs; others are never normally 381modified (though users may edit some of these). 382 383@item 384Some files are architecture-independent and can be shared by all 385machines at a site; some are architecture-dependent and can be shared 386only by machines of the same kind and operating system; others may never 387be shared between two machines. 388@end itemize 389 390This makes for six different possibilities. However, we want to 391discourage the use of architecture-dependent files, aside from object 392files and libraries. It is much cleaner to make other data files 393architecture-independent, and it is generally not hard. 394 395Here are the variables Makefiles should use to specify directories 396to put these various kinds of files in: 397 398@table @samp 399@item datarootdir 400The root of the directory tree for read-only architecture-independent 401data files. This should normally be @file{/usr/local/share}, but 402write it as @file{$(prefix)/share}. (If you are using Autoconf, write 403it as @samp{@@datarootdir@@}.) @samp{datadir}'s default value is 404based on this variable; so are @samp{infodir}, @samp{mandir}, and 405others. 406 407@item datadir 408The directory for installing idiosyncratic read-only 409architecture-independent data files for this program. This is usually 410the same place as @samp{datarootdir}, but we use the two separate 411variables so that you can move these program-specific files without 412altering the location for Info files, man pages, etc. 413 414This should normally be @file{/usr/local/share}, but write it as 415@file{$(datarootdir)}. (If you are using Autoconf, write it as 416@samp{@@datadir@@}.) 417 418The definition of @samp{datadir} is the same for all packages, so you 419should install your data in a subdirectory thereof. Most packages 420install their data under @file{$(datadir)/@var{package-name}/}. 421 422@item sysconfdir 423The directory for installing read-only data files that pertain to a 424single machine--that is to say, files for configuring a host. Mailer 425and network configuration files, @file{/etc/passwd}, and so forth belong 426here. All the files in this directory should be ordinary ASCII text 427files. This directory should normally be @file{/usr/local/etc}, but 428write it as @file{$(prefix)/etc}. 429(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) 430 431Do not install executables here in this directory (they probably belong 432in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install 433files that are modified in the normal course of their use (programs 434whose purpose is to change the configuration of the system excluded). 435Those probably belong in @file{$(localstatedir)}. 436 437@item sharedstatedir 438The directory for installing architecture-independent data files which 439the programs modify while they run. This should normally be 440@file{/usr/local/com}, but write it as @file{$(prefix)/com}. 441(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) 442 443@item localstatedir 444The directory for installing data files which the programs modify while 445they run, and that pertain to one specific machine. Users should never 446need to modify files in this directory to configure the package's 447operation; put such configuration information in separate files that go 448in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} 449should normally be @file{/usr/local/var}, but write it as 450@file{$(prefix)/var}. 451(If you are using Autoconf, write it as @samp{@@localstatedir@@}.) 452@end table 453 454These variables specify the directory for installing certain specific 455types of files, if your program has them. Every GNU package should 456have Info files, so every program needs @samp{infodir}, but not all 457need @samp{libdir} or @samp{lispdir}. 458 459@table @samp 460@item includedir 461@c rewritten to avoid overfull hbox --roland 462The directory for installing header files to be included by user 463programs with the C @samp{#include} preprocessor directive. This 464should normally be @file{/usr/local/include}, but write it as 465@file{$(prefix)/include}. 466(If you are using Autoconf, write it as @samp{@@includedir@@}.) 467 468Most compilers other than GCC do not look for header files in directory 469@file{/usr/local/include}. So installing the header files this way is 470only useful with GCC. Sometimes this is not a problem because some 471libraries are only really intended to work with GCC. But some libraries 472are intended to work with other compilers. They should install their 473header files in two places, one specified by @code{includedir} and one 474specified by @code{oldincludedir}. 475 476@item oldincludedir 477The directory for installing @samp{#include} header files for use with 478compilers other than GCC. This should normally be @file{/usr/include}. 479(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) 480 481The Makefile commands should check whether the value of 482@code{oldincludedir} is empty. If it is, they should not try to use 483it; they should cancel the second installation of the header files. 484 485A package should not replace an existing header in this directory unless 486the header came from the same package. Thus, if your Foo package 487provides a header file @file{foo.h}, then it should install the header 488file in the @code{oldincludedir} directory if either (1) there is no 489@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo 490package. 491 492To tell whether @file{foo.h} came from the Foo package, put a magic 493string in the file---part of a comment---and @code{grep} for that string. 494 495@item docdir 496The directory for installing documentation files (other than Info) for 497this package. By default, it should be 498@file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as 499@file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf, 500write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which 501may include a version number, prevents collisions among files with 502common names, such as @file{README}. 503 504@item infodir 505The directory for installing the Info files for this package. By 506default, it should be @file{/usr/local/share/info}, but it should be 507written as @file{$(datarootdir)/info}. (If you are using Autoconf, 508write it as @samp{@@infodir@@}.) @code{infodir} is separate from 509@code{docdir} for compatibility with existing practice. 510 511@item htmldir 512@itemx dvidir 513@itemx pdfdir 514@itemx psdir 515Directories for installing documentation files in the particular 516format. (It is not required to support documentation in all these 517formats.) They should all be set to @code{$(docdir)} by default. (If 518you are using Autoconf, write them as @samp{@@htmldir@@}, 519@samp{@@dvidir@@}, etc.) Packages which supply several translations 520of their documentation should install them in 521@samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where 522@var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}. 523 524@item libdir 525The directory for object files and libraries of object code. Do not 526install executables here, they probably ought to go in @file{$(libexecdir)} 527instead. The value of @code{libdir} should normally be 528@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. 529(If you are using Autoconf, write it as @samp{@@libdir@@}.) 530 531@item lispdir 532The directory for installing any Emacs Lisp files in this package. By 533default, it should be @file{/usr/local/share/emacs/site-lisp}, but it 534should be written as @file{$(datarootdir)/emacs/site-lisp}. 535 536If you are using Autoconf, write the default as @samp{@@lispdir@@}. 537In order to make @samp{@@lispdir@@} work, you need the following lines 538in your @file{configure.in} file: 539 540@example 541lispdir='$@{datarootdir@}/emacs/site-lisp' 542AC_SUBST(lispdir) 543@end example 544 545@item localedir 546The directory for installing locale-specific message catalogs for this 547package. By default, it should be @file{/usr/local/share/locale}, but 548it should be written as @file{$(datarootdir)/locale}. (If you are 549using Autoconf, write it as @samp{@@localedir@@}.) This directory 550usually has a subdirectory per locale. 551@end table 552 553Unix-style man pages are installed in one of the following: 554 555@table @samp 556@item mandir 557The top-level directory for installing the man pages (if any) for this 558package. It will normally be @file{/usr/local/share/man}, but you 559should write it as @file{$(datarootdir)/man}. (If you are using 560Autoconf, write it as @samp{@@mandir@@}.) 561 562@item man1dir 563The directory for installing section 1 man pages. Write it as 564@file{$(mandir)/man1}. 565@item man2dir 566The directory for installing section 2 man pages. Write it as 567@file{$(mandir)/man2} 568@item @dots{} 569 570@strong{Don't make the primary documentation for any GNU software be a 571man page. Write a manual in Texinfo instead. Man pages are just for 572the sake of people running GNU software on Unix, which is a secondary 573application only.} 574 575@item manext 576The file name extension for the installed man page. This should contain 577a period followed by the appropriate digit; it should normally be @samp{.1}. 578 579@item man1ext 580The file name extension for installed section 1 man pages. 581@item man2ext 582The file name extension for installed section 2 man pages. 583@item @dots{} 584Use these names instead of @samp{manext} if the package needs to install man 585pages in more than one section of the manual. 586@end table 587 588And finally, you should set the following variable: 589 590@table @samp 591@item srcdir 592The directory for the sources being compiled. The value of this 593variable is normally inserted by the @code{configure} shell script. 594(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.) 595@end table 596 597For example: 598 599@smallexample 600@c I have changed some of the comments here slightly to fix an overfull 601@c hbox, so the make manual can format correctly. --roland 602# Common prefix for installation directories. 603# NOTE: This directory must exist when you start the install. 604prefix = /usr/local 605datarootdir = $(prefix)/share 606datadir = $(datarootdir) 607exec_prefix = $(prefix) 608# Where to put the executable for the command `gcc'. 609bindir = $(exec_prefix)/bin 610# Where to put the directories used by the compiler. 611libexecdir = $(exec_prefix)/libexec 612# Where to put the Info files. 613infodir = $(datarootdir)/info 614@end smallexample 615 616If your program installs a large number of files into one of the 617standard user-specified directories, it might be useful to group them 618into a subdirectory particular to that program. If you do this, you 619should write the @code{install} rule to create these subdirectories. 620 621Do not expect the user to include the subdirectory name in the value of 622any of the variables listed above. The idea of having a uniform set of 623variable names for installation directories is to enable the user to 624specify the exact same values for several different GNU packages. In 625order for this to be useful, all the packages must be designed so that 626they will work sensibly when the user does so. 627 628@node Standard Targets 629@section Standard Targets for Users 630 631All GNU programs should have the following targets in their Makefiles: 632 633@table @samp 634@item all 635Compile the entire program. This should be the default target. This 636target need not rebuild any documentation files; Info files should 637normally be included in the distribution, and DVI files should be made 638only when explicitly asked for. 639 640By default, the Make rules should compile and link with @samp{-g}, so 641that executable programs have debugging symbols. Users who don't mind 642being helpless can strip the executables later if they wish. 643 644@item install 645Compile the program and copy the executables, libraries, and so on to 646the file names where they should reside for actual use. If there is a 647simple test to verify that a program is properly installed, this target 648should run that test. 649 650Do not strip executables when installing them. Devil-may-care users can 651use the @code{install-strip} target to do that. 652 653If possible, write the @code{install} target rule so that it does not 654modify anything in the directory where the program was built, provided 655@samp{make all} has just been done. This is convenient for building the 656program under one user name and installing it under another. 657 658The commands should create all the directories in which files are to be 659installed, if they don't already exist. This includes the directories 660specified as the values of the variables @code{prefix} and 661@code{exec_prefix}, as well as all subdirectories that are needed. 662One way to do this is by means of an @code{installdirs} target 663as described below. 664 665Use @samp{-} before any command for installing a man page, so that 666@code{make} will ignore any errors. This is in case there are systems 667that don't have the Unix man page documentation system installed. 668 669The way to install Info files is to copy them into @file{$(infodir)} 670with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run 671the @code{install-info} program if it is present. @code{install-info} 672is a program that edits the Info @file{dir} file to add or update the 673menu entry for the given Info file; it is part of the Texinfo package. 674Here is a sample rule to install an Info file: 675 676@comment This example has been carefully formatted for the Make manual. 677@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. 678@smallexample 679$(DESTDIR)$(infodir)/foo.info: foo.info 680 $(POST_INSTALL) 681# There may be a newer info file in . than in srcdir. 682 -if test -f foo.info; then d=.; \ 683 else d=$(srcdir); fi; \ 684 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@@; \ 685# Run install-info only if it exists. 686# Use `if' instead of just prepending `-' to the 687# line so we notice real errors from install-info. 688# We use `$(SHELL) -c' because some shells do not 689# fail gracefully when there is an unknown command. 690 if $(SHELL) -c 'install-info --version' \ 691 >/dev/null 2>&1; then \ 692 install-info --dir-file=$(DESTDIR)$(infodir)/dir \ 693 $(DESTDIR)$(infodir)/foo.info; \ 694 else true; fi 695@end smallexample 696 697When writing the @code{install} target, you must classify all the 698commands into three categories: normal ones, @dfn{pre-installation} 699commands and @dfn{post-installation} commands. @xref{Install Command 700Categories}. 701 702@item install-html 703@itemx install-dvi 704@itemx install-pdf 705@itemx install-ps 706These targets install documentation in formats other than Info; 707they're intended to be called explicitly by the person installing the 708package, if that format is desired. GNU prefers Info files, so these 709must be installed by the @code{install} target. 710 711When you have many documentation files to install, we recommend that 712you avoid collisions and clutter by arranging for these targets to 713install in subdirectories of the appropriate installation directory, 714such as @code{htmldir}. As one example, if your package has multiple 715manuals, and you wish to install HTML documentation with many files 716(such as the ``split'' mode output by @code{makeinfo --html}), you'll 717certainly want to use subdirectories, or two nodes with the same name 718in different manuals will overwrite each other. 719 720@item uninstall 721Delete all the installed files---the copies that the @samp{install} 722and @samp{install-*} targets create. 723 724This rule should not modify the directories where compilation is done, 725only the directories where files are installed. 726 727The uninstallation commands are divided into three categories, just like 728the installation commands. @xref{Install Command Categories}. 729 730@item install-strip 731Like @code{install}, but strip the executable files while installing 732them. In simple cases, this target can use the @code{install} target in 733a simple way: 734 735@smallexample 736install-strip: 737 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ 738 install 739@end smallexample 740 741But if the package installs scripts as well as real executables, the 742@code{install-strip} target can't just refer to the @code{install} 743target; it has to strip the executables but not the scripts. 744 745@code{install-strip} should not strip the executables in the build 746directory which are being copied for installation. It should only strip 747the copies that are installed. 748 749Normally we do not recommend stripping an executable unless you are sure 750the program has no bugs. However, it can be reasonable to install a 751stripped executable for actual execution while saving the unstripped 752executable elsewhere in case there is a bug. 753 754@comment The gratuitous blank line here is to make the table look better 755@comment in the printed Make manual. Please leave it in. 756@item clean 757 758Delete all files in the current directory that are normally created by 759building the program. Also delete files in other directories if they 760are created by this makefile. However, don't delete the files that 761record the configuration. Also preserve files that could be made by 762building, but normally aren't because the distribution comes with 763them. There is no need to delete parent directories that were created 764with @samp{mkdir -p}, since they could have existed anyway. 765 766Delete @file{.dvi} files here if they are not part of the distribution. 767 768@item distclean 769Delete all files in the current directory (or created by this 770makefile) that are created by configuring or building the program. If 771you have unpacked the source and built the program without creating 772any other files, @samp{make distclean} should leave only the files 773that were in the distribution. However, there is no need to delete 774parent directories that were created with @samp{mkdir -p}, since they 775could have existed anyway. 776 777@item mostlyclean 778Like @samp{clean}, but may refrain from deleting a few files that people 779normally don't want to recompile. For example, the @samp{mostlyclean} 780target for GCC does not delete @file{libgcc.a}, because recompiling it 781is rarely necessary and takes a lot of time. 782 783@item maintainer-clean 784Delete almost everything that can be reconstructed with this Makefile. 785This typically includes everything deleted by @code{distclean}, plus 786more: C source files produced by Bison, tags tables, Info files, and 787so on. 788 789The reason we say ``almost everything'' is that running the command 790@samp{make maintainer-clean} should not delete @file{configure} even 791if @file{configure} can be remade using a rule in the Makefile. More 792generally, @samp{make maintainer-clean} should not delete anything 793that needs to exist in order to run @file{configure} and then begin to 794build the program. Also, there is no need to delete parent 795directories that were created with @samp{mkdir -p}, since they could 796have existed anyway. These are the only exceptions; 797@code{maintainer-clean} should delete everything else that can be 798rebuilt. 799 800The @samp{maintainer-clean} target is intended to be used by a maintainer of 801the package, not by ordinary users. You may need special tools to 802reconstruct some of the files that @samp{make maintainer-clean} deletes. 803Since these files are normally included in the distribution, we don't 804take care to make them easy to reconstruct. If you find you need to 805unpack the full distribution again, don't blame us. 806 807To help make users aware of this, the commands for the special 808@code{maintainer-clean} target should start with these two: 809 810@smallexample 811@@echo 'This command is intended for maintainers to use; it' 812@@echo 'deletes files that may need special tools to rebuild.' 813@end smallexample 814 815@item TAGS 816Update a tags table for this program. 817@c ADR: how? 818 819@item info 820Generate any Info files needed. The best way to write the rules is as 821follows: 822 823@smallexample 824info: foo.info 825 826foo.info: foo.texi chap1.texi chap2.texi 827 $(MAKEINFO) $(srcdir)/foo.texi 828@end smallexample 829 830@noindent 831You must define the variable @code{MAKEINFO} in the Makefile. It should 832run the @code{makeinfo} program, which is part of the Texinfo 833distribution. 834 835Normally a GNU distribution comes with Info files, and that means the 836Info files are present in the source directory. Therefore, the Make 837rule for an info file should update it in the source directory. When 838users build the package, ordinarily Make will not update the Info files 839because they will already be up to date. 840 841@item dvi 842@itemx html 843@itemx pdf 844@itemx ps 845Generate documentation files in the given format, if possible. 846Here's an example rule for generating DVI files from Texinfo: 847 848@smallexample 849dvi: foo.dvi 850 851foo.dvi: foo.texi chap1.texi chap2.texi 852 $(TEXI2DVI) $(srcdir)/foo.texi 853@end smallexample 854 855@noindent 856You must define the variable @code{TEXI2DVI} in the Makefile. It should 857run the program @code{texi2dvi}, which is part of the Texinfo 858distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work 859of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, 860write just the dependencies, and allow GNU @code{make} to provide the command. 861 862Here's another example, this one for generating HTML from Texinfo: 863 864@smallexample 865html: foo.html 866 867foo.html: foo.texi chap1.texi chap2.texi 868 $(TEXI2HTML) $(srcdir)/foo.texi 869@end smallexample 870 871@noindent 872Again, you would define the variable @code{TEXI2HTML} in the Makefile; 873for example, it might run @code{makeinfo --no-split --html} 874(@command{makeinfo} is part of the Texinfo distribution). 875 876@item dist 877Create a distribution tar file for this program. The tar file should be 878set up so that the file names in the tar file start with a subdirectory 879name which is the name of the package it is a distribution for. This 880name can include the version number. 881 882For example, the distribution tar file of GCC version 1.40 unpacks into 883a subdirectory named @file{gcc-1.40}. 884 885The easiest way to do this is to create a subdirectory appropriately 886named, use @code{ln} or @code{cp} to install the proper files in it, and 887then @code{tar} that subdirectory. 888 889Compress the tar file with @code{gzip}. For example, the actual 890distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. 891 892The @code{dist} target should explicitly depend on all non-source files 893that are in the distribution, to make sure they are up to date in the 894distribution. 895@ifset CODESTD 896@xref{Releases, , Making Releases}. 897@end ifset 898@ifclear CODESTD 899@xref{Releases, , Making Releases, standards, GNU Coding Standards}. 900@end ifclear 901 902@item check 903Perform self-tests (if any). The user must build the program before 904running the tests, but need not install the program; you should write 905the self-tests so that they work when the program is built but not 906installed. 907@end table 908 909The following targets are suggested as conventional names, for programs 910in which they are useful. 911 912@table @code 913@item installcheck 914Perform installation tests (if any). The user must build and install 915the program before running the tests. You should not assume that 916@file{$(bindir)} is in the search path. 917 918@item installdirs 919It's useful to add a target named @samp{installdirs} to create the 920directories where files are installed, and their parent directories. 921There is a script called @file{mkinstalldirs} which is convenient for 922this; you can find it in the Texinfo package. 923@c It's in /gd/gnu/lib/mkinstalldirs. 924You can use a rule like this: 925 926@comment This has been carefully formatted to look decent in the Make manual. 927@comment Please be sure not to make it extend any further to the right.--roland 928@smallexample 929# Make sure all installation directories (e.g. $(bindir)) 930# actually exist by making them if necessary. 931installdirs: mkinstalldirs 932 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ 933 $(libdir) $(infodir) \ 934 $(mandir) 935@end smallexample 936 937@noindent 938or, if you wish to support @env{DESTDIR}, 939 940@smallexample 941# Make sure all installation directories (e.g. $(bindir)) 942# actually exist by making them if necessary. 943installdirs: mkinstalldirs 944 $(srcdir)/mkinstalldirs \ 945 $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ 946 $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ 947 $(DESTDIR)$(mandir) 948@end smallexample 949 950This rule should not modify the directories where compilation is done. 951It should do nothing but create installation directories. 952@end table 953 954@node Install Command Categories 955@section Install Command Categories 956 957@cindex pre-installation commands 958@cindex post-installation commands 959When writing the @code{install} target, you must classify all the 960commands into three categories: normal ones, @dfn{pre-installation} 961commands and @dfn{post-installation} commands. 962 963Normal commands move files into their proper places, and set their 964modes. They may not alter any files except the ones that come entirely 965from the package they belong to. 966 967Pre-installation and post-installation commands may alter other files; 968in particular, they can edit global configuration files or data bases. 969 970Pre-installation commands are typically executed before the normal 971commands, and post-installation commands are typically run after the 972normal commands. 973 974The most common use for a post-installation command is to run 975@code{install-info}. This cannot be done with a normal command, since 976it alters a file (the Info directory) which does not come entirely and 977solely from the package being installed. It is a post-installation 978command because it needs to be done after the normal command which 979installs the package's Info files. 980 981Most programs don't need any pre-installation commands, but we have the 982feature just in case it is needed. 983 984To classify the commands in the @code{install} rule into these three 985categories, insert @dfn{category lines} among them. A category line 986specifies the category for the commands that follow. 987 988A category line consists of a tab and a reference to a special Make 989variable, plus an optional comment at the end. There are three 990variables you can use, one for each category; the variable name 991specifies the category. Category lines are no-ops in ordinary execution 992because these three Make variables are normally undefined (and you 993@emph{should not} define them in the makefile). 994 995Here are the three possible category lines, each with a comment that 996explains what it means: 997 998@smallexample 999 $(PRE_INSTALL) # @r{Pre-install commands follow.} 1000 $(POST_INSTALL) # @r{Post-install commands follow.} 1001 $(NORMAL_INSTALL) # @r{Normal commands follow.} 1002@end smallexample 1003 1004If you don't use a category line at the beginning of the @code{install} 1005rule, all the commands are classified as normal until the first category 1006line. If you don't use any category lines, all the commands are 1007classified as normal. 1008 1009These are the category lines for @code{uninstall}: 1010 1011@smallexample 1012 $(PRE_UNINSTALL) # @r{Pre-uninstall commands follow.} 1013 $(POST_UNINSTALL) # @r{Post-uninstall commands follow.} 1014 $(NORMAL_UNINSTALL) # @r{Normal commands follow.} 1015@end smallexample 1016 1017Typically, a pre-uninstall command would be used for deleting entries 1018from the Info directory. 1019 1020If the @code{install} or @code{uninstall} target has any dependencies 1021which act as subroutines of installation, then you should start 1022@emph{each} dependency's commands with a category line, and start the 1023main target's commands with a category line also. This way, you can 1024ensure that each command is placed in the right category regardless of 1025which of the dependencies actually run. 1026 1027Pre-installation and post-installation commands should not run any 1028programs except for these: 1029 1030@example 1031[ basename bash cat chgrp chmod chown cmp cp dd diff echo 1032egrep expand expr false fgrep find getopt grep gunzip gzip 1033hostname install install-info kill ldconfig ln ls md5sum 1034mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee 1035test touch true uname xargs yes 1036@end example 1037 1038@cindex binary packages 1039The reason for distinguishing the commands in this way is for the sake 1040of making binary packages. Typically a binary package contains all the 1041executables and other files that need to be installed, and has its own 1042method of installing them---so it does not need to run the normal 1043installation commands. But installing the binary package does need to 1044execute the pre-installation and post-installation commands. 1045 1046Programs to build binary packages work by extracting the 1047pre-installation and post-installation commands. Here is one way of 1048extracting the pre-installation commands (the @option{-s} option to 1049@command{make} is needed to silence messages about entering 1050subdirectories): 1051 1052@smallexample 1053make -s -n install -o all \ 1054 PRE_INSTALL=pre-install \ 1055 POST_INSTALL=post-install \ 1056 NORMAL_INSTALL=normal-install \ 1057 | gawk -f pre-install.awk 1058@end smallexample 1059 1060@noindent 1061where the file @file{pre-install.awk} could contain this: 1062 1063@smallexample 1064$0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@} 1065on @{print $0@} 1066$0 ~ /^pre-install[ \t]*$/ @{on = 1@} 1067@end smallexample 1068