diff options
| -rw-r--r-- | make-stds.texi | 449 |
1 files changed, 449 insertions, 0 deletions
diff --git a/make-stds.texi b/make-stds.texi new file mode 100644 index 0000000..2c6b808 --- /dev/null +++ b/make-stds.texi @@ -0,0 +1,449 @@ +@comment This file is included by both standards.texi and make.texinfo. +@comment It was broken out of standards.texi on 1/6/93 by roland. + +@node Makefile Conventions +@chapter Makefile Conventions +@comment standards.texi does not print an index, but make.texinfo does. +@cindex makefile, conventions for +@cindex conventions for makefiles +@cindex standards for makefiles + +This chapter describes conventions for writing the Makefiles for GNU programs. + +@menu +* Makefile Basics:: +* Utilities in Makefiles:: +* Standard Targets:: +* Command Variables:: +* Directory Variables:: +@end menu + +@node Makefile Basics +@section General Conventions for Makefiles + +Every Makefile should contain this line: + +@example +SHELL = /bin/sh +@end example + +@noindent +to avoid trouble on systems where the @code{SHELL} variable might be +inherited from the environment. (This is never a problem with GNU +@code{make}.) + +Don't assume that @file{.} is in the path for command execution. When +you need to run programs that are a part of your package during the +make, please make sure that it uses @file{./} if the program is built as +part of the make or @file{$(srcdir)/} if the file is an unchanging part +of the source code. Without one of these prefixes, the current search +path is used. + +The distinction between @file{./} and @file{$(srcdir)/} is important +when using the @samp{--srcdir} option to @file{configure}. A rule of +the form: + +@example +foo.1 : foo.man sedscript + sed -e sedscript foo.man > foo.1 +@end example + +@noindent +will fail when the current directory is not the source directory, +because @file{foo.man} and @file{sedscript} are not in the current +directory. + +Relying on @samp{VPATH} to find the source file will work in the case +where there is a single dependency file, since the @file{make} automatic +variable @samp{$<} will represent the source file wherever it is. A +makefile target like + +@example +foo.o : bar.c + $(CC) $(CFLAGS) -I. -I$(srcdir) -c bar.c -o foo.o +@end example + +@noindent +should instead be written as + +@example +foo.o : bar.c + $(CC) $(CFLAGS) $< -o $@@ +@end example + +@noindent +in order to allow @samp{VPATH} to work correctly. When the target has +multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest +way to make the rule work well. For example, the target above for +@file{foo.1} is best written as: + +@example +foo.1 : foo.man sedscript + sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1 +@end example + +@node Utilities in Makefiles +@section Utilities in Makefiles + +Write the Makefile commands (and any shell scripts, such as +@code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any +special features of @code{ksh} or @code{bash}. + +The @code{configure} script and the Makefile rules for building and +installation should not use any utilities directly except these: + +@example +cat cmp cp echo egrep expr grep +ln mkdir mv pwd rm rmdir sed test touch +@end example + +Stick to the generally supported options for these programs. For +example, don't use @samp{mkdir -p}, convenient as it may be, because +most systems don't support it. + +The Makefile rules for building and installation can also use compilers +and related programs, but should do so via @code{make} variables so that the +user can substitute alternatives. Here are some of the programs we +mean: + +@example +ar bison cc flex install ld lex make ranlib yacc +@end example + +When you use @code{ranlib}, you should test whether it exists, and run +it only if it exists, so that the distribution will work on systems that +don't have @code{ranlib}. + +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 +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 then run that +test. + +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. + +In the future, when we have a standard way of installing info files, +@samp{install} targets will be the proper place to do so. + +@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). + +@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 realclean +Delete everything from the current directory that can be reconstructed +with this Makefile. This typically includes everything deleted by +distclean, plus more: C source files produced by Bison, tags tables, +info files, and so on. + +One exception, however: @samp{make realclean} should not delete +@file{configure} even if @file{configure} can be remade using a rule in +the Makefile. More generally, @samp{make realclean} should not delete +anything that needs to exist in order to run @file{configure} +and then begin to build the program. + +@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: + +@example +info: foo.info + +foo.info: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi + $(MAKEINFO) $(srcdir)/foo.texi +@end example + +@noindent +You must define the variable @code{MAKEINFO} in the Makefile. +It should run the Makeinfo program, which is part of the Texinfo2 distribution. + +@item dvi +Generate DVI files for all TeXinfo documentation. +For example: + +@example +dvi: foo.dvi + +foo.dvi: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi + $(TEXI2DVI) $(srcdir)/foo.texi +@end example + +@noindent +You must define the variable @code{TEXI2DVI} in the Makefile. It should +run the program @code{texi2dvi}, which is part of the Texinfo2 +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 + +@node Command Variables +@section Variables for Specifying Commands + +Makefiles should provide variables for overriding certain commands, options, +and so on. + +In particular, you should run most utility programs via variables. +Thus, if you use Bison, have a variable named @code{BISON} whose default +value is set with @samp{BISON = bison}, and refer to it with +@code{$(BISON)} whenever you need to use Bison. + +File management utilities such as @code{ln}, @code{rm}, @code{mv}, and +so on, need not be referred to through variables in this way, since users +don't need to replace them with other programs. + +Each program-name variable should come with an options variable that is +used to supply options to the program. Append @samp{FLAGS} to the +program-name variable name to get the options variable name---for +example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to +this rule, but we keep it because it is standard.) Use @code{CPPFLAGS} +in any compilation command that runs the preprocessor, and use +@code{LDFLAGS} in any compilation command that does linking as well as +in any direct use of @code{ld}. + +If there are C compiler options that @emph{must} be used for proper +compilation of certain files, do not include them in @code{CFLAGS}. +Users expect to be able to specify @code{CFLAGS} freely themselves. +Instead, arrange to pass the necessary options to the C compiler +independently of @code{CFLAGS}, by writing them explicitly in the +compilation commands or by defining an implicit rule, like this: + +@example +CFLAGS = -g +ALL_CFLAGS = $(CFLAGS) -I. +.c.o: + $(CC) -c $(ALL_CFLAGS) $(CPPFLAGS) $< +@end example + +Do include the @samp{-g} option in @code{CFLAGS}, because that is not +@emph{required} for proper compilation. You can consider it a default +that is only recommended. If the package is set up so that it is +compiled with GCC by default, then you might as well include @samp{-O} +in the default value of @code{CFLAGS} as well. + +Every Makefile should define the variable @code{INSTALL}, which is the +basic command for installing a file into the system. + +Every Makefile should also define variables @code{INSTALL_PROGRAM} and +@code{INSTALL_DATA}. (The default for each of these should be +@code{$(INSTALL)}.) Then it should use those variables as the commands +for actual installation, for executables and nonexecutables +respectively. Use these variables as follows: + +@example +$(INSTALL_PROGRAM) foo $(bindir)/foo +$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a +@end example + +@noindent +Always use a file name, not a directory name, as the second argument of +the installation commands. Use a separate command for each file to be +installed. + +@node Directory Variables +@section Variables for Installation Directories + +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: + +@table @samp +@item prefix +A prefix used in constructing the default values of the variables listed +below. The default value of @code{prefix} should be @file{/usr/local} +(at least for now). + +@item exec_prefix +A prefix used in constructing the default values of the some of the +variables listed below. The default value of @code{exec_prefix} should +be @code{$(prefix)}. + +Generally, @code{$(exec_prefix)} is used for directories that contain +machine-specific files (such as executables and subroutine libraries), +while @code{$(prefix)} is used directly for other directories. + +@item bindir +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}. + +@item libdir +The directory for installing executable files to be run by the program +rather than by users. Object files and libraries of object code should +also go in this directory. The idea is that this directory is used for +files that pertain to a specific machine architecture, but need not be +in the path for commands. The value of @code{libdir} should normally be +@file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}. + +@item datadir +The directory for installing read-only data files which the programs +refer to while they run. This directory is used for files which are +independent of the type of machine being used. This should normally be +@file{/usr/local/lib}, but write it as @file{$(prefix)/lib}. + +@item statedir +The directory for installing data files which the programs modify while +they run. These files should be independent of the type of machine +being used, and it should be possible to share them among machines at a +network installation. This should normally be @file{/usr/local/lib}, +but write it as @file{$(prefix)/lib}. + +@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 +@file{$(prefix)/include}. + +Most compilers other than GCC do not look for header files in +@file{/usr/local/include}. So installing the header files this way is +only useful with GCC. Sometimes this is not a problem because some +libraries are only really intended to work with GCC. But some libraries +are intended to work with other compilers. They should install their +header files in two places, one specified by @code{includedir} and one +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}. + +The Makefile commands should check whether the value of +@code{oldincludedir} is empty. If it is, they should not try to use +it; they should cancel the second installation of the header files. + +A package should not replace an existing header in this directory unless +the header came from the same package. Thus, if your Foo package +provides a header file @file{foo.h}, then it should install the header +file in the @code{oldincludedir} directory if either (1) there is no +@file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo +package. + +The way to tell whether @file{foo.h} came from the Foo package is to put +a magic string in the file---part of a comment---and grep for that +string. + +@item mandir +The directory for installing the man pages (if any) for this package. +It should include the suffix for the proper section of the +manual---usually @samp{1} for a utility. + +@item man1dir +The directory for installing section 1 man pages. +@item man2dir +The directory for installing section 2 man pages. +@item @dots{} +Use these names instead of @samp{mandir} if the package needs to install man +pages in more than one section of the manual. + +@strong{Don't make the primary documentation for any GNU software be a +man page. Write a manual in Texinfo instead. Man pages are just for +the sake of people running GNU software on Unix, which is a secondary +application only.} + +@item manext +The file name extension for the installed man page. This should contain +a period followed by the appropriate digit. + +@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}. + +@item srcdir +The directory for the sources being compiled. The value of this +variable is normally inserted by the @code{configure} shell script. +@end table + +For example: + +@example +# Common prefix for installation directories. +# NOTE: This directory must exist when you start the install. +prefix = /usr/local +exec_prefix = $(prefix) +# Directory in which to put the executable for the command `gcc'. +bindir = $(exec_prefix)/bin +# Directory in which to put the directories used by the compiler. +libdir = $(exec_prefix)/lib +# Directory in which to put the Info files. +infodir = $(prefix)/info +@end example + +If your program installs a large number of files into one of the +standard user-specified directories, it might be useful to group them +into a subdirectory particular to that program. If you do this, you +should write the @code{install} rule to create these subdirectories. + +Do not expect the user to include the subdirectory name in the value of +any of the variables listed above. The idea of having a uniform set of +variable names for installation directories is to enable the user to +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. + |