1 This is ../info/standards.info, produced by makeinfo version 4.0 from
5 * Standards: (standards). GNU coding standards.
8 GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996,
9 1997, 1998, 1999 Free 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: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
28 Utilities in Makefiles
29 ----------------------
31 Write the Makefile commands (and any shell scripts, such as
32 `configure') to run in `sh', not in `csh'. Don't use any special
33 features of `ksh' or `bash'.
35 The `configure' script and the Makefile rules for building and
36 installation should not use any utilities directly except these:
38 cat cmp cp diff echo egrep expr false grep install-info
39 ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
41 The compression program `gzip' can be used in the `dist' rule.
43 Stick to the generally supported options for these programs. For
44 example, don't use `mkdir -p', convenient as it may be, because most
45 systems don't support it.
47 It is a good idea to avoid creating symbolic links in makefiles,
48 since a few systems don't support them.
50 The Makefile rules for building and installation can also use
51 compilers and related programs, but should do so via `make' variables
52 so that the user can substitute alternatives. Here are some of the
55 ar bison cc flex install ld ldconfig lex
56 make makeinfo ranlib texi2dvi yacc
58 Use the following `make' variables to run those programs:
60 $(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
61 $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
63 When you use `ranlib' or `ldconfig', you should make sure nothing
64 bad happens if the system does not have the program in question.
65 Arrange to ignore an error from that command, and print a message before
66 the command to tell the user that failure of this command does not mean
67 a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
69 If you use symbolic links, you should implement a fallback for
70 systems that don't have symbolic links.
72 Additional utilities that can be used via Make variables are:
74 chgrp chmod chown mknod
76 It is ok to use other utilities in Makefile portions (or scripts)
77 intended only for particular systems where you know those utilities
81 File: standards.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
83 Variables for Specifying Commands
84 ---------------------------------
86 Makefiles should provide variables for overriding certain commands,
89 In particular, you should run most utility programs via variables.
90 Thus, if you use Bison, have a variable named `BISON' whose default
91 value is set with `BISON = bison', and refer to it with `$(BISON)'
92 whenever you need to use Bison.
94 File management utilities such as `ln', `rm', `mv', and so on, need
95 not be referred to through variables in this way, since users don't
96 need to replace them with other programs.
98 Each program-name variable should come with an options variable that
99 is used to supply options to the program. Append `FLAGS' to the
100 program-name variable name to get the options variable name--for
101 example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
102 `YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
103 but we keep them because they are standard.) Use `CPPFLAGS' in any
104 compilation command that runs the preprocessor, and use `LDFLAGS' in
105 any compilation command that does linking as well as in any direct use
108 If there are C compiler options that _must_ be used for proper
109 compilation of certain files, do not include them in `CFLAGS'. Users
110 expect to be able to specify `CFLAGS' freely themselves. Instead,
111 arrange to pass the necessary options to the C compiler independently
112 of `CFLAGS', by writing them explicitly in the compilation commands or
113 by defining an implicit rule, like this:
116 ALL_CFLAGS = -I. $(CFLAGS)
118 $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
120 Do include the `-g' option in `CFLAGS', because that is not
121 _required_ for proper compilation. You can consider it a default that
122 is only recommended. If the package is set up so that it is compiled
123 with GCC by default, then you might as well include `-O' in the default
124 value of `CFLAGS' as well.
126 Put `CFLAGS' last in the compilation command, after other variables
127 containing compiler options, so the user can use `CFLAGS' to override
130 `CFLAGS' should be used in every invocation of the C compiler, both
131 those which do compilation and those which do linking.
133 Every Makefile should define the variable `INSTALL', which is the
134 basic command for installing a file into the system.
136 Every Makefile should also define the variables `INSTALL_PROGRAM'
137 and `INSTALL_DATA'. (The default for each of these should be
138 `$(INSTALL)'.) Then it should use those variables as the commands for
139 actual installation, for executables and nonexecutables respectively.
140 Use these variables as follows:
142 $(INSTALL_PROGRAM) foo $(bindir)/foo
143 $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
145 Optionally, you may prepend the value of `DESTDIR' to the target
146 filename. Doing this allows the installer to create a snapshot of the
147 installation to be copied onto the real target filesystem later. Do not
148 set the value of `DESTDIR' in your Makefile, and do not include it in
149 any installed files. With support for `DESTDIR', the above examples
152 $(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
153 $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
155 Always use a file name, not a directory name, as the second argument of
156 the installation commands. Use a separate command for each file to be
160 File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
162 Variables for Installation Directories
163 --------------------------------------
165 Installation directories should always be named by variables, so it
166 is easy to install in a nonstandard place. The standard names for these
167 variables are described below. They are based on a standard filesystem
168 layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
169 other modern operating systems.
171 These two variables set the root for the installation. All the other
172 installation directories should be subdirectories of one of these two,
173 and nothing should be directly installed into these two directories.
176 A prefix used in constructing the default values of the variables
177 listed below. The default value of `prefix' should be
178 `/usr/local'. When building the complete GNU system, the prefix
179 will be empty and `/usr' will be a symbolic link to `/'. (If you
180 are using Autoconf, write it as `@prefix@'.)
182 Running `make install' with a different value of `prefix' from the
183 one used to build the program should NOT recompile the program.
186 A prefix used in constructing the default values of some of the
187 variables listed below. The default value of `exec_prefix' should
188 be `$(prefix)'. (If you are using Autoconf, write it as
191 Generally, `$(exec_prefix)' is used for directories that contain
192 machine-specific files (such as executables and subroutine
193 libraries), while `$(prefix)' is used directly for other
196 Running `make install' with a different value of `exec_prefix'
197 from the one used to build the program should NOT recompile the
200 Executable programs are installed in one of the following
204 The directory for installing executable programs that users can
205 run. This should normally be `/usr/local/bin', but write it as
206 `$(exec_prefix)/bin'. (If you are using Autoconf, write it as
210 The directory for installing executable programs that can be run
211 from the shell, but are only generally useful to system
212 administrators. This should normally be `/usr/local/sbin', but
213 write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
214 write it as `@sbindir@'.)
217 The directory for installing executable programs to be run by other
218 programs rather than by users. This directory should normally be
219 `/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
220 (If you are using Autoconf, write it as `@libexecdir@'.)
222 Data files used by the program during its execution are divided into
223 categories in two ways.
225 * Some files are normally modified by programs; others are never
226 normally modified (though users may edit some of these).
228 * Some files are architecture-independent and can be shared by all
229 machines at a site; some are architecture-dependent and can be
230 shared only by machines of the same kind and operating system;
231 others may never be shared between two machines.
233 This makes for six different possibilities. However, we want to
234 discourage the use of architecture-dependent files, aside from object
235 files and libraries. It is much cleaner to make other data files
236 architecture-independent, and it is generally not hard.
238 Therefore, here are the variables Makefiles should use to specify
242 The directory for installing read-only architecture independent
243 data files. This should normally be `/usr/local/share', but write
244 it as `$(prefix)/share'. (If you are using Autoconf, write it as
245 `@datadir@'.) As a special exception, see `$(infodir)' and
246 `$(includedir)' below.
249 The directory for installing read-only data files that pertain to a
250 single machine-that is to say, files for configuring a host.
251 Mailer and network configuration files, `/etc/passwd', and so
252 forth belong here. All the files in this directory should be
253 ordinary ASCII text files. This directory should normally be
254 `/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
255 using Autoconf, write it as `@sysconfdir@'.)
257 Do not install executables here in this directory (they probably
258 belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
259 files that are modified in the normal course of their use (programs
260 whose purpose is to change the configuration of the system
261 excluded). Those probably belong in `$(localstatedir)'.
264 The directory for installing architecture-independent data files
265 which the programs modify while they run. This should normally be
266 `/usr/local/com', but write it as `$(prefix)/com'. (If you are
267 using Autoconf, write it as `@sharedstatedir@'.)
270 The directory for installing data files which the programs modify
271 while they run, and that pertain to one specific machine. Users
272 should never need to modify files in this directory to configure
273 the package's operation; put such configuration information in
274 separate files that go in `$(datadir)' or `$(sysconfdir)'.
275 `$(localstatedir)' should normally be `/usr/local/var', but write
276 it as `$(prefix)/var'. (If you are using Autoconf, write it as
280 The directory for object files and libraries of object code. Do
281 not install executables here, they probably ought to go in
282 `$(libexecdir)' instead. The value of `libdir' should normally be
283 `/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
284 are using Autoconf, write it as `@libdir@'.)
287 The directory for installing the Info files for this package. By
288 default, it should be `/usr/local/info', but it should be written
289 as `$(prefix)/info'. (If you are using Autoconf, write it as
293 The directory for installing any Emacs Lisp files in this package.
294 By default, it should be `/usr/local/share/emacs/site-lisp', but
295 it should be written as `$(prefix)/share/emacs/site-lisp'.
297 If you are using Autoconf, write the default as `@lispdir@'. In
298 order to make `@lispdir@' work, you need the following lines in
299 your `configure.in' file:
301 lispdir='${datadir}/emacs/site-lisp'
305 The directory for installing header files to be included by user
306 programs with the C `#include' preprocessor directive. This
307 should normally be `/usr/local/include', but write it as
308 `$(prefix)/include'. (If you are using Autoconf, write it as
311 Most compilers other than GCC do not look for header files in
312 directory `/usr/local/include'. So installing the header files
313 this way is only useful with GCC. Sometimes this is not a problem
314 because some libraries are only really intended to work with GCC.
315 But some libraries are intended to work with other compilers.
316 They should install their header files in two places, one
317 specified by `includedir' and one specified by `oldincludedir'.
320 The directory for installing `#include' header files for use with
321 compilers other than GCC. This should normally be `/usr/include'.
322 (If you are using Autoconf, you can write it as `@oldincludedir@'.)
324 The Makefile commands should check whether the value of
325 `oldincludedir' is empty. If it is, they should not try to use
326 it; they should cancel the second installation of the header files.
328 A package should not replace an existing header in this directory
329 unless the header came from the same package. Thus, if your Foo
330 package provides a header file `foo.h', then it should install the
331 header file in the `oldincludedir' directory if either (1) there
332 is no `foo.h' there or (2) the `foo.h' that exists came from the
335 To tell whether `foo.h' came from the Foo package, put a magic
336 string in the file--part of a comment--and `grep' for that string.
338 Unix-style man pages are installed in one of the following:
341 The top-level directory for installing the man pages (if any) for
342 this package. It will normally be `/usr/local/man', but you should
343 write it as `$(prefix)/man'. (If you are using Autoconf, write it
347 The directory for installing section 1 man pages. Write it as
351 The directory for installing section 2 man pages. Write it as
355 *Don't make the primary documentation for any GNU software be a
356 man page. Write a manual in Texinfo instead. Man pages are just
357 for the sake of people running GNU software on Unix, which is a
358 secondary application only.*
361 The file name extension for the installed man page. This should
362 contain a period followed by the appropriate digit; it should
366 The file name extension for installed section 1 man pages.
369 The file name extension for installed section 2 man pages.
372 Use these names instead of `manext' if the package needs to
373 install man pages in more than one section of the manual.
375 And finally, you should set the following variable:
378 The directory for the sources being compiled. The value of this
379 variable is normally inserted by the `configure' shell script.
380 (If you are using Autoconf, use `srcdir = @srcdir@'.)
384 # Common prefix for installation directories.
385 # NOTE: This directory must exist when you start the install.
387 exec_prefix = $(prefix)
388 # Where to put the executable for the command `gcc'.
389 bindir = $(exec_prefix)/bin
390 # Where to put the directories used by the compiler.
391 libexecdir = $(exec_prefix)/libexec
392 # Where to put the Info files.
393 infodir = $(prefix)/info
395 If your program installs a large number of files into one of the
396 standard user-specified directories, it might be useful to group them
397 into a subdirectory particular to that program. If you do this, you
398 should write the `install' rule to create these subdirectories.
400 Do not expect the user to include the subdirectory name in the value
401 of any of the variables listed above. The idea of having a uniform set
402 of variable names for installation directories is to enable the user to
403 specify the exact same values for several different GNU packages. In
404 order for this to be useful, all the packages must be designed so that
405 they will work sensibly when the user does so.
408 File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
410 Standard Targets for Users
411 --------------------------
413 All GNU programs should have the following targets in their
417 Compile the entire program. This should be the default target.
418 This target need not rebuild any documentation files; Info files
419 should normally be included in the distribution, and DVI files
420 should be made only when explicitly asked for.
422 By default, the Make rules should compile and link with `-g', so
423 that executable programs have debugging symbols. Users who don't
424 mind being helpless can strip the executables later if they wish.
427 Compile the program and copy the executables, libraries, and so on
428 to the file names where they should reside for actual use. If
429 there is a simple test to verify that a program is properly
430 installed, this target should run that test.
432 Do not strip executables when installing them. Devil-may-care
433 users can use the `install-strip' target to do that.
435 If possible, write the `install' target rule so that it does not
436 modify anything in the directory where the program was built,
437 provided `make all' has just been done. This is convenient for
438 building the program under one user name and installing it under
441 The commands should create all the directories in which files are
442 to be installed, if they don't already exist. This includes the
443 directories specified as the values of the variables `prefix' and
444 `exec_prefix', as well as all subdirectories that are needed. One
445 way to do this is by means of an `installdirs' target as described
448 Use `-' before any command for installing a man page, so that
449 `make' will ignore any errors. This is in case there are systems
450 that don't have the Unix man page documentation system installed.
452 The way to install Info files is to copy them into `$(infodir)'
453 with `$(INSTALL_DATA)' (*note Command Variables::), and then run
454 the `install-info' program if it is present. `install-info' is a
455 program that edits the Info `dir' file to add or update the menu
456 entry for the given Info file; it is part of the Texinfo package.
457 Here is a sample rule to install an Info file:
459 $(DESTDIR)$(infodir)/foo.info: foo.info
461 # There may be a newer info file in . than in srcdir.
462 -if test -f foo.info; then d=.; \
463 else d=$(srcdir); fi; \
464 $(INSTALL_DATA) $$d/foo.info $(DESTDIR)$@; \
465 # Run install-info only if it exists.
466 # Use `if' instead of just prepending `-' to the
467 # line so we notice real errors from install-info.
468 # We use `$(SHELL) -c' because some shells do not
469 # fail gracefully when there is an unknown command.
470 if $(SHELL) -c 'install-info --version' \
471 >/dev/null 2>&1; then \
472 install-info --dir-file=$(DESTDIR)$(infodir)/dir \
473 $(DESTDIR)$(infodir)/foo.info; \
476 When writing the `install' target, you must classify all the
477 commands into three categories: normal ones, "pre-installation"
478 commands and "post-installation" commands. *Note Install Command
482 Delete all the installed files--the copies that the `install'
485 This rule should not modify the directories where compilation is
486 done, only the directories where files are installed.
488 The uninstallation commands are divided into three categories,
489 just like the installation commands. *Note Install Command
493 Like `install', but strip the executable files while installing
494 them. In many cases, the definition of this target can be very
498 $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
501 Normally we do not recommend stripping an executable unless you
502 are sure the program has no bugs. However, it can be reasonable
503 to install a stripped executable for actual execution while saving
504 the unstripped executable elsewhere in case there is a bug.
507 Delete all files from the current directory that are normally
508 created by building the program. Don't delete the files that
509 record the configuration. Also preserve files that could be made
510 by building, but normally aren't because the distribution comes
513 Delete `.dvi' files here if they are not part of the distribution.
516 Delete all files from the current directory that are created by
517 configuring or building the program. If you have unpacked the
518 source and built the program without creating any other files,
519 `make distclean' should leave only the files that were in the
523 Like `clean', but may refrain from deleting a few files that people
524 normally don't want to recompile. For example, the `mostlyclean'
525 target for GCC does not delete `libgcc.a', because recompiling it
526 is rarely necessary and takes a lot of time.
529 Delete almost everything from the current directory that can be
530 reconstructed with this Makefile. This typically includes
531 everything deleted by `distclean', plus more: C source files
532 produced by Bison, tags tables, Info files, and so on.
534 The reason we say "almost everything" is that running the command
535 `make maintainer-clean' should not delete `configure' even if
536 `configure' can be remade using a rule in the Makefile. More
537 generally, `make maintainer-clean' should not delete anything that
538 needs to exist in order to run `configure' and then begin to build
539 the program. This is the only exception; `maintainer-clean' should
540 delete everything else that can be rebuilt.
542 The `maintainer-clean' target is intended to be used by a
543 maintainer of the package, not by ordinary users. You may need
544 special tools to reconstruct some of the files that `make
545 maintainer-clean' deletes. Since these files are normally
546 included in the distribution, we don't take care to make them easy
547 to reconstruct. If you find you need to unpack the full
548 distribution again, don't blame us.
550 To help make users aware of this, the commands for the special
551 `maintainer-clean' target should start with these two:
553 @echo 'This command is intended for maintainers to use; it'
554 @echo 'deletes files that may need special tools to rebuild.'
557 Update a tags table for this program.
560 Generate any Info files needed. The best way to write the rules
565 foo.info: foo.texi chap1.texi chap2.texi
566 $(MAKEINFO) $(srcdir)/foo.texi
568 You must define the variable `MAKEINFO' in the Makefile. It should
569 run the `makeinfo' program, which is part of the Texinfo
572 Normally a GNU distribution comes with Info files, and that means
573 the Info files are present in the source directory. Therefore,
574 the Make rule for an info file should update it in the source
575 directory. When users build the package, ordinarily Make will not
576 update the Info files because they will already be up to date.
579 Generate DVI files for all Texinfo documentation. For example:
583 foo.dvi: foo.texi chap1.texi chap2.texi
584 $(TEXI2DVI) $(srcdir)/foo.texi
586 You must define the variable `TEXI2DVI' in the Makefile. It should
587 run the program `texi2dvi', which is part of the Texinfo
588 distribution.(1) Alternatively, write just the dependencies, and
589 allow GNU `make' to provide the command.
592 Create a distribution tar file for this program. The tar file
593 should be set up so that the file names in the tar file start with
594 a subdirectory name which is the name of the package it is a
595 distribution for. This name can include the version number.
597 For example, the distribution tar file of GCC version 1.40 unpacks
598 into a subdirectory named `gcc-1.40'.
600 The easiest way to do this is to create a subdirectory
601 appropriately named, use `ln' or `cp' to install the proper files
602 in it, and then `tar' that subdirectory.
604 Compress the tar file file with `gzip'. For example, the actual
605 distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
607 The `dist' target should explicitly depend on all non-source files
608 that are in the distribution, to make sure they are up to date in
609 the distribution. *Note Making Releases: Releases.
612 Perform self-tests (if any). The user must build the program
613 before running the tests, but need not install the program; you
614 should write the self-tests so that they work when the program is
615 built but not installed.
617 The following targets are suggested as conventional names, for
618 programs in which they are useful.
621 Perform installation tests (if any). The user must build and
622 install the program before running the tests. You should not
623 assume that `$(bindir)' is in the search path.
626 It's useful to add a target named `installdirs' to create the
627 directories where files are installed, and their parent
628 directories. There is a script called `mkinstalldirs' which is
629 convenient for this; you can find it in the Texinfo package. You
630 can use a rule like this:
632 # Make sure all installation directories (e.g. $(bindir))
633 # actually exist by making them if necessary.
634 installdirs: mkinstalldirs
635 $(srcdir)/mkinstalldirs $(bindir) $(datadir) \
636 $(libdir) $(infodir) \
639 This rule should not modify the directories where compilation is
640 done. It should do nothing but create installation directories.
642 ---------- Footnotes ----------
644 (1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
645 not distributed with Texinfo.
648 File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
650 Install Command Categories
651 --------------------------
653 When writing the `install' target, you must classify all the
654 commands into three categories: normal ones, "pre-installation"
655 commands and "post-installation" commands.
657 Normal commands move files into their proper places, and set their
658 modes. They may not alter any files except the ones that come entirely
659 from the package they belong to.
661 Pre-installation and post-installation commands may alter other
662 files; in particular, they can edit global configuration files or data
665 Pre-installation commands are typically executed before the normal
666 commands, and post-installation commands are typically run after the
669 The most common use for a post-installation command is to run
670 `install-info'. This cannot be done with a normal command, since it
671 alters a file (the Info directory) which does not come entirely and
672 solely from the package being installed. It is a post-installation
673 command because it needs to be done after the normal command which
674 installs the package's Info files.
676 Most programs don't need any pre-installation commands, but we have
677 the feature just in case it is needed.
679 To classify the commands in the `install' rule into these three
680 categories, insert "category lines" among them. A category line
681 specifies the category for the commands that follow.
683 A category line consists of a tab and a reference to a special Make
684 variable, plus an optional comment at the end. There are three
685 variables you can use, one for each category; the variable name
686 specifies the category. Category lines are no-ops in ordinary execution
687 because these three Make variables are normally undefined (and you
688 _should not_ define them in the makefile).
690 Here are the three possible category lines, each with a comment that
691 explains what it means:
693 $(PRE_INSTALL) # Pre-install commands follow.
694 $(POST_INSTALL) # Post-install commands follow.
695 $(NORMAL_INSTALL) # Normal commands follow.
697 If you don't use a category line at the beginning of the `install'
698 rule, all the commands are classified as normal until the first category
699 line. If you don't use any category lines, all the commands are
700 classified as normal.
702 These are the category lines for `uninstall':
704 $(PRE_UNINSTALL) # Pre-uninstall commands follow.
705 $(POST_UNINSTALL) # Post-uninstall commands follow.
706 $(NORMAL_UNINSTALL) # Normal commands follow.
708 Typically, a pre-uninstall command would be used for deleting entries
709 from the Info directory.
711 If the `install' or `uninstall' target has any dependencies which
712 act as subroutines of installation, then you should start _each_
713 dependency's commands with a category line, and start the main target's
714 commands with a category line also. This way, you can ensure that each
715 command is placed in the right category regardless of which of the
716 dependencies actually run.
718 Pre-installation and post-installation commands should not run any
719 programs except for these:
721 [ basename bash cat chgrp chmod chown cmp cp dd diff echo
722 egrep expand expr false fgrep find getopt grep gunzip gzip
723 hostname install install-info kill ldconfig ln ls md5sum
724 mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
725 test touch true uname xargs yes
727 The reason for distinguishing the commands in this way is for the
728 sake of making binary packages. Typically a binary package contains
729 all the executables and other files that need to be installed, and has
730 its own method of installing them--so it does not need to run the normal
731 installation commands. But installing the binary package does need to
732 execute the pre-installation and post-installation commands.
734 Programs to build binary packages work by extracting the
735 pre-installation and post-installation commands. Here is one way of
736 extracting the pre-installation commands:
738 make -n install -o all \
739 PRE_INSTALL=pre-install \
740 POST_INSTALL=post-install \
741 NORMAL_INSTALL=normal-install \
742 | gawk -f pre-install.awk
744 where the file `pre-install.awk' could contain this:
746 $0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
748 $0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
750 The resulting file of pre-installation commands is executed as a
751 shell script as part of installing the binary package.
754 File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
759 Package the distribution of `Foo version 69.96' up in a gzipped tar
760 file with the name `foo-69.96.tar.gz'. It should unpack into a
761 subdirectory named `foo-69.96'.
763 Building and installing the program should never modify any of the
764 files contained in the distribution. This means that all the files
765 that form part of the program in any way must be classified into "source
766 files" and "non-source files". Source files are written by humans and
767 never changed automatically; non-source files are produced from source
768 files by programs under the control of the Makefile.
770 The distribution should contain a file named `README' which gives
771 the name of the package, and a general description of what it does. It
772 is also good to explain the purpose of each of the first-level
773 subdirectories in the package, if there are any. The `README' file
774 should either state the version number of the package, or refer to where
775 in the package it can be found.
777 The `README' file should refer to the file `INSTALL', which should
778 contain an explanation of the installation procedure.
780 The `README' file should also refer to the file which contains the
781 copying conditions. The GNU GPL, if used, should be in a file called
782 `COPYING'. If the GNU LGPL is used, it should be in a file called
785 Naturally, all the source files must be in the distribution. It is
786 okay to include non-source files in the distribution, provided they are
787 up-to-date and machine-independent, so that building the distribution
788 normally will never modify them. We commonly include non-source files
789 produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
790 unnecessary dependencies between our distributions, so that users can
791 install whichever packages they want to install.
793 Non-source files that might actually be modified by building and
794 installing the program should *never* be included in the distribution.
795 So if you do distribute non-source files, always make sure they are up
796 to date when you make a new distribution.
798 Make sure that the directory into which the distribution unpacks (as
799 well as any subdirectories) are all world-writable (octal mode 777).
800 This is so that old versions of `tar' which preserve the ownership and
801 permissions of the files from the tar archive will be able to extract
802 all the files even if the user is unprivileged.
804 Make sure that all the files in the distribution are world-readable.
806 Make sure that no file name in the distribution is more than 14
807 characters long. Likewise, no file created by building the program
808 should have a name longer than 14 characters. The reason for this is
809 that some systems adhere to a foolish interpretation of the POSIX
810 standard, and refuse to open a longer name, rather than truncating as
811 they did in the past.
813 Don't include any symbolic links in the distribution itself. If the
814 tar file contains symbolic links, then people cannot even unpack it on
815 systems that don't support symbolic links. Also, don't use multiple
816 names for one file in different directories, because certain file
817 systems cannot handle this and that prevents unpacking the distribution.
819 Try to make sure that all the file names will be unique on MS-DOS. A
820 name on MS-DOS consists of up to 8 characters, optionally followed by a
821 period and up to three characters. MS-DOS will truncate extra
822 characters both before and after the period. Thus, `foobarhacker.c'
823 and `foobarhacker.o' are not ambiguous; they are truncated to
824 `foobarha.c' and `foobarha.o', which are distinct.
826 Include in your distribution a copy of the `texinfo.tex' you used to
827 test print any `*.texinfo' or `*.texi' files.
829 Likewise, if your program uses small GNU software packages like
830 regex, getopt, obstack, or termcap, include them in the distribution
831 file. Leaving them out would make the distribution file a little
832 smaller at the expense of possible inconvenience to a user who doesn't
833 know what other files to get.
836 File: standards.info, Node: References, Prev: Managing Releases, Up: Top
838 References to Non-Free Software and Documentation
839 *************************************************
841 A GNU program should not recommend use of any non-free program. We
842 can't stop some people from writing proprietary programs, or stop other
843 people from using them. But we can and should avoid helping to
844 advertise them to new customers.
846 Sometimes it is important to mention how to build your package on
847 top of some non-free operating system or other non-free base package.
848 In such cases, please mention the name of the non-free package or
849 system in the briefest possible way. Don't include any references for
850 where to find more information about the proprietary program. The goal
851 should be that people already using the proprietary program will get
852 the advice they need about how to use your free program, while people
853 who don't already use the proprietary program will not see anything to
854 encourage them to take an interest in it.
856 Likewise, a GNU package should not refer the user to any non-free
857 documentation for free software. The need for free documentation to go
858 with free software is now a major focus of the GNU project; to show that
859 we are serious about the need for free documentation, we must not
860 undermine our position by recommending use of documentation that isn't