diff options
| -rw-r--r-- | make-stds.texi | 495 |
1 files changed, 267 insertions, 228 deletions
diff --git a/make-stds.texi b/make-stds.texi index b89d899..6a1827f 100644 --- a/make-stds.texi +++ b/make-stds.texi @@ -8,14 +8,26 @@ @cindex conventions for makefiles @cindex standards for makefiles -This chapter describes conventions for writing the Makefiles for GNU programs. +This +@ifinfo +node +@end ifinfo +@iftex +@ifset CODESTD +section +@end ifset +@ifclear CODESTD +chapter +@end ifclear +@end iftex +describes conventions for writing the Makefiles for GNU programs. @menu -* Makefile Basics:: -* Utilities in Makefiles:: -* Standard Targets:: -* Command Variables:: -* Directory Variables:: +* Makefile Basics:: General Conventions for Makefiles +* Utilities in Makefiles:: Utilities in Makefiles +* Command Variables:: Variables for Specifying Commands +* Directory Variables:: Variables for Installation Directories +* Standard Targets:: Standard Targets for Users @end menu @node Makefile Basics @@ -71,7 +83,7 @@ When using GNU @code{make}, relying on @samp{VPATH} to find the source file will work in the case where there is a single dependency file, since the @code{make} automatic variable @samp{$<} will represent the source file wherever it is. (Many versions of @code{make} set @samp{$<} -only in implicit rules.) A makefile target like +only in implicit rules.) A Makefile target like @smallexample foo.o : bar.c @@ -140,226 +152,15 @@ When you use @code{ranlib}, you should make sure nothing bad happens if the system does not have @code{ranlib}. Arrange to ignore an error from that command, and print a message before the command to tell the user that failure of the @code{ranlib} command does not mean a problem. +(The Autoconf @samp{AC_PROG_RANLIB} macro can help with this.) If you use symbolic links, you should implement a fallback for systems that don't have symbolic links. It is ok to use other utilities in Makefile portions (or scripts) -intended only for particular systems where you know those utilities to +intended only for particular systems where you know those utilities exist. -@node Standard Targets -@section Standard Targets for Users - -All GNU programs should have the following targets in their Makefiles: - -@table @samp -@item all -Compile the entire program. This should be the default target. This -target need not rebuild any documentation files; Info files should -normally be included in the distribution, and DVI files should be made -only when explicitly asked for. - -@item install -Compile the program and copy the executables, libraries, and so on to -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. - -If possible, write the @code{install} target rule so that it does not -modify anything in the directory where the program was built, provided -@samp{make all} has just been done. This is convenient for building the -program under one user name and installing it under another. - -The commands should create all the directories in which files are to be -installed, if they don't already exist. This includes the directories -specified as the values of the variables @code{prefix} and -@code{exec_prefix}, as well as all subdirectories that are needed. -One way to do this is by means of an @code{installdirs} target -as described below. - -Use @samp{-} before any command for installing a man page, so that -@code{make} will ignore any errors. This is in case there are systems -that don't have the Unix man page documentation system installed. - -The way to install Info files is to copy them into @file{$(infodir)} -with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run -the @code{install-info} program if it is present. @code{install-info} -is a script that edits the Info @file{dir} file to add or update the -menu entry for the given Info file; it will be part of the Texinfo package. -Here is a sample rule to install an Info file: - -@comment This example has been carefully formatted for the Make manual. -@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. -@smallexample -$(infodir)/foo.info: foo.info -# There may be a newer info file in . than in srcdir. - -if test -f foo.info; then d=.; \ - else d=$(srcdir); fi; \ - $(INSTALL_DATA) $$d/foo.info $@@; \ -# Run install-info only if it exists. -# Use `if' instead of just prepending `-' to the -# line so we notice real errors from install-info. -# We use `$(SHELL) -c' because some shells do not -# fail gracefully when there is an unknown command. - if $(SHELL) -c 'install-info --version' \ - >/dev/null 2>&1; then \ - install-info --infodir=$(infodir) $$d/foo.info; \ - else true; fi -@end smallexample - -@item uninstall -Delete all the installed files that the @samp{install} target would -create (but not the noninstalled files such as @samp{make all} would -create). - -This rule should not modify the directories where compilation is done, -only the directories where files are installed. - -@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 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 @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. - -@item mostlyclean -Like @samp{clean}, but may refrain from deleting a few files that people -normally don't want to recompile. For example, the @samp{mostlyclean} -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. - -The reason we say ``almost everything'' is that running the command -@samp{make maintainer-clean} should not delete @file{configure} even if -it 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. - -The @samp{maintainer-clean} is intended to be used by a maintainer of -the package, not by ordinary users. You may need special tools to -reconstruct some of the files that @samp{make maintainer-clean} deletes. -Since these files are normally included in the distribution, we don't -take care to make them easy to reconstruct. If you find you need to -unpack the full distribution again, don't blame us. - -To help make users aware of this, the commands for the special -@code{maintainer-clean} target should start with these two: - -@smallexample -@@echo "This command is intended for maintainers to use; it" -@@echo "deletes files that may require special tools to rebuild." -@end smallexample - -@item TAGS -Update a tags table for this program. - -@item info -Generate any Info files needed. The best way to write the rules is as -follows: - -@smallexample -info: foo.info - -foo.info: foo.texi chap1.texi chap2.texi - $(MAKEINFO) $(srcdir)/foo.texi -@end smallexample - -@noindent -You must define the variable @code{MAKEINFO} in the Makefile. It should -run the @code{makeinfo} program, which is part of the Texinfo -distribution. - -@item dvi -Generate DVI files for all TeXinfo documentation. -For example: - -@smallexample -dvi: foo.dvi - -foo.dvi: foo.texi chap1.texi chap2.texi - $(TEXI2DVI) $(srcdir)/foo.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. Alternatively, write just the dependencies, and allow GNU -Make to provide the command. - -@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 -name which is the name of the package it is a distribution for. This -name can include the version number. - -For example, the distribution tar file of GCC version 1.40 unpacks into -a subdirectory named @file{gcc-1.40}. - -The easiest way to do this is to create a subdirectory appropriately -named, use @code{ln} or @code{cp} to install the proper files in it, and -then @code{tar} that subdirectory. - -The @code{dist} target should explicitly depend on all non-source files -that are in the distribution, to make sure they are up to date in the -distribution. -@xref{Releases, , Making Releases, standards, GNU Coding Standards}. - -@item check -Perform self-tests (if any). The user must build the program before -running the tests, but need not install the program; you should write -the self-tests so that they work when the program is built but not -installed. -@end table - -The following targets are suggested as conventional names, for programs -in which they are useful. - -@table @code -@item installcheck -Perform installation tests (if any). The user must build and install -the program before running the tests. You should not assume that -@file{$(bindir)} is in the search path. - -@item installdirs -It's useful to add a target named @samp{installdirs} to create the -directories where files are installed, and their parent directories. -There is a script called @file{mkinstalldirs} which is convenient for -this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs. -You can use a rule like this: - -@comment This has been carefully formatted to look decent in the Make manual. -@comment Please be sure not to make it extend any further to the right.--roland -@smallexample -# Make sure all installation directories (e.g. $(bindir)) -# actually exist by making them if necessary. -installdirs: mkinstalldirs - $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ - $(libdir) $(infodir) \ - $(mandir) -@end smallexample - -This rule should not modify the directories where compilation is done. -It should do nothing but create installation directories. -@end table - @node Command Variables @section Variables for Specifying Commands @@ -446,11 +247,13 @@ A prefix used in constructing the default values of the variables listed below. The default value of @code{prefix} should be @file{/usr/local}. When building the complete GNU system, the prefix will be empty and @file{/usr} will be a symbolic link to @file{/}. +(If you are using Autoconf, write it as @samp{@@prefix@@}.) @item exec_prefix A prefix used in constructing the default values of some of the variables listed below. The default value of @code{exec_prefix} should be @code{$(prefix)}. +(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.) Generally, @code{$(exec_prefix)} is used for directories that contain machine-specific files (such as executables and subroutine libraries), @@ -464,18 +267,21 @@ Executable programs are installed in one of the following directories. The directory for installing executable programs that users can run. This should normally be @file{/usr/local/bin}, but write it as @file{$(exec_prefix)/bin}. +(If you are using Autoconf, write it as @samp{@@bindir@@}.) @item sbindir The directory for installing executable programs that can be run from the shell, but are only generally useful to system administrators. This should normally be @file{/usr/local/sbin}, but write it as @file{$(exec_prefix)/sbin}. +(If you are using Autoconf, write it as @samp{@@sbindir@@}.) @item libexecdir @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94 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@@}.) @end table Data files used by the program during its execution are divided into @@ -494,18 +300,20 @@ be shared between two machines. @end itemize This makes for six different possibilities. However, we want to -discourage the use of architecture-dependent files, aside from of object +discourage the use of architecture-dependent files, aside from object files and libraries. It is much cleaner to make other data files architecture-independent, and it is generally not hard. -Therefore, here are the variables makefiles should use to specify +Therefore, here are the variables Makefiles should use to specify directories: @table @samp @item datadir The directory for installing read-only architecture independent data files. This should normally be @file{/usr/local/share}, but write it as -@file{$(prefix)/share}. As a special exception, see @file{$(infodir)} +@file{$(prefix)/share}. +(If you are using Autoconf, write it as @samp{@@datadir@@}.) +As a special exception, see @file{$(infodir)} and @file{$(includedir)} below. @item sysconfdir @@ -515,12 +323,13 @@ and network configuration files, @file{/etc/passwd}, and so forth belong here. All the files in this directory should be ordinary ASCII text files. This directory should normally be @file{/usr/local/etc}, but write it as @file{$(prefix)/etc}. +(If you are using Autoconf, write it as @samp{@@sysconfdir@@}.) @c rewritten to avoid overfull hbox --tower Do not install executables @c here in this directory (they probably -belong in @file{$(libexecdir)} or @file{$(sbindir))}. Also do not +belong in @file{$(libexecdir)} or @file{$(sbindir)}). Also do not install files that are modified in the normal course of their use (programs whose purpose is to change the configuration of the system excluded). Those probably belong in @file{$(localstatedir)}. @@ -529,26 +338,30 @@ excluded). Those probably belong in @file{$(localstatedir)}. The directory for installing architecture-independent data files which the programs modify while they run. This should normally be @file{/usr/local/com}, but write it as @file{$(prefix)/com}. +(If you are using Autoconf, write it as @samp{@@sharedstatedir@@}.) @item localstatedir The directory for installing data files which the programs modify while they run, and that pertain to one specific machine. Users should never need to modify files in this directory to configure the package's operation; put such configuration information in separate files that go -in @file{datadir} or @file{$(sysconfdir)}. @file{$(localstatedir)} +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 libdir The directory for object files and libraries of object code. Do not install executables here, they probably belong in @file{$(libexecdir)} instead. The value of @code{libdir} should normally be @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. +(If you are using Autoconf, write it as @samp{@@libdir@@}.) @item infodir The directory for installing the Info files for this package. By default, it should be @file{/usr/local/info}, but it should be written as @file{$(prefix)/info}. +(If you are using Autoconf, write it as @samp{@@infodir@@}.) @item includedir @c rewritten to avoid overfull hbox --roland @@ -556,6 +369,7 @@ 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 @file{$(prefix)/include}. +(If you are using Autoconf, write it as @samp{@@includedir@@}.) Most compilers other than GCC do not look for header files in @file{/usr/local/include}. So installing the header files this way is @@ -568,6 +382,7 @@ specified by @code{oldincludedir}. @item oldincludedir The directory for installing @samp{#include} header files for use with compilers other than GCC. This should normally be @file{/usr/include}. +(If you are using Autoconf, you can write it as @samp{@@oldincludedir@@}.) The Makefile commands should check whether the value of @code{oldincludedir} is empty. If it is, they should not try to use @@ -581,7 +396,7 @@ file in the @code{oldincludedir} directory if either (1) there is no package. To tell whether @file{foo.h} came from the Foo package, put a magic -string in the file---part of a comment---and grep for that string. +string in the file---part of a comment---and @code{grep} for that string. @end table Unix-style man pages are installed in one of the following: @@ -590,14 +405,15 @@ Unix-style man pages are installed in one of the following: @item mandir The top-level directory for installing the man pages (if any) for this package. It will normally be @file{/usr/local/man}, but you should -write it as @file{$(prefix)/man}. +write it as @file{$(prefix)/man}. +(If you are using Autoconf, write it as @samp{@@mandir@@}.) @item man1dir The directory for installing section 1 man pages. Write it as @file{$(mandir)/man1}. @item man2dir The directory for installing section 2 man pages. Write it as -@file{$(mandir)/man2}. +@file{$(mandir)/man2} @item @dots{} @strong{Don't make the primary documentation for any GNU software be a @@ -624,6 +440,7 @@ And finally, you should set the following variable: @item srcdir The directory for the sources being compiled. The value of this variable is normally inserted by the @code{configure} shell script. +(If you are using Autconf, use @samp{srcdir = @@srcdir@@}.) @end table For example: @@ -655,3 +472,225 @@ specify the exact same values for several different GNU packages. In order for this to be useful, all the packages must be designed so that they will work sensibly when the user does so. +@node Standard Targets +@section Standard Targets for Users + +All GNU programs should have the following targets in their Makefiles: + +@table @samp +@item all +Compile the entire program. This should be the default target. This +target need not rebuild any documentation files; Info files should +normally be included in the distribution, and DVI files should be made +only when explicitly asked for. + +@item install +Compile the program and copy the executables, libraries, and so on to +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. + +If possible, write the @code{install} target rule so that it does not +modify anything in the directory where the program was built, provided +@samp{make all} has just been done. This is convenient for building the +program under one user name and installing it under another. + +The commands should create all the directories in which files are to be +installed, if they don't already exist. This includes the directories +specified as the values of the variables @code{prefix} and +@code{exec_prefix}, as well as all subdirectories that are needed. +One way to do this is by means of an @code{installdirs} target +as described below. + +Use @samp{-} before any command for installing a man page, so that +@code{make} will ignore any errors. This is in case there are systems +that don't have the Unix man page documentation system installed. + +The way to install Info files is to copy them into @file{$(infodir)} +with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run +the @code{install-info} program if it is present. @code{install-info} +is a script that edits the Info @file{dir} file to add or update the +menu entry for the given Info file; it will be part of the Texinfo package. +Here is a sample rule to install an Info file: + +@comment This example has been carefully formatted for the Make manual. +@comment Please do not reformat it without talking to roland@gnu.ai.mit.edu. +@smallexample +$(infodir)/foo.info: foo.info +# There may be a newer info file in . than in srcdir. + -if test -f foo.info; then d=.; \ + else d=$(srcdir); fi; \ + $(INSTALL_DATA) $$d/foo.info $@@; \ +# Run install-info only if it exists. +# Use `if' instead of just prepending `-' to the +# line so we notice real errors from install-info. +# We use `$(SHELL) -c' because some shells do not +# fail gracefully when there is an unknown command. + if $(SHELL) -c 'install-info --version' \ + >/dev/null 2>&1; then \ + install-info --infodir=$(infodir) $$d/foo.info; \ + else true; fi +@end smallexample + +@item uninstall +Delete all the installed files that the @samp{install} target would +create (but not the noninstalled files such as @samp{make all} would +create). + +This rule should not modify the directories where compilation is done, +only the directories where files are installed. + +@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 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 @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. + +@item mostlyclean +Like @samp{clean}, but may refrain from deleting a few files that people +normally don't want to recompile. For example, the @samp{mostlyclean} +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. + +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. + +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 +reconstruct some of the files that @samp{make maintainer-clean} deletes. +Since these files are normally included in the distribution, we don't +take care to make them easy to reconstruct. If you find you need to +unpack the full distribution again, don't blame us. + +To help make users aware of this, the commands for the special +@code{maintainer-clean} target should start with these two: + +@smallexample +@@echo "This command is intended for maintainers to use; it" +@@echo "deletes files that may require special tools to rebuild." +@end smallexample + +@item TAGS +Update a tags table for this program. +@c ADR: how? + +@item info +Generate any Info files needed. The best way to write the rules is as +follows: + +@smallexample +info: foo.info + +foo.info: foo.texi chap1.texi chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi +@end smallexample + +@noindent +You must define the variable @code{MAKEINFO} in the Makefile. It should +run the @code{makeinfo} program, which is part of the Texinfo +distribution. + +@item dvi +Generate DVI files for all Texinfo documentation. +For example: + +@smallexample +dvi: foo.dvi + +foo.dvi: foo.texi chap1.texi chap2.texi + $(TEXI2DVI) $(srcdir)/foo.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 Make to provide the command. + +@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 +name which is the name of the package it is a distribution for. This +name can include the version number. + +For example, the distribution tar file of GCC version 1.40 unpacks into +a subdirectory named @file{gcc-1.40}. + +The easiest way to do this is to create a subdirectory appropriately +named, use @code{ln} or @code{cp} to install the proper files in it, and +then @code{tar} that subdirectory. + +Compress the tar file file with @code{gzip}. For example, the actual +distribution file for GCC version 1.40 is called @file{gcc-1.40.tar.gz}. + +The @code{dist} target should explicitly depend on all non-source files +that are in the distribution, to make sure they are up to date in the +distribution. +@ifset CODESTD +@xref{Releases, , Making Releases}. +@end ifset +@ifclear CODESTD +@xref{Releases, , Making Releases, standards, GNU Coding Standards}. +@end ifclear + +@item check +Perform self-tests (if any). The user must build the program before +running the tests, but need not install the program; you should write +the self-tests so that they work when the program is built but not +installed. +@end table + +The following targets are suggested as conventional names, for programs +in which they are useful. + +@table @code +@item installcheck +Perform installation tests (if any). The user must build and install +the program before running the tests. You should not assume that +@file{$(bindir)} is in the search path. + +@item installdirs +It's useful to add a target named @samp{installdirs} to create the +directories where files are installed, and their parent directories. +There is a script called @file{mkinstalldirs} which is convenient for +this; you can find it in the Texinfo package. +@c It's in /gd/gnu/lib/mkinstalldirs. +You can use a rule like this: + +@comment This has been carefully formatted to look decent in the Make manual. +@comment Please be sure not to make it extend any further to the right.--roland +@smallexample +# Make sure all installation directories (e.g. $(bindir)) +# actually exist by making them if necessary. +installdirs: mkinstalldirs + $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ + $(libdir) $(infodir) \ + $(mandir) +@end smallexample + +This rule should not modify the directories where compilation is done. +It should do nothing but create installation directories. +@end table |