1 This is Info file ../info/standards.info, produced by Makeinfo version
2 1.68 from the input file standards.texi.
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
9 Software Foundation, Inc.
11 Permission is granted to make and distribute verbatim copies of this
12 manual provided the copyright notice and this permission notice are
13 preserved on all copies.
15 Permission is granted to copy and distribute modified versions of
16 this manual under the conditions for verbatim copying, provided that
17 the entire resulting derived work is distributed under the terms of a
18 permission notice identical to this one.
20 Permission is granted to copy and distribute translations of this
21 manual into another language, under the above conditions for modified
22 versions, except that this permission notice may be stated in a
23 translation approved by the Free Software Foundation.
26 File: standards.info, Node: Standard Targets, Prev: Directory Variables, Up: Makefile Conventions
28 Standard Targets for Users
29 --------------------------
31 All GNU programs should have the following targets in their
35 Compile the entire program. This should be the default target.
36 This target need not rebuild any documentation files; Info files
37 should normally be included in the distribution, and DVI files
38 should be made only when explicitly asked for.
40 By default, the Make rules should compile and link with `-g', so
41 that executable programs have debugging symbols. Users who don't
42 mind being helpless can strip the executables later if they wish.
45 Compile the program and copy the executables, libraries, and so on
46 to the file names where they should reside for actual use. If
47 there is a simple test to verify that a program is properly
48 installed, this target should run that test.
50 Do not strip executables when installing them. Devil-may-care
51 users can use the `install-strip' target to do that.
53 If possible, write the `install' target rule so that it does not
54 modify anything in the directory where the program was built,
55 provided `make all' has just been done. This is convenient for
56 building the program under one user name and installing it under
59 The commands should create all the directories in which files are
60 to be installed, if they don't already exist. This includes the
61 directories specified as the values of the variables `prefix' and
62 `exec_prefix', as well as all subdirectories that are needed. One
63 way to do this is by means of an `installdirs' target as described
66 Use `-' before any command for installing a man page, so that
67 `make' will ignore any errors. This is in case there are systems
68 that don't have the Unix man page documentation system installed.
70 The way to install Info files is to copy them into `$(infodir)'
71 with `$(INSTALL_DATA)' (*note Command Variables::.), and then run
72 the `install-info' program if it is present. `install-info' is a
73 program that edits the Info `dir' file to add or update the menu
74 entry for the given Info file; it is part of the Texinfo package.
75 Here is a sample rule to install an Info file:
77 $(infodir)/foo.info: foo.info
78 # There may be a newer info file in . than in srcdir.
79 -if test -f foo.info; then d=.; \
80 else d=$(srcdir); fi; \
81 $(INSTALL_DATA) $$d/foo.info $@; \
82 # Run install-info only if it exists.
83 # Use `if' instead of just prepending `-' to the
84 # line so we notice real errors from install-info.
85 # We use `$(SHELL) -c' because some shells do not
86 # fail gracefully when there is an unknown command.
87 if $(SHELL) -c 'install-info --version' \
88 >/dev/null 2>&1; then \
89 install-info --dir-file=$(infodir)/dir \
90 $(infodir)/foo.info; \
94 Delete all the installed files that the `install' target would
95 create (but not the noninstalled files such as `make all' would
98 This rule should not modify the directories where compilation is
99 done, only the directories where files are installed.
102 Like `install', but strip the executable files while installing
103 them. The definition of this target can be very simple:
106 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
109 Normally we do not recommend stripping an executable unless you
110 are sure the program has no bugs. However, it can be reasonable
111 to install a stripped executable for actual execution while saving
112 the unstripped executable elsewhere in case there is a bug.
115 Delete all files from the current directory that are normally
116 created by building the program. Don't delete the files that
117 record the configuration. Also preserve files that could be made
118 by building, but normally aren't because the distribution comes
121 Delete `.dvi' files here if they are not part of the distribution.
124 Delete all files from the current directory that are created by
125 configuring or building the program. If you have unpacked the
126 source and built the program without creating any other files,
127 `make distclean' should leave only the files that were in the
131 Like `clean', but may refrain from deleting a few files that people
132 normally don't want to recompile. For example, the `mostlyclean'
133 target for GCC does not delete `libgcc.a', because recompiling it
134 is rarely necessary and takes a lot of time.
137 Delete almost everything from the current directory that can be
138 reconstructed with this Makefile. This typically includes
139 everything deleted by `distclean', plus more: C source files
140 produced by Bison, tags tables, Info files, and so on.
142 The reason we say "almost everything" is that running the command
143 `make maintainer-clean' should not delete `configure' even if
144 `configure' can be remade using a rule in the Makefile. More
145 generally, `make maintainer-clean' should not delete anything that
146 needs to exist in order to run `configure' and then begin to build
147 the program. This is the only exception; `maintainer-clean' should
148 delete everything else that can be rebuilt.
150 The `maintainer-clean' target is intended to be used by a
151 maintainer of the package, not by ordinary users. You may need
152 special tools to reconstruct some of the files that `make
153 maintainer-clean' deletes. Since these files are normally
154 included in the distribution, we don't take care to make them easy
155 to reconstruct. If you find you need to unpack the full
156 distribution again, don't blame us.
158 To help make users aware of this, the commands for the special
159 `maintainer-clean' target should start with these two:
161 @echo 'This command is intended for maintainers to use; it'
162 @echo 'deletes files that may need special tools to rebuild.'
165 Update a tags table for this program.
168 Generate any Info files needed. The best way to write the rules
173 foo.info: foo.texi chap1.texi chap2.texi
174 $(MAKEINFO) $(srcdir)/foo.texi
176 You must define the variable `MAKEINFO' in the Makefile. It should
177 run the `makeinfo' program, which is part of the Texinfo
181 Generate DVI files for all Texinfo documentation. For example:
185 foo.dvi: foo.texi chap1.texi chap2.texi
186 $(TEXI2DVI) $(srcdir)/foo.texi
188 You must define the variable `TEXI2DVI' in the Makefile. It should
189 run the program `texi2dvi', which is part of the Texinfo
190 distribution.(1) Alternatively, write just the dependencies, and
191 allow GNU `make' to provide the command.
194 Create a distribution tar file for this program. The tar file
195 should be set up so that the file names in the tar file start with
196 a subdirectory name which is the name of the package it is a
197 distribution for. This name can include the version number.
199 For example, the distribution tar file of GCC version 1.40 unpacks
200 into a subdirectory named `gcc-1.40'.
202 The easiest way to do this is to create a subdirectory
203 appropriately named, use `ln' or `cp' to install the proper files
204 in it, and then `tar' that subdirectory.
206 Compress the tar file with `gzip'. For example, the actual
207 distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
209 The `dist' target should explicitly depend on all non-source files
210 that are in the distribution, to make sure they are up to date in
211 the distribution. *Note Making Releases: Releases.
214 Perform self-tests (if any). The user must build the program
215 before running the tests, but need not install the program; you
216 should write the self-tests so that they work when the program is
217 built but not installed.
219 The following targets are suggested as conventional names, for
220 programs in which they are useful.
223 Perform installation tests (if any). The user must build and
224 install the program before running the tests. You should not
225 assume that `$(bindir)' is in the search path.
228 It's useful to add a target named `installdirs' to create the
229 directories where files are installed, and their parent
230 directories. There is a script called `mkinstalldirs' which is
231 convenient for this; you can find it in the Texinfo package. You
232 can use a rule like this:
234 # Make sure all installation directories (e.g. $(bindir))
235 # actually exist by making them if necessary.
236 installdirs: mkinstalldirs
237 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
238 $(libdir) $(infodir) \
241 This rule should not modify the directories where compilation is
242 done. It should do nothing but create installation directories.
244 ---------- Footnotes ----------
246 (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
247 not distributed with Texinfo.
250 File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
255 Package the distribution of Foo version 69.96 in a gzipped tar file
256 named `foo-69.96.tar.gz'. It should unpack into a subdirectory named
259 Building and installing the program should never modify any of the
260 files contained in the distribution. This means that all the files
261 that form part of the program in any way must be classified into "source
262 files" and "non-source files". Source files are written by humans and
263 never changed automatically; non-source files are produced from source
264 files by programs under the control of the Makefile.
266 Naturally, all the source files must be in the distribution. It is
267 okay to include non-source files in the distribution, provided they are
268 up-to-date and machine-independent, so that building the distribution
269 normally will never modify them. We commonly include non-source files
270 produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
271 unnecessary dependencies between our distributions, so that users can
272 install whichever packages they want to install.
274 Non-source files that might actually be modified by building and
275 installing the program should *never* be included in the distribution.
276 So if you do distribute non-source files, always make sure they are up
277 to date when you make a new distribution.
279 Make sure that the directory into which the distribution unpacks (as
280 well as any subdirectories) are all world-writable (octal mode 777).
281 This is so that old versions of `tar' which preserve the ownership and
282 permissions of the files from the tar archive will be able to extract
283 all the files even if the user is unprivileged.
285 Make sure that all the files in the distribution are world-readable.
287 Make sure that no file name in the distribution is more than 14
288 characters long. Likewise, no file created by building the program
289 should have a name longer than 14 characters. The reason for this is
290 that some systems adhere to a foolish interpretation of the POSIX
291 standard, and refuse to open a longer name, rather than truncating as
292 they did in the past.
294 Don't include any symbolic links in the distribution itself. If the
295 tar file contains symbolic links, then people cannot even unpack it on
296 systems that don't support symbolic links. Also, don't use multiple
297 names for one file in different directories, because certain file
298 systems cannot handle this and that prevents unpacking the distribution.
300 Try to make sure that all the file names will be unique on MS-DOS. A
301 name on MS-DOS consists of up to 8 characters, optionally followed by a
302 period and up to three characters. MS-DOS will truncate extra
303 characters both before and after the period. Thus, `foobarhacker.c'
304 and `foobarhacker.o' are not ambiguous; they are truncated to
305 `foobarha.c' and `foobarha.o', which are distinct.
307 Include in your distribution a copy of the `texinfo.tex' you used to
308 test print any `*.texinfo' or `*.texi' files.
310 Likewise, if your program uses small GNU software packages like
311 regex, getopt, obstack, or termcap, include them in the distribution
312 file. Leaving them out would make the distribution file a little
313 smaller at the expense of possible inconvenience to a user who doesn't
314 know what other files to get.
projects / chise / xemacs-chise.git.1 / blob