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