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