| @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}.) |
| |
| Different @code{make} programs have incompatible suffix lists and |
| implicit rules, and this sometimes creates confusion or misbehavior. So |
| it is a good idea to set the suffix list explicitly using only the |
| suffixes you need in the particular Makefile, like this: |
| |
| @example |
| .SUFFIXES: |
| .SUFFIXES: .c .o |
| @end example |
| |
| @noindent |
| The first line clears out the suffix list, the second introduces all |
| suffixes which may be subject to implicit rules in this Makefile. |
| |
| 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: |
| |
| @smallexample |
| foo.1 : foo.man sedscript |
| sed -e sedscript foo.man > foo.1 |
| @end smallexample |
| |
| @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. |
| |
| 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 @file{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 |
| |
| @smallexample |
| foo.o : bar.c |
| $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o |
| @end smallexample |
| |
| @noindent |
| should instead be written as |
| |
| @smallexample |
| foo.o : bar.c |
| $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@ |
| @end smallexample |
| |
| @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: |
| |
| @smallexample |
| foo.1 : foo.man sedscript |
| sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@ |
| @end smallexample |
| |
| @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 makeinfo ranlib texi2dvi yacc |
| @end example |
| |
| Use the following @code{make} variables: |
| |
| @example |
| $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX) |
| $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC) |
| @end example |
| |
| 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. |
| |
| 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, 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 @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} 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 |
| @code{maintainer-clean} should start with these two: |
| |
| @example |
| @@echo "This command is intended for maintainers to use;" |
| @@echo "it deletes files that may require special tools to rebuild." |
| @end example |
| |
| @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 |
| |
| 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: |
| |
| @smallexample |
| CFLAGS = -g |
| ALL_CFLAGS = -I. $(CFLAGS) |
| .c.o: |
| $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $< |
| @end smallexample |
| |
| 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. |
| |
| Put @code{CFLAGS} last in the compilation command, after other variables |
| containing compiler options, so the user can use @code{CFLAGS} to |
| override the others. |
| |
| 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 the 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 described below. They are based on a standard filesystem |
| layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and |
| other modern operating systems. |
| |
| These two variables set the root for the installation. All the other |
| installation directories should be subdirectories of one of these two, |
| and nothing should be directly installed into these two directories. |
| |
| @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} |
| When building the complete GNU system, the prefix will be empty and |
| @file{/usr} will be a symbolic link to @file{/}. |
| |
| @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)}. |
| |
| 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. |
| @end table |
| |
| Executable programs are installed in one of the following directories. |
| |
| @table @samp |
| @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 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}. |
| |
| @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}. |
| @end table |
| |
| Data files used by the program during its execution are divided into |
| categories in two ways. |
| |
| @itemize @bullet |
| @item |
| Some files are normally modified by programs; others are never normally |
| modified (though users may edit some of these). |
| |
| @item |
| Some files are architecture-independent and can be shared by all |
| machines at a site; some are architecture-dependent and can be shared |
| only by machines of the same kind and operating system; others may never |
| 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 |
| 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 |
| 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)} |
| and @file{$(includedir)} below. |
| |
| @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 |
| 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}. |
| |
| @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 |
| 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)}. |
| |
| @item sharedstatedir |
| 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}. |
| |
| @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)} |
| should normally be @file{/usr/local/var}, but write it as |
| @file{$(prefix)/var}. |
| |
| @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}. |
| |
| @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 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. |
| |
| 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. |
| @end table |
| |
| Unix-style man pages are installed in one of the following: |
| |
| @table @samp |
| @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. It will normally be |
| @file{/usr/local/man/man1}, but you should write it as |
| @file{$(prefix)/man/man1}. |
| |
| @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; it should normally be @samp{.1}. |
| |
| @item man1ext |
| The file name extension for installed section 1 man pages. |
| @item man2ext |
| The file name extension for installed section 2 man pages. |
| @item @dots{} |
| Use these names instead of @samp{manext} if the package needs to install man |
| pages in more than one section of the manual. |
| @end table |
| |
| And finally, you should set the following variable: |
| |
| @table @samp |
| @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: |
| |
| @smallexample |
| @c I have changed some of the comments here slightly to fix an overfull |
| @c hbox, so the make manual can format correctly. --roland |
| # Common prefix for installation directories. |
| # NOTE: This directory must exist when you start the install. |
| prefix = /usr/local |
| exec_prefix = $(prefix) |
| # Where to put the executable for the command `gcc'. |
| bindir = $(exec_prefix)/bin |
| # Where to put the directories used by the compiler. |
| libexecdir = $(exec_prefix)/libexec |
| # Where to put the Info files. |
| infodir = $(prefix)/info |
| @end smallexample |
| |
| 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. |
| |