![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to make-stds.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / libg++ / etc|
Return to make-stds.texi CVS log | Up to [Apple XNU] / GNUtools / libg++ / etc |
1.1 root 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.
3:
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
10:
11: This chapter describes conventions for writing the Makefiles for GNU programs.
12:
13: @menu
14: * Makefile Basics::
15: * Utilities in Makefiles::
16: * Standard Targets::
17: * Command Variables::
18: * Directory Variables::
19: @end menu
20:
21: @node Makefile Basics
22: @section General Conventions for Makefiles
23:
24: Every Makefile should contain this line:
25:
26: @example
27: SHELL = /bin/sh
28: @end example
29:
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}.)
34:
35: Don't assume that @file{.} is in the path for command execution. When
36: you need to run programs that are a part of your package during the
37: make, please make sure that it uses @file{./} if the program is built as
38: part of the make or @file{$(srcdir)/} if the file is an unchanging part
39: of the source code. Without one of these prefixes, the current search
40: path is used.
41:
42: The distinction between @file{./} and @file{$(srcdir)/} is important
43: when using the @samp{--srcdir} option to @file{configure}. A rule of
44: the form:
45:
46: @example
47: foo.1 : foo.man sedscript
48: sed -e sedscript foo.man > foo.1
49: @end example
50:
51: @noindent
52: will fail when the current directory is not the source directory,
53: because @file{foo.man} and @file{sedscript} are not in the current
54: directory.
55:
56: When using GNU @code{make}, relying on @samp{VPATH} to find the source
57: file will work in the case where there is a single dependency file,
58: since the @file{make} automatic variable @samp{$<} will represent the
59: source file wherever it is. (Many versions of @code{make} set @samp{$<}
60: only in implicit rules.) A makefile target like
61:
62: @example
63: foo.o : bar.c
64: $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
65: @end example
66:
67: @noindent
68: should instead be written as
69:
70: @example
71: foo.o : bar.c
72: $(CC) $(CFLAGS) $< -o $@@
73: @end example
74:
75: @noindent
76: in order to allow @samp{VPATH} to work correctly. When the target has
77: multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
78: way to make the rule work well. For example, the target above for
79: @file{foo.1} is best written as:
80:
81: @example
82: foo.1 : foo.man sedscript
83: sed -s $(srcdir)/sedscript $(srcdir)/foo.man > foo.1
84: @end example
85:
86: @node Utilities in Makefiles
87: @section Utilities in Makefiles
88:
89: Write the Makefile commands (and any shell scripts, such as
90: @code{configure}) to run in @code{sh}, not in @code{csh}. Don't use any
91: special features of @code{ksh} or @code{bash}.
92:
93: The @code{configure} script and the Makefile rules for building and
94: installation should not use any utilities directly except these:
95:
96: @example
97: cat cmp cp echo egrep expr grep
98: ln mkdir mv pwd rm rmdir sed test touch
99: @end example
100:
101: Stick to the generally supported options for these programs. For
102: example, don't use @samp{mkdir -p}, convenient as it may be, because
103: most systems don't support it.
104:
105: The Makefile rules for building and installation can also use compilers
106: and related programs, but should do so via @code{make} variables so that the
107: user can substitute alternatives. Here are some of the programs we
108: mean:
109:
110: @example
111: ar bison cc flex install ld lex
112: make makeinfo ranlib texi2dvi yacc
113: @end example
114:
115: When you use @code{ranlib}, you should test whether it exists, and run
116: it only if it exists, so that the distribution will work on systems that
117: don't have @code{ranlib}.
118:
119: If you use symbolic links, you should implement a fallback for systems
120: that don't have symbolic links.
121:
122: It is ok to use other utilities in Makefile portions (or scripts)
123: intended only for particular systems where you know those utilities to
124: exist.
125:
126: @node Standard Targets
127: @section Standard Targets for Users
128:
129: All GNU programs should have the following targets in their Makefiles:
130:
131: @table @samp
132: @item all
133: Compile the entire program. This should be the default target. This
134: target need not rebuild any documentation files; info files should
135: normally be included in the distribution, and DVI files should be made
136: only when explicitly asked for.
137:
138: @item install
139: Compile the program and copy the executables, libraries, and so on to
140: the file names where they should reside for actual use. If there is a
141: simple test to verify that a program is properly installed then run that
142: test.
143:
144: Use @samp{-} before any command for installing a man page, so that
145: @code{make} will ignore any errors. This is in case there are systems
146: that don't have the Unix man page documentation system installed.
147:
148: In the future, when we have a standard way of installing info files,
149: @samp{install} targets will be the proper place to do so.
150:
151: @item uninstall
152: Delete all the installed files that the @samp{install} target would
153: create (but not the noninstalled files such as @samp{make all} would
154: create).
155:
156: @item clean
157: Delete all files from the current directory that are normally created by
158: building the program. Don't delete the files that record the
159: configuration. Also preserve files that could be made by building, but
160: normally aren't because the distribution comes with them.
161:
162: Delete @file{.dvi} files here if they are not part of the distribution.
163:
164: @item distclean
165: Delete all files from the current directory that are created by
166: configuring or building the program. If you have unpacked the source
167: and built the program without creating any other files, @samp{make
168: distclean} should leave only the files that were in the distribution.
169:
170: @item mostlyclean
171: Like @samp{clean}, but may refrain from deleting a few files that people
172: normally don't want to recompile. For example, the @samp{mostlyclean}
173: target for GCC does not delete @file{libgcc.a}, because recompiling it
174: is rarely necessary and takes a lot of time.
175:
176: @item realclean
177: Delete everything from the current directory that can be reconstructed
178: with this Makefile. This typically includes everything deleted by
179: distclean, plus more: C source files produced by Bison, tags tables,
180: info files, and so on.
181:
182: One exception, however: @samp{make realclean} should not delete
183: @file{configure} even if @file{configure} can be remade using a rule in
184: the Makefile. More generally, @samp{make realclean} should not delete
185: anything that needs to exist in order to run @file{configure}
186: and then begin to build the program.
187:
188: @item TAGS
189: Update a tags table for this program.
190:
191: @item info
192: Generate any info files needed. The best way to write the rules is as
193: follows:
194:
195: @example
196: info: foo.info
197:
198: foo.info: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
199: $(MAKEINFO) $(srcdir)/foo.texi
200: @end example
201:
202: @noindent
203: You must define the variable @code{MAKEINFO} in the Makefile.
204: It should run the Makeinfo program, which is part of the Texinfo2 distribution.
205:
206: @item dvi
207: Generate DVI files for all TeXinfo documentation.
208: For example:
209:
210: @example
211: dvi: foo.dvi
212:
213: foo.dvi: $(srcdir)/foo.texi $(srcdir)/chap1.texi $(srcdir)/chap2.texi
214: $(TEXI2DVI) $(srcdir)/foo.texi
215: @end example
216:
217: @noindent
218: You must define the variable @code{TEXI2DVI} in the Makefile. It should
219: run the program @code{texi2dvi}, which is part of the Texinfo2
220: distribution. Alternatively, write just the dependencies, and allow GNU
221: Make to provide the command.
222:
223: @item dist
224: Create a distribution tar file for this program. The tar file should be
225: set up so that the file names in the tar file start with a subdirectory
226: name which is the name of the package it is a distribution for. This
227: name can include the version number.
228:
229: For example, the distribution tar file of GCC version 1.40 unpacks into
230: a subdirectory named @file{gcc-1.40}.
231:
232: The easiest way to do this is to create a subdirectory appropriately
233: named, use @code{ln} or @code{cp} to install the proper files in it, and
234: then @code{tar} that subdirectory.
235:
236: The @code{dist} target should explicitly depend on all non-source files
237: that are in the distribution, to make sure they are up to date in the
238: distribution.
239: @xref{Releases, , Making Releases, standards, GNU Coding Standards}.
240:
241: @item check
242: Perform self-tests (if any). The user must build the program before
243: running the tests, but need not install the program; you should write
244: the self-tests so that they work when the program is built but not
245: installed.
246: @end table
247:
248: The following targets are suggested as conventional names, for programs
249: in which they are useful.
250:
251: @table @code
252: @item installcheck
253: Perform installation tests (if any). The user must build and install
254: the program before running the tests. You should not assume that
255: @file{$(bindir)} is in the search path.
256:
257: @item installdirs
258: It's useful to add a target named @samp{installdirs} to create the
259: directories where files are installed, and their parent directories.
260: There is a script called @file{mkinstalldirs} which is convenient for
261: this; find it in the Texinfo package.@c It's in /gd/gnu/lib/mkinstalldirs.
262: You can use a rule like this:
263:
264: @example
265: # Make sure all installation directories, e.g. $(bindir) actually exist by
266: # making them if necessary.
267: installdirs: mkinstalldirs
268: $(srcdir)/mkinstalldirs $(bindir) $(datadir) $(libdir) \
269: $(infodir) $(mandir)
270: @end example
271: @end table
272:
273: @node Command Variables
274: @section Variables for Specifying Commands
275:
276: Makefiles should provide variables for overriding certain commands, options,
277: and so on.
278:
279: In particular, you should run most utility programs via variables.
280: Thus, if you use Bison, have a variable named @code{BISON} whose default
281: value is set with @samp{BISON = bison}, and refer to it with
282: @code{$(BISON)} whenever you need to use Bison.
283:
284: File management utilities such as @code{ln}, @code{rm}, @code{mv}, and
285: so on, need not be referred to through variables in this way, since users
286: don't need to replace them with other programs.
287:
288: Each program-name variable should come with an options variable that is
289: used to supply options to the program. Append @samp{FLAGS} to the
290: program-name variable name to get the options variable name---for
291: example, @code{BISONFLAGS}. (The name @code{CFLAGS} is an exception to
292: this rule, but we keep it because it is standard.) Use @code{CPPFLAGS}
293: in any compilation command that runs the preprocessor, and use
294: @code{LDFLAGS} in any compilation command that does linking as well as
295: in any direct use of @code{ld}.
296:
297: If there are C compiler options that @emph{must} be used for proper
298: compilation of certain files, do not include them in @code{CFLAGS}.
299: Users expect to be able to specify @code{CFLAGS} freely themselves.
300: Instead, arrange to pass the necessary options to the C compiler
301: independently of @code{CFLAGS}, by writing them explicitly in the
302: compilation commands or by defining an implicit rule, like this:
303:
304: @example
305: CFLAGS = -g
306: ALL_CFLAGS = -I. $(CFLAGS)
307: .c.o:
308: $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
309: @end example
310:
311: Do include the @samp{-g} option in @code{CFLAGS}, because that is not
312: @emph{required} for proper compilation. You can consider it a default
313: that is only recommended. If the package is set up so that it is
314: compiled with GCC by default, then you might as well include @samp{-O}
315: in the default value of @code{CFLAGS} as well.
316:
317: Put @code{CFLAGS} last in the compilation command, after other variables
318: containing compiler options, so the user can use @code{CFLAGS} to
319: override the others.
320:
321: Every Makefile should define the variable @code{INSTALL}, which is the
322: basic command for installing a file into the system.
323:
324: Every Makefile should also define variables @code{INSTALL_PROGRAM} and
325: @code{INSTALL_DATA}. (The default for each of these should be
326: @code{$(INSTALL)}.) Then it should use those variables as the commands
327: for actual installation, for executables and nonexecutables
328: respectively. Use these variables as follows:
329:
330: @example
331: $(INSTALL_PROGRAM) foo $(bindir)/foo
332: $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
333: @end example
334:
335: @noindent
336: Always use a file name, not a directory name, as the second argument of
337: the installation commands. Use a separate command for each file to be
338: installed.
339:
340: @node Directory Variables
341: @section Variables for Installation Directories
342:
343: Installation directories should always be named by variables, so it is
344: easy to install in a nonstandard place. The standard names for these
345: variables are:
346:
347: @table @samp
348: @item prefix
349: A prefix used in constructing the default values of the variables listed
350: below. The default value of @code{prefix} should be @file{/usr/local}
351: (at least for now).
352:
353: @item exec_prefix
354: A prefix used in constructing the default values of the some of the
355: variables listed below. The default value of @code{exec_prefix} should
356: be @code{$(prefix)}.
357:
358: Generally, @code{$(exec_prefix)} is used for directories that contain
359: machine-specific files (such as executables and subroutine libraries),
360: while @code{$(prefix)} is used directly for other directories.
361:
362: @item bindir
363: The directory for installing executable programs that users can run.
364: This should normally be @file{/usr/local/bin}, but write it as
365: @file{$(exec_prefix)/bin}.
366:
367: @item libdir
368: The directory for installing executable files to be run by the program
369: rather than by users. Object files and libraries of object code should
370: also go in this directory. The idea is that this directory is used for
371: files that pertain to a specific machine architecture, but need not be
372: in the path for commands. The value of @code{libdir} should normally be
373: @file{/usr/local/lib}, but write it as @file{$(exec_prefix)/lib}.
374:
375: @item datadir
376: The directory for installing read-only data files which the programs
377: refer to while they run. This directory is used for files which are
378: independent of the type of machine being used. This should normally be
379: @file{/usr/local/lib}, but write it as @file{$(prefix)/lib}.
380:
381: @item statedir
382: The directory for installing data files which the programs modify while
383: they run. These files should be independent of the type of machine
384: being used, and it should be possible to share them among machines at a
385: network installation. This should normally be @file{/usr/local/lib},
386: but write it as @file{$(prefix)/lib}.
387:
388: @item includedir
389: @c rewritten to avoid overfull hbox --roland
390: The directory for installing header files to be included by user
391: programs with the C @samp{#include} preprocessor directive. This
392: should normally be @file{/usr/local/include}, but write it as
393: @file{$(prefix)/include}.
394:
395: Most compilers other than GCC do not look for header files in
396: @file{/usr/local/include}. So installing the header files this way is
397: only useful with GCC. Sometimes this is not a problem because some
398: libraries are only really intended to work with GCC. But some libraries
399: are intended to work with other compilers. They should install their
400: header files in two places, one specified by @code{includedir} and one
401: specified by @code{oldincludedir}.
402:
403: @item oldincludedir
404: The directory for installing @samp{#include} header files for use with
405: compilers other than GCC. This should normally be @file{/usr/include}.
406:
407: The Makefile commands should check whether the value of
408: @code{oldincludedir} is empty. If it is, they should not try to use
409: it; they should cancel the second installation of the header files.
410:
411: A package should not replace an existing header in this directory unless
412: the header came from the same package. Thus, if your Foo package
413: provides a header file @file{foo.h}, then it should install the header
414: file in the @code{oldincludedir} directory if either (1) there is no
415: @file{foo.h} there or (2) the @file{foo.h} that exists came from the Foo
416: package.
417:
418: The way to tell whether @file{foo.h} came from the Foo package is to put
419: a magic string in the file---part of a comment---and grep for that
420: string.
421:
422: @item mandir
423: The directory for installing the man pages (if any) for this package.
424: It should include the suffix for the proper section of the
425: manual---usually @samp{1} for a utility.
426:
427: @item man1dir
428: The directory for installing section 1 man pages.
429: @item man2dir
430: The directory for installing section 2 man pages.
431: @item @dots{}
432: Use these names instead of @samp{mandir} if the package needs to install man
433: pages in more than one section of the manual.
434:
435: @strong{Don't make the primary documentation for any GNU software be a
436: man page. Write a manual in Texinfo instead. Man pages are just for
437: the sake of people running GNU software on Unix, which is a secondary
438: application only.}
439:
440: @item manext
441: The file name extension for the installed man page. This should contain
442: a period followed by the appropriate digit.
443:
444: @item infodir
445: The directory for installing the info files for this package. By
446: default, it should be @file{/usr/local/info}, but it should be written
447: as @file{$(prefix)/info}.
448:
449: @item srcdir
450: The directory for the sources being compiled. The value of this
451: variable is normally inserted by the @code{configure} shell script.
452: @end table
453:
454: For example:
455:
456: @example
457: @c I have changed some of the comments here slightly to fix an overfull
458: @c hbox, so the make manual can format correctly. --roland
459: # Common prefix for installation directories.
460: # NOTE: This directory must exist when you start the install.
461: prefix = /usr/local
462: exec_prefix = $(prefix)
463: # Where to put the executable for the command `gcc'.
464: bindir = $(exec_prefix)/bin
465: # Where to put the directories used by the compiler.
466: libdir = $(exec_prefix)/lib
467: # Where to put the Info files.
468: infodir = $(prefix)/info
469: @end example
470:
471: If your program installs a large number of files into one of the
472: standard user-specified directories, it might be useful to group them
473: into a subdirectory particular to that program. If you do this, you
474: should write the @code{install} rule to create these subdirectories.
475:
476: Do not expect the user to include the subdirectory name in the value of
477: any of the variables listed above. The idea of having a uniform set of
478: variable names for installation directories is to enable the user to
479: specify the exact same values for several different GNU packages. In
480: order for this to be useful, all the packages must be designed so that
481: they will work sensibly when the user does so.
482:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.