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