X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fmake-stds.texi;h=cd9f0623a03e587b659ddc700dee788a91ac3a3e;hb=f8211e803844eb6112f5f045709b808e2e089ebe;hp=8b58fa0a8b2b0fe873eee75ae318d75e0dd2fe7e;hpb=a0d72143f3350c955a423ab810cb9dc42c21959b;p=gnulib.git diff --git a/doc/make-stds.texi b/doc/make-stds.texi index 8b58fa0a8..cd9f0623a 100644 --- a/doc/make-stds.texi +++ b/doc/make-stds.texi @@ -8,8 +8,8 @@ @cindex conventions for makefiles @cindex standards for makefiles -@c Copyright 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free -@c Software Foundation, Inc. +@c Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001, +@c 2004, 2005 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.1 @@ -293,9 +293,18 @@ installed. Installation directories should always be named by variables, so it is easy to install in a nonstandard place. The standard names for these -variables are described below. They are based on a standard filesystem -layout; variants of it are used in SVR4, 4.4BSD, GNU/Linux, Ultrix v4, -and other modern operating systems. +variables and the values they should have in GNU packages are +described below. They are based on a standard filesystem layout; +variants of it are used in GNU/Linux and other modern operating +systems. + +Installers are expected to override these values when calling +@command{make} (e.g., @kbd{make prefix=/usr install} or +@command{configure} (e.g., @kbd{configure --prefix=/usr}). GNU +packages should not try to guess which value should be appropriate for +these variables on the system they are being installed onto: use the +default settings specified here so that all GNU packages behave +identically, allowing the installer to achieve any desired layout. These two variables set the root for the installation. All the other installation directories should be subdirectories of one of these two, @@ -355,6 +364,12 @@ The directory for installing executable programs to be run by other programs rather than by users. This directory should normally be @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}. (If you are using Autoconf, write it as @samp{@@libexecdir@@}.) + +The definition of @samp{libexecdir} is the same for all packages, so +you should install your data in a subdirectory thereof. Most packages +install their data under @file{$(libexecdir)/@var{package-name}/}, +possibly within additional subdirectories thereof, such as +@file{$(libexecdir)/@var{package-name}/@var{machine}/@var{version}}. @end table Data files used by the program during its execution are divided into @@ -384,20 +399,26 @@ to put these various kinds of files in: @item datarootdir The root of the directory tree for read-only architecture-independent data files. This should normally be @file{/usr/local/share}, but -write it as @file{$(prefix)/share}. @samp{datadir}'s default value is -based on this variable; so are @samp{infodir}, @samp{mandir}, and others. +write it as @file{$(prefix)/share}. (If you are using Autoconf, write +it as @samp{@@datarootdir@@}.) @samp{datadir}'s default value is +based on this variable; so are @samp{infodir}, @samp{mandir}, and +others. @item datadir -The directory for installing ideosyncratic read-only +The directory for installing idiosyncratic read-only architecture-independent data files for this program. This is usually the same place as @samp{datarootdir}, but we use the two separate -variables so that you can move these ideosyncratic files without +variables so that you can move these program-specific files without altering the location for Info files, man pages, etc. -The default definition of @samp{datadir} should be +This should normally be @file{/usr/local/share}, but write it as @file{$(datarootdir)}. (If you are using Autoconf, write it as @samp{@@datadir@@}.) +The definition of @samp{datadir} is the same for all packages, so you +should install your data in a subdirectory thereof. Most packages +install their data under @file{$(datadir)/@var{package-name}/}. + @item sysconfdir The directory for installing read-only data files that pertain to a single machine--that is to say, files for configuring a host. Mailer @@ -471,11 +492,34 @@ package. To tell whether @file{foo.h} came from the Foo package, put a magic string in the file---part of a comment---and @code{grep} for that string. +@item docdir +The directory for installing documentation files (other than Info) for +this package. By default, it should be +@file{/usr/local/share/doc/@var{yourpkg}}, but it should be written as +@file{$(datarootdir)/doc/@var{yourpkg}}. (If you are using Autoconf, +write it as @samp{@@docdir@@}.) The @var{yourpkg} subdirectory, which +may include a version number, prevents collisions among files with +common names, such as @file{README}. + @item infodir The directory for installing the Info files for this package. By default, it should be @file{/usr/local/share/info}, but it should be written as @file{$(datarootdir)/info}. (If you are using Autoconf, -write it as @samp{@@infodir@@}.) +write it as @samp{@@infodir@@}.) @code{infodir} is separate from +@code{docdir} for compatibility with existing practice. + +@item htmldir +@itemx dvidir +@itemx pdfdir +@itemx psdir +Directories for installing documentation files in the particular +format. (It is not required to support documentation in all these +formats.) They should all be set to @code{$(docdir)} by default. (If +you are using Autoconf, write them as @samp{@@htmldir@@}, +@samp{@@dvidir@@}, etc.) Packages which supply several translations +of their documentation should install them in +@samp{$(htmldir)/}@var{ll}, @samp{$(pdfdir)/}@var{ll}, etc. where +@var{ll} is a locale abbreviation such as @samp{en} or @samp{pt_BR}. @item libdir The directory for object files and libraries of object code. Do not @@ -502,7 +546,8 @@ AC_SUBST(lispdir) The directory for installing locale-specific message catalogs for this package. By default, it should be @file{/usr/local/share/locale}, but it should be written as @file{$(datarootdir)/locale}. (If you are -using Autoconf, write it as @samp{@@localedir@@}.) +using Autoconf, write it as @samp{@@localedir@@}.) This directory +usually has a subdirectory per locale. @end table Unix-style man pages are installed in one of the following: @@ -654,9 +699,27 @@ commands into three categories: normal ones, @dfn{pre-installation} commands and @dfn{post-installation} commands. @xref{Install Command Categories}. +@item install-html +@itemx install-dvi +@itemx install-pdf +@itemx install-ps +These targets install documentation in formats other than Info; +they're intended to be called explicitly by the person installing the +package, if that format is desired. GNU prefers Info files, so these +must be installed by the @code{install} target. + +When you have many documentation files to install, we recommend that +you avoid collisions and clutter by arranging for these targets to +install in subdirectories of the appropriate installation directory, +such as @code{htmldir}. As one example, if your package has multiple +manuals, and you wish to install HTML documentation with many files +(such as the ``split'' mode output by @code{makeinfo --html}), you'll +certainly want to use subdirectories, or two nodes with the same name +in different manuals will overwrite each other. + @item uninstall Delete all the installed files---the copies that the @samp{install} -target creates. +and @samp{install-*} targets create. This rule should not modify the directories where compilation is done, only the directories where files are installed. @@ -692,18 +755,24 @@ executable elsewhere in case there is a bug. @comment in the printed Make manual. Please leave it in. @item clean -Delete all files from the current directory that are normally created by -building the program. Don't delete the files that record the -configuration. Also preserve files that could be made by building, but -normally aren't because the distribution comes with them. +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 +record the configuration. Also preserve files that could be made by +building, but normally aren't because the distribution comes with +them. There is no need to delete parent directories that were created +with @samp{mkdir -p}, since they could have existed anyway. Delete @file{.dvi} files here if they are not part of the distribution. @item distclean -Delete all files from the current directory that are created by -configuring or building the program. If you have unpacked the source -and built the program without creating any other files, @samp{make -distclean} should leave only the files that were in the distribution. +Delete all files in the current directory (or created by this +makefile) that are created by configuring or building the program. If +you have unpacked the source and built the program without creating +any other files, @samp{make distclean} should leave only the files +that were in the distribution. However, there is no need to delete +parent directories that were created with @samp{mkdir -p}, since they +could have existed anyway. @item mostlyclean Like @samp{clean}, but may refrain from deleting a few files that people @@ -712,18 +781,21 @@ target for GCC does not delete @file{libgcc.a}, because recompiling it is rarely necessary and takes a lot of time. @item maintainer-clean -Delete almost everything from the current directory that can be -reconstructed with this Makefile. This typically includes everything -deleted by @code{distclean}, plus more: C source files produced by -Bison, tags tables, Info files, and so on. +Delete almost everything that can be reconstructed with this Makefile. +This typically includes everything deleted by @code{distclean}, plus +more: C source files produced by Bison, tags tables, Info files, and +so on. The reason we say ``almost everything'' is that running the command -@samp{make maintainer-clean} should not delete @file{configure} even if -@file{configure} can be remade using a rule in the Makefile. More generally, -@samp{make maintainer-clean} should not delete anything that needs to -exist in order to run @file{configure} and then begin to build the -program. This is the only exception; @code{maintainer-clean} should -delete everything else that can be rebuilt. +@samp{make maintainer-clean} should not delete @file{configure} even +if @file{configure} can be remade using a rule in the Makefile. More +generally, @samp{make maintainer-clean} should not delete anything +that needs to exist in order to run @file{configure} and then begin to +build the program. Also, there is no need to delete parent +directories that were created with @samp{mkdir -p}, since they could +have existed anyway. These are the only exceptions; +@code{maintainer-clean} should delete everything else that can be +rebuilt. The @samp{maintainer-clean} target is intended to be used by a maintainer of the package, not by ordinary users. You may need special tools to @@ -767,8 +839,11 @@ users build the package, ordinarily Make will not update the Info files because they will already be up to date. @item dvi -Generate DVI files for all Texinfo documentation. -For example: +@itemx html +@itemx pdf +@itemx ps +Generate documentation files in the given format, if possible. +Here's an example rule for generating DVI files from Texinfo: @smallexample dvi: foo.dvi @@ -784,6 +859,20 @@ 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. +Here's another example, this one for generating HTML from Texinfo: + +@smallexample +html: foo.html + +foo.html: foo.texi chap1.texi chap2.texi + $(TEXI2HTML) $(srcdir)/foo.texi +@end smallexample + +@noindent +Again, you would define the variable @code{TEXI2HTML} in the Makefile; +for example, it might run @code{makeinfo --no-split --html} +(@command{makeinfo} is part of the Texinfo distribution). + @item dist Create a distribution tar file for this program. The tar file should be set up so that the file names in the tar file start with a subdirectory @@ -956,10 +1045,12 @@ execute the pre-installation and post-installation commands. Programs to build binary packages work by extracting the pre-installation and post-installation commands. Here is one way of -extracting the pre-installation commands: +extracting the pre-installation commands (the @option{-s} option to +@command{make} is needed to silence messages about entering +subdirectories): @smallexample -make -n install -o all \ +make -s -n install -o all \ PRE_INSTALL=pre-install \ POST_INSTALL=post-install \ NORMAL_INSTALL=normal-install \ @@ -970,10 +1061,7 @@ make -n install -o all \ where the file @file{pre-install.awk} could contain this: @smallexample -$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ @{on = 0@} +$0 ~ /^(normal-install|post-install)[ \t]*$/ @{on = 0@} on @{print $0@} -$0 ~ /^\t[ \t]*pre_install[ \t]*$/ @{on = 1@} +$0 ~ /^pre-install[ \t]*$/ @{on = 1@} @end smallexample - -The resulting file of pre-installation commands is executed as a shell -script as part of installing the binary package.