Updated from libc
[make.git] / make-stds.texi
blob435a0d2b9ce305588ce6cf29f48fd5713daa2a01
1 @comment This file is included by both standards.texi and make.texinfo.
2 @comment It was broken out of standards.texi on 1/6/93 by roland.
4 @node Makefile Conventions
5 @chapter Makefile Conventions
6 @comment standards.texi does not print an index, but make.texinfo does.
7 @cindex makefile, conventions for
8 @cindex conventions for makefiles
9 @cindex standards for makefiles
11 This chapter describes conventions for writing the Makefiles for GNU programs.
13 @menu
14 * Makefile Basics::
15 * Utilities in Makefiles::
16 * Standard Targets::
17 * Command Variables::
18 * Directory Variables::
19 @end menu
21 @node Makefile Basics
22 @section General Conventions for Makefiles
24 Every Makefile should contain this line:
26 @example
27 SHELL = /bin/sh
28 @end example
30 @noindent
31 to avoid trouble on systems where the @code{SHELL} variable might be
32 inherited from the environment.  (This is never a problem with GNU
33 @code{make}.)
35 Different @code{make} programs have incompatible suffix lists and
36 implicit rules, and this sometimes creates confusion or misbehavior.  So
37 it is a good idea to set the suffix list explicitly using only the
38 suffixes you need in the particular Makefile, like this:
40 @example
41 .SUFFIXES:
42 .SUFFIXES: .c .o
43 @end example
45 @noindent
46 The first line clears out the suffix list, the second introduces all
47 suffixes which may be subject to implicit rules in this Makefile.
49 Don't assume that @file{.} is in the path for command execution.  When
50 you need to run programs that are a part of your package during the
51 make, please make sure that it uses @file{./} if the program is built as
52 part of the make or @file{$(srcdir)/} if the file is an unchanging part
53 of the source code.  Without one of these prefixes, the current search
54 path is used.  
56 The distinction between @file{./} and @file{$(srcdir)/} is important
57 when using the @samp{--srcdir} option to @file{configure}.  A rule of
58 the form:
60 @smallexample
61 foo.1 : foo.man sedscript
62         sed -e sedscript foo.man > foo.1
63 @end smallexample
65 @noindent
66 will fail when the current directory is not the source directory,
67 because @file{foo.man} and @file{sedscript} are not in the current
68 directory.
70 When using GNU @code{make}, relying on @samp{VPATH} to find the source
71 file will work in the case where there is a single dependency file,
72 since the @file{make} automatic variable @samp{$<} will represent the
73 source file wherever it is.  (Many versions of @code{make} set @samp{$<}
74 only in implicit rules.)  A makefile target like
76 @smallexample
77 foo.o : bar.c
78         $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
79 @end smallexample
81 @noindent
82 should instead be written as
84 @smallexample
85 foo.o : bar.c
86         $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
87 @end smallexample
89 @noindent
90 in order to allow @samp{VPATH} to work correctly.  When the target has
91 multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
92 way to make the rule work well.  For example, the target above for
93 @file{foo.1} is best written as:
95 @smallexample
96 foo.1 : foo.man sedscript
97         sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
98 @end smallexample
100 @node Utilities in Makefiles
101 @section Utilities in Makefiles
103 Write the Makefile commands (and any shell scripts, such as
104 @code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
105 special features of @code{ksh} or @code{bash}.
107 The @code{configure} script and the Makefile rules for building and
108 installation should not use any utilities directly except these:
110 @example
111 cat cmp cp echo egrep expr grep
112 ln mkdir mv pwd rm rmdir sed test touch
113 @end example
115 Stick to the generally supported options for these programs.  For
116 example, don't use @samp{mkdir -p}, convenient as it may be, because
117 most systems don't support it.
119 The Makefile rules for building and installation can also use compilers
120 and related programs, but should do so via @code{make} variables so that the
121 user can substitute alternatives.  Here are some of the programs we
122 mean:
124 @example
125 ar bison cc flex install ld lex
126 make makeinfo ranlib texi2dvi yacc
127 @end example
129 Use the following @code{make} variables:
131 @example
132 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LEX)
133 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
134 @end example
136 When you use @code{ranlib}, you should make sure nothing bad happens if
137 the system does not have @code{ranlib}.  Arrange to ignore an error
138 from that command, and print a message before the command to tell the
139 user that failure of the @code{ranlib} command does not mean a problem.
141 If you use symbolic links, you should implement a fallback for systems
142 that don't have symbolic links.
144 It is ok to use other utilities in Makefile portions (or scripts)
145 intended only for particular systems where you know those utilities to
146 exist.
148 @node Standard Targets
149 @section Standard Targets for Users
151 All GNU programs should have the following targets in their Makefiles:
153 @table @samp
154 @item all
155 Compile the entire program.  This should be the default target.  This
156 target need not rebuild any documentation files; Info files should
157 normally be included in the distribution, and DVI files should be made
158 only when explicitly asked for.
160 @item install
161 Compile the program and copy the executables, libraries, and so on to
162 the file names where they should reside for actual use.  If there is a
163 simple test to verify that a program is properly installed, this target
164 should run that test.
166 If possible, write the @code{install} target rule so that it does not
167 modify anything in the directory where the program was built, provided
168 @samp{make all} has just been done.  This is convenient for building the
169 program under one user name and installing it under another.
171 The commands should create all the directories in which files are to be
172 installed, if they don't already exist.  This includes the directories
173 specified as the values of the variables @code{prefix} and
174 @code{exec_prefix}, as well as all subdirectories that are needed.
175 One way to do this is by means of an @code{installdirs} target
176 as described below.
178 Use @samp{-} before any command for installing a man page, so that
179 @code{make} will ignore any errors.  This is in case there are systems
180 that don't have the Unix man page documentation system installed.
182 The way to install Info files is to copy them into @file{$(infodir)}
183 with @code{$(INSTALL_DATA)} (@pxref{Command Variables}), and then run
184 the @code{install-info} program if it is present.  @code{install-info}
185 is a script that edits the Info @file{dir} file to add or update the
186 menu entry for the given Info file; it will be part of the Texinfo package.
187 Here is a sample rule to install an Info file:
189 @comment This example has been carefully formatted for the Make manual.
190 @comment Please do not reformat it without talking to roland@gnu.ai.mit.edu.
191 @smallexample
192 $(infodir)/foo.info: foo.info
193 # There may be a newer info file in . than in srcdir.
194         -if test -f foo.info; then d=.; \
195          else d=$(srcdir); fi; \
196         $(INSTALL_DATA) $$d/foo.info $@@; \
197 # Run install-info only if it exists.
198 # Use `if' instead of just prepending `-' to the
199 # line so we notice real errors from install-info.
200 # We use `$(SHELL) -c' because some shells do not
201 # fail gracefully when there is an unknown command.
202         if $(SHELL) -c 'install-info --version' \
203            >/dev/null 2>&1; then \
204           install-info --infodir=$(infodir) $$d/foo.info; \
205         else true; fi
206 @end smallexample
208 @item uninstall
209 Delete all the installed files that the @samp{install} target would
210 create (but not the noninstalled files such as @samp{make all} would
211 create).
213 This rule should not modify the directories where compilation is done,
214 only the directories where files are installed.
216 @comment The gratuitous blank line here is to make the table look better
217 @comment in the printed Make manual.  Please leave it in.
218 @item clean
220 Delete all files from the current directory that are normally created by
221 building the program.  Don't delete the files that record the
222 configuration.  Also preserve files that could be made by building, but
223 normally aren't because the distribution comes with them.
225 Delete @file{.dvi} files here if they are not part of the distribution.
227 @item distclean
228 Delete all files from the current directory that are created by
229 configuring or building the program.  If you have unpacked the source
230 and built the program without creating any other files, @samp{make
231 distclean} should leave only the files that were in the distribution.
233 @item mostlyclean
234 Like @samp{clean}, but may refrain from deleting a few files that people
235 normally don't want to recompile.  For example, the @samp{mostlyclean}
236 target for GCC does not delete @file{libgcc.a}, because recompiling it
237 is rarely necessary and takes a lot of time.
239 @item maintainer-clean
240 Delete almost everything from the current directory that can be
241 reconstructed with this Makefile.  This typically includes everything
242 deleted by @code{distclean}, plus more: C source files produced by
243 Bison, tags tables, Info files, and so on.
245 The reason we say ``almost everything'' is that running the command
246 @samp{make maintainer-clean} should not delete @file{configure} even if
247 it can be remade using a rule in the Makefile.  More generally,
248 @samp{make maintainer-clean} should not delete anything that needs to
249 exist in order to run @file{configure} and then begin to build the
250 program.  This is the only exception; @code{maintainer-clean} should
251 delete everything else that can be rebuilt.
253 The @samp{maintainer-clean} is intended to be used by a maintainer of
254 the package, not by ordinary users.  You may need special tools to
255 reconstruct some of the files that @samp{make maintainer-clean} deletes.
256 Since these files are normally included in the distribution, we don't
257 take care to make them easy to reconstruct.  If you find you need to
258 unpack the full distribution again, don't blame us.
260 To help make users aware of this, the commands for the special 
261 @code{maintainer-clean} target should start with these two:
263 @smallexample
264 @@echo "This command is intended for maintainers to use; it"
265 @@echo "deletes files that may require special tools to rebuild."
266 @end smallexample
268 @item TAGS
269 Update a tags table for this program.
271 @item info
272 Generate any Info files needed.  The best way to write the rules is as
273 follows:
275 @smallexample
276 info: foo.info
278 foo.info: foo.texi chap1.texi chap2.texi
279         $(MAKEINFO) $(srcdir)/foo.texi
280 @end smallexample
282 @noindent
283 You must define the variable @code{MAKEINFO} in the Makefile.  It should
284 run the @code{makeinfo} program, which is part of the Texinfo
285 distribution.
287 @item dvi
288 Generate DVI files for all TeXinfo documentation.  
289 For example:
291 @smallexample
292 dvi: foo.dvi
294 foo.dvi: foo.texi chap1.texi chap2.texi
295         $(TEXI2DVI) $(srcdir)/foo.texi
296 @end smallexample
298 @noindent
299 You must define the variable @code{TEXI2DVI} in the Makefile.  It should
300 run the program @code{texi2dvi}, which is part of the Texinfo
301 distribution.  Alternatively, write just the dependencies, and allow GNU
302 Make to provide the command.
304 @item dist
305 Create a distribution tar file for this program.  The tar file should be
306 set up so that the file names in the tar file start with a subdirectory
307 name which is the name of the package it is a distribution for.  This
308 name can include the version number.
310 For example, the distribution tar file of GCC version 1.40 unpacks into
311 a subdirectory named @file{gcc-1.40}.
313 The easiest way to do this is to create a subdirectory appropriately
314 named, use @code{ln} or @code{cp} to install the proper files in it, and
315 then @code{tar} that subdirectory.
317 The @code{dist} target should explicitly depend on all non-source files
318 that are in the distribution, to make sure they are up to date in the
319 distribution.  
320 @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
322 @item check
323 Perform self-tests (if any).  The user must build the program before
324 running the tests, but need not install the program; you should write
325 the self-tests so that they work when the program is built but not
326 installed.
327 @end table
329 The following targets are suggested as conventional names, for programs
330 in which they are useful.
332 @table @code
333 @item installcheck
334 Perform installation tests (if any).  The user must build and install
335 the program before running the tests.  You should not assume that
336 @file{$(bindir)} is in the search path.  
338 @item installdirs
339 It's useful to add a target named @samp{installdirs} to create the
340 directories where files are installed, and their parent directories.
341 There is a script called @file{mkinstalldirs} which is convenient for
342 this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs.
343 You can use a rule like this:
345 @comment This has been carefully formatted to look decent in the Make manual.
346 @comment Please be sure not to make it extend any further to the right.--roland
347 @smallexample
348 # Make sure all installation directories (e.g. $(bindir))
349 # actually exist by making them if necessary.
350 installdirs: mkinstalldirs
351         $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
352                                 $(libdir) $(infodir) \
353                                 $(mandir)
354 @end smallexample
356 This rule should not modify the directories where compilation is done.
357 It should do nothing but create installation directories.
358 @end table
360 @node Command Variables
361 @section Variables for Specifying Commands
363 Makefiles should provide variables for overriding certain commands, options,
364 and so on.
366 In particular, you should run most utility programs via variables.
367 Thus, if you use Bison, have a variable named @code{BISON} whose default
368 value is set with @samp{BISON = bison}, and refer to it with
369 @code{$(BISON)} whenever you need to use Bison.
371 File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
372 so on, need not be referred to through variables in this way, since users
373 don't need to replace them with other programs.
375 Each program-name variable should come with an options variable that is
376 used to supply options to the program.  Append @samp{FLAGS} to the
377 program-name variable name to get the options variable name---for
378 example, @code{BISONFLAGS}.  (The name @code{CFLAGS} is an exception to
379 this rule, but we keep it because it is standard.)  Use @code{CPPFLAGS}
380 in any compilation command that runs the preprocessor, and use
381 @code{LDFLAGS} in any compilation command that does linking as well as
382 in any direct use of @code{ld}.
384 If there are C compiler options that @emph{must} be used for proper
385 compilation of certain files, do not include them in @code{CFLAGS}.
386 Users expect to be able to specify @code{CFLAGS} freely themselves.
387 Instead, arrange to pass the necessary options to the C compiler
388 independently of @code{CFLAGS}, by writing them explicitly in the
389 compilation commands or by defining an implicit rule, like this:
391 @smallexample
392 CFLAGS = -g
393 ALL_CFLAGS = -I. $(CFLAGS)
394 .c.o:
395         $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
396 @end smallexample
398 Do include the @samp{-g} option in @code{CFLAGS}, because that is not
399 @emph{required} for proper compilation.  You can consider it a default
400 that is only recommended.  If the package is set up so that it is
401 compiled with GCC by default, then you might as well include @samp{-O}
402 in the default value of @code{CFLAGS} as well.
404 Put @code{CFLAGS} last in the compilation command, after other variables
405 containing compiler options, so the user can use @code{CFLAGS} to
406 override the others.
408 Every Makefile should define the variable @code{INSTALL}, which is the
409 basic command for installing a file into the system.
411 Every Makefile should also define the variables @code{INSTALL_PROGRAM}
412 and @code{INSTALL_DATA}.  (The default for each of these should be
413 @code{$(INSTALL)}.)  Then it should use those variables as the commands
414 for actual installation, for executables and nonexecutables
415 respectively.  Use these variables as follows:
417 @example
418 $(INSTALL_PROGRAM) foo $(bindir)/foo
419 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
420 @end example
422 @noindent
423 Always use a file name, not a directory name, as the second argument of
424 the installation commands.  Use a separate command for each file to be
425 installed.
427 @node Directory Variables
428 @section Variables for Installation Directories
430 Installation directories should always be named by variables, so it is
431 easy to install in a nonstandard place.  The standard names for these
432 variables are described below.  They are based on a standard filesystem
433 layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
434 other modern operating systems.
436 These two variables set the root for the installation.  All the other
437 installation directories should be subdirectories of one of these two,
438 and nothing should be directly installed into these two directories.
440 @table @samp
441 @item prefix
442 A prefix used in constructing the default values of the variables listed
443 below.  The default value of @code{prefix} should be @file{/usr/local}.
444 When building the complete GNU system, the prefix will be empty and
445 @file{/usr} will be a symbolic link to @file{/}.
447 @item exec_prefix
448 A prefix used in constructing the default values of some of the
449 variables listed below.  The default value of @code{exec_prefix} should
450 be @code{$(prefix)}.
452 Generally, @code{$(exec_prefix)} is used for directories that contain
453 machine-specific files (such as executables and subroutine libraries),
454 while @code{$(prefix)} is used directly for other directories.
455 @end table
457 Executable programs are installed in one of the following directories.
459 @table @samp
460 @item bindir
461 The directory for installing executable programs that users can run.
462 This should normally be @file{/usr/local/bin}, but write it as
463 @file{$(exec_prefix)/bin}.
465 @item sbindir
466 The directory for installing executable programs that can be run from
467 the shell, but are only generally useful to system administrators.  This
468 should normally be @file{/usr/local/sbin}, but write it as
469 @file{$(exec_prefix)/sbin}.
471 @item libexecdir
472 @comment This paragraph adjusted to avoid overfull hbox --roland 5jul94
473 The directory for installing executable programs to be run by other
474 programs rather than by users.  This directory should normally be
475 @file{/usr/local/libexec}, but write it as @file{$(exec_prefix)/libexec}.
476 @end table
478 Data files used by the program during its execution are divided into
479 categories in two ways.
481 @itemize @bullet
482 @item
483 Some files are normally modified by programs; others are never normally
484 modified (though users may edit some of these).
486 @item
487 Some files are architecture-independent and can be shared by all
488 machines at a site; some are architecture-dependent and can be shared
489 only by machines of the same kind and operating system; others may never
490 be shared between two machines.
491 @end itemize
493 This makes for six different possibilities.  However, we want to
494 discourage the use of architecture-dependent files, aside from of object
495 files and libraries.  It is much cleaner to make other data files
496 architecture-independent, and it is generally not hard.
498 Therefore, here are the variables makefiles should use to specify
499 directories:
501 @table @samp
502 @item datadir
503 The directory for installing read-only architecture independent data
504 files.  This should normally be @file{/usr/local/share}, but write it as
505 @file{$(prefix)/share}.  As a special exception, see @file{$(infodir)}
506 and @file{$(includedir)} below.
508 @item sysconfdir
509 The directory for installing read-only data files that pertain to a
510 single machine--that is to say, files for configuring a host.  Mailer
511 and network configuration files, @file{/etc/passwd}, and so forth belong
512 here.  All the files in this directory should be ordinary ASCII text
513 files.  This directory should normally be @file{/usr/local/etc}, but
514 write it as @file{$(prefix)/etc}.
516 @c rewritten to avoid overfull hbox --tower
517 Do not install executables
518 @c here
519 in this directory (they probably
520 belong in @file{$(libexecdir)} or @file{$(sbindir))}.  Also do not
521 install files that are modified in the normal course of their use
522 (programs whose purpose is to change the configuration of the system
523 excluded).  Those probably belong in @file{$(localstatedir)}.
525 @item sharedstatedir
526 The directory for installing architecture-independent data files which
527 the programs modify while they run.  This should normally be
528 @file{/usr/local/com}, but write it as @file{$(prefix)/com}.
530 @item localstatedir
531 The directory for installing data files which the programs modify while
532 they run, and that pertain to one specific machine.  Users should never
533 need to modify files in this directory to configure the package's
534 operation; put such configuration information in separate files that go
535 in @file{datadir} or @file{$(sysconfdir)}.  @file{$(localstatedir)}
536 should normally be @file{/usr/local/var}, but write it as
537 @file{$(prefix)/var}.
539 @item libdir
540 The directory for object files and libraries of object code.  Do not
541 install executables here, they probably belong in @file{$(libexecdir)}
542 instead.  The value of @code{libdir} should normally be
543 @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
545 @item infodir
546 The directory for installing the Info files for this package.  By
547 default, it should be @file{/usr/local/info}, but it should be written
548 as @file{$(prefix)/info}.
550 @item includedir
551 @c rewritten to avoid overfull hbox --roland
552 The directory for installing header files to be included by user
553 programs with the C @samp{#include} preprocessor directive.  This
554 should normally be @file{/usr/local/include}, but write it as
555 @file{$(prefix)/include}.
557 Most compilers other than GCC do not look for header files in
558 @file{/usr/local/include}.  So installing the header files this way is
559 only useful with GCC.  Sometimes this is not a problem because some
560 libraries are only really intended to work with GCC.  But some libraries
561 are intended to work with other compilers.  They should install their
562 header files in two places, one specified by @code{includedir} and one
563 specified by @code{oldincludedir}.
565 @item oldincludedir
566 The directory for installing @samp{#include} header files for use with
567 compilers other than GCC.  This should normally be @file{/usr/include}.
569 The Makefile commands should check whether the value of
570 @code{oldincludedir} is empty.  If it is, they should not try to use
571 it; they should cancel the second installation of the header files.
573 A package should not replace an existing header in this directory unless
574 the header came from the same package.  Thus, if your Foo package
575 provides a header file @file{foo.h}, then it should install the header
576 file in the @code{oldincludedir} directory if either (1) there is no
577 @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
578 package.
580 To tell whether @file{foo.h} came from the Foo package, put a magic
581 string in the file---part of a comment---and grep for that string.
582 @end table
584 Unix-style man pages are installed in one of the following:
586 @table @samp
587 @item mandir
588 The top-level directory for installing the man pages (if any) for this
589 package.  It will normally be @file{/usr/local/man}, but you should
590 write it as @file{$(prefix)/man}.
592 @item man1dir
593 The directory for installing section 1 man pages.  Write it as
594 @file{$(mandir)/man1}.
595 @item man2dir
596 The directory for installing section 2 man pages.  Write it as
597 @file{$(mandir)/man2}.
598 @item @dots{}
600 @strong{Don't make the primary documentation for any GNU software be a
601 man page.  Write a manual in Texinfo instead.  Man pages are just for
602 the sake of people running GNU software on Unix, which is a secondary
603 application only.}
605 @item manext
606 The file name extension for the installed man page.  This should contain
607 a period followed by the appropriate digit; it should normally be @samp{.1}.
609 @item man1ext
610 The file name extension for installed section 1 man pages.
611 @item man2ext
612 The file name extension for installed section 2 man pages.
613 @item @dots{}
614 Use these names instead of @samp{manext} if the package needs to install man
615 pages in more than one section of the manual.
616 @end table
618 And finally, you should set the following variable:
620 @table @samp
621 @item srcdir
622 The directory for the sources being compiled.  The value of this
623 variable is normally inserted by the @code{configure} shell script.
624 @end table
626 For example:
628 @smallexample
629 @c I have changed some of the comments here slightly to fix an overfull
630 @c hbox, so the make manual can format correctly. --roland
631 # Common prefix for installation directories.
632 # NOTE: This directory must exist when you start the install.
633 prefix = /usr/local
634 exec_prefix = $(prefix)
635 # Where to put the executable for the command `gcc'.
636 bindir = $(exec_prefix)/bin
637 # Where to put the directories used by the compiler.
638 libexecdir = $(exec_prefix)/libexec
639 # Where to put the Info files.
640 infodir = $(prefix)/info
641 @end smallexample
643 If your program installs a large number of files into one of the
644 standard user-specified directories, it might be useful to group them
645 into a subdirectory particular to that program.  If you do this, you
646 should write the @code{install} rule to create these subdirectories.
648 Do not expect the user to include the subdirectory name in the value of
649 any of the variables listed above.  The idea of having a uniform set of
650 variable names for installation directories is to enable the user to
651 specify the exact same values for several different GNU packages.  In
652 order for this to be useful, all the packages must be designed so that
653 they will work sensibly when the user does so.