X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fmake-stds.texi;h=db0162877f99fc224473930613f67c6dda81e93f;hb=bbfcd2f1a92c9bdbb8d7d7d0a8a8c6665c316747;hp=c8e0d6387089b8e71861639ad1fb1035746cb710;hpb=2709233ead439b582d82af48bd25e709378cda44;p=gnulib.git diff --git a/doc/make-stds.texi b/doc/make-stds.texi index c8e0d6387..db0162877 100644 --- a/doc/make-stds.texi +++ b/doc/make-stds.texi @@ -8,7 +8,7 @@ @cindex standards for makefiles @c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001, -@c 2004, 2005, 2006, 2007, 2008, 2010 Free Software Foundation, Inc. +@c 2004, 2005, 2006, 2007, 2008, 2010, 2013 Free Software Foundation, Inc. @c @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.3 @@ -159,8 +159,8 @@ installation should not use any utilities directly except these: @c mkfifo mknod tee uname @example -awk cat cmp cp diff echo egrep expr false grep install-info -ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch tr true +awk cat cmp cp diff echo egrep expr false grep install-info ln ls +mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true @end example Compression programs such as @code{gzip} can be used in the @@ -320,7 +320,7 @@ make DESTDIR=/tmp/stage install useful. If your installation step would normally install -@file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an +@file{/usr/local/bin/foo} and @file{/usr/@/local/@/lib/@/libfoo.a}, then an installation invoked as in the example above would install @file{/tmp/stage/usr/local/bin/foo} and @file{/tmp/stage/usr/local/lib/libfoo.a} instead. @@ -478,9 +478,11 @@ the same place as @samp{datarootdir}, but we use the two separate variables so that you can move these program-specific files without altering the location for Info files, man pages, etc. +@c raggedright (not until next Texinfo release) This should normally be @file{/usr/local/share}, but write it as @file{$(datarootdir)}. (If you are using Autoconf, write it as @samp{@@datadir@@}.) +@c end raggedright The definition of @samp{datadir} is the same for all packages, so you should install your data in a subdirectory thereof. Most packages @@ -516,6 +518,19 @@ in @file{$(datadir)} or @file{$(sysconfdir)}. @file{$(localstatedir)} should normally be @file{/usr/local/var}, but write it as @file{$(prefix)/var}. (If you are using Autoconf, write it as @samp{@@localstatedir@@}.) + +@item runstatedir +The directory for installing data files which the programs modify +while they run, that pertain to one specific machine, and which need +not persist longer than the execution of the program---which is +generally long-lived, for example, until the next reboot. PID files +for system daemons are a typical use. In addition, this directory +should not be cleaned except perhaps at reboot, while the general +@file{/tmp} (@code{TMPDIR}) may be cleaned arbitrarily. This should +normally be @file{/var/run}, but write it as +@file{$(localstatedir)/run}. Having it as a separate variable allows +the use of @file{/run} if desired, for example. (If you are using +Autoconf 2.70 or later, write it as @samp{@@runstatedir@@}.) @end table These variables specify the directory for installing certain specific @@ -525,7 +540,6 @@ need @samp{libdir} or @samp{lispdir}. @table @samp @item includedir -@c rewritten to avoid overfull hbox --roland The directory for installing header files to be included by user programs with the C @samp{#include} preprocessor directive. This should normally be @file{/usr/local/include}, but write it as @@ -601,7 +615,7 @@ should be written as @file{$(datarootdir)/emacs/site-lisp}. If you are using Autoconf, write the default as @samp{@@lispdir@@}. In order to make @samp{@@lispdir@@} work, you need the following lines -in your @file{configure.in} file: +in your @file{configure.ac} file: @example lispdir='$@{datarootdir@}/emacs/site-lisp' @@ -714,8 +728,9 @@ documentation format) files should be made only when explicitly asked for. By default, the Make rules should compile and link with @samp{-g}, so -that executable programs have debugging symbols. Users who don't mind -being helpless can strip the executables later if they wish. +that executable programs have debugging symbols. Otherwise, you are +essentially helpless in the face of a crash, and it is often far from +easy to reproduce with a fresh build. @item install Compile the program and copy the executables, libraries, and so on to @@ -723,8 +738,11 @@ the file names where they should reside for actual use. If there is a simple test to verify that a program is properly installed, this target should run that test. -Do not strip executables when installing them. Devil-may-care users can -use the @code{install-strip} target to do that. +Do not strip executables when installing them. This helps eventual +debugging that may be needed later, and nowadays disk space is cheap +and dynamic loaders typically ensure debug sections are not loaded during +normal execution. Users that need stripped binaries may invoke the +@code{install-strip} target to do that. If possible, write the @code{install} target rule so that it does not modify anything in the directory where the program was built, provided @@ -836,10 +854,7 @@ the program has no bugs. However, it can be reasonable to install a stripped executable for actual execution while saving the unstripped executable elsewhere in case there is a bug. -@comment The gratuitous blank line here is to make the table look better -@comment in the printed Make manual. Please leave it in. @item clean - Delete all files in the current directory that are normally created by building the program. Also delete files in other directories if they are created by this makefile. However, don't delete the files that @@ -942,11 +957,12 @@ foo.dvi: foo.texi chap1.texi chap2.texi @end smallexample @noindent -You must define the variable @code{TEXI2DVI} in the Makefile. It should -run the program @code{texi2dvi}, which is part of the Texinfo -distribution.@footnote{@code{texi2dvi} uses @TeX{} to do the real work -of formatting. @TeX{} is not distributed with Texinfo.} Alternatively, -write just the dependencies, and allow GNU @code{make} to provide the command. +You must define the variable @code{TEXI2DVI} in the Makefile. It +should run the program @code{texi2dvi}, which is part of the Texinfo +distribution. (@code{texi2dvi} uses @TeX{} to do the real work of +formatting. @TeX{} is not distributed with Texinfo.) Alternatively, +write only the dependencies, and allow GNU @code{make} to provide the +command. Here's another example, this one for generating HTML from Texinfo: