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