680 lines
29 KiB
Plaintext
680 lines
29 KiB
Plaintext
This is Info file standards.info, produced by Makeinfo-1.64 from the
|
||
input file ./standards.texi.
|
||
|
||
START-INFO-DIR-ENTRY
|
||
* Standards: (standards). GNU coding standards.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
GNU Coding Standards Copyright (C) 1992, 1993, 1994, 1995, 1996 Free
|
||
Software Foundation, Inc.
|
||
|
||
Permission is granted to make and distribute verbatim copies of this
|
||
manual provided the copyright notice and this permission notice are
|
||
preserved on all copies.
|
||
|
||
Permission is granted to copy and distribute modified versions of
|
||
this manual under the conditions for verbatim copying, provided that
|
||
the entire resulting derived work is distributed under the terms of a
|
||
permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this
|
||
manual into another language, under the above conditions for modified
|
||
versions, except that this permission notice may be stated in a
|
||
translation approved by the Free Software Foundation.
|
||
|
||
|
||
File: standards.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
|
||
|
||
Variables for Installation Directories
|
||
--------------------------------------
|
||
|
||
Installation directories should always be named by variables, so it
|
||
is easy to install in a nonstandard place. The standard names for these
|
||
variables are described below. They are based on a standard filesystem
|
||
layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
|
||
other modern operating systems.
|
||
|
||
These two variables set the root for the installation. All the other
|
||
installation directories should be subdirectories of one of these two,
|
||
and nothing should be directly installed into these two directories.
|
||
|
||
`prefix'
|
||
A prefix used in constructing the default values of the variables
|
||
listed below. The default value of `prefix' should be
|
||
`/usr/local'. When building the complete GNU system, the prefix
|
||
will be empty and `/usr' will be a symbolic link to `/'. (If you
|
||
are using Autoconf, write it as `@prefix@'.)
|
||
|
||
`exec_prefix'
|
||
A prefix used in constructing the default values of some of the
|
||
variables listed below. The default value of `exec_prefix' should
|
||
be `$(prefix)'. (If you are using Autoconf, write it as
|
||
`@exec_prefix@'.)
|
||
|
||
Generally, `$(exec_prefix)' is used for directories that contain
|
||
machine-specific files (such as executables and subroutine
|
||
libraries), while `$(prefix)' is used directly for other
|
||
directories.
|
||
|
||
Executable programs are installed in one of the following
|
||
directories.
|
||
|
||
`bindir'
|
||
The directory for installing executable programs that users can
|
||
run. This should normally be `/usr/local/bin', but write it as
|
||
`$(exec_prefix)/bin'. (If you are using Autoconf, write it as
|
||
`@bindir@'.)
|
||
|
||
`sbindir'
|
||
The directory for installing executable programs that can be run
|
||
from the shell, but are only generally useful to system
|
||
administrators. This should normally be `/usr/local/sbin', but
|
||
write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
|
||
write it as `@sbindir@'.)
|
||
|
||
`libexecdir'
|
||
The directory for installing executable programs to be run by other
|
||
programs rather than by users. This directory should normally be
|
||
`/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
|
||
(If you are using Autoconf, write it as `@libexecdir@'.)
|
||
|
||
Data files used by the program during its execution are divided into
|
||
categories in two ways.
|
||
|
||
* Some files are normally modified by programs; others are never
|
||
normally modified (though users may edit some of these).
|
||
|
||
* Some files are architecture-independent and can be shared by all
|
||
machines at a site; some are architecture-dependent and can be
|
||
shared only by machines of the same kind and operating system;
|
||
others may never be shared between two machines.
|
||
|
||
This makes for six different possibilities. However, we want to
|
||
discourage the use of architecture-dependent files, aside from object
|
||
files and libraries. It is much cleaner to make other data files
|
||
architecture-independent, and it is generally not hard.
|
||
|
||
Therefore, here are the variables Makefiles should use to specify
|
||
directories:
|
||
|
||
`datadir'
|
||
The directory for installing read-only architecture independent
|
||
data files. This should normally be `/usr/local/share', but write
|
||
it as `$(prefix)/share'. (If you are using Autoconf, write it as
|
||
`@datadir@'.) As a special exception, see `$(infodir)' and
|
||
`$(includedir)' below.
|
||
|
||
`sysconfdir'
|
||
The directory for installing read-only data files that pertain to a
|
||
single machine-that is to say, files for configuring a host.
|
||
Mailer and network configuration files, `/etc/passwd', and so
|
||
forth belong here. All the files in this directory should be
|
||
ordinary ASCII text files. This directory should normally be
|
||
`/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
|
||
using Autoconf, write it as `@sysconfdir@'.)
|
||
|
||
Do not install executables in this directory (they probably belong
|
||
in `$(libexecdir)' or `$(sbindir)'). Also do not install files
|
||
that are modified in the normal course of their use (programs
|
||
whose purpose is to change the configuration of the system
|
||
excluded). Those probably belong in `$(localstatedir)'.
|
||
|
||
`sharedstatedir'
|
||
The directory for installing architecture-independent data files
|
||
which the programs modify while they run. This should normally be
|
||
`/usr/local/com', but write it as `$(prefix)/com'. (If you are
|
||
using Autoconf, write it as `@sharedstatedir@'.)
|
||
|
||
`localstatedir'
|
||
The directory for installing data files which the programs modify
|
||
while they run, and that pertain to one specific machine. Users
|
||
should never need to modify files in this directory to configure
|
||
the package's operation; put such configuration information in
|
||
separate files that go in `$(datadir)' or `$(sysconfdir)'.
|
||
`$(localstatedir)' should normally be `/usr/local/var', but write
|
||
it as `$(prefix)/var'. (If you are using Autoconf, write it as
|
||
`@localstatedir@'.)
|
||
|
||
`libdir'
|
||
The directory for object files and libraries of object code. Do
|
||
not install executables here, they probably ought to go in
|
||
`$(libexecdir)' instead. The value of `libdir' should normally be
|
||
`/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
|
||
are using Autoconf, write it as `@libdir@'.)
|
||
|
||
`infodir'
|
||
The directory for installing the Info files for this package. By
|
||
default, it should be `/usr/local/info', but it should be written
|
||
as `$(prefix)/info'. (If you are using Autoconf, write it as
|
||
`@infodir@'.)
|
||
|
||
`lispdir'
|
||
The directory for installing any Emacs Lisp files in this package.
|
||
By default, it should be `/usr/local/share/emacs/site-lisp', but
|
||
it should be written as `$(prefix)/share/emacs/site-lisp'.
|
||
|
||
If you are using Autoconf, write the default as `@lispdir@'. In
|
||
order to make `@lispdir@' work, you need the following lines in
|
||
your `configure.in' file:
|
||
|
||
lispdir='${datadir}/emacs/site-lisp'
|
||
AC_SUBST(lispdir)
|
||
|
||
`includedir'
|
||
The directory for installing header files to be included by user
|
||
programs with the C `#include' preprocessor directive. This
|
||
should normally be `/usr/local/include', but write it as
|
||
`$(prefix)/include'. (If you are using Autoconf, write it as
|
||
`@includedir@'.)
|
||
|
||
Most compilers other than GCC do not look for header files in
|
||
`/usr/local/include'. So installing the header files this way is
|
||
only useful with GCC. Sometimes this is not a problem because some
|
||
libraries are only really intended to work with GCC. But some
|
||
libraries are intended to work with other compilers. They should
|
||
install their header files in two places, one specified by
|
||
`includedir' and one specified by `oldincludedir'.
|
||
|
||
`oldincludedir'
|
||
The directory for installing `#include' header files for use with
|
||
compilers other than GCC. This should normally be `/usr/include'.
|
||
(If you are using Autoconf, you can write it as `@oldincludedir@'.)
|
||
|
||
The Makefile commands should check whether the value of
|
||
`oldincludedir' is empty. If it is, they should not try to use
|
||
it; they should cancel the second installation of the header files.
|
||
|
||
A package should not replace an existing header in this directory
|
||
unless the header came from the same package. Thus, if your Foo
|
||
package provides a header file `foo.h', then it should install the
|
||
header file in the `oldincludedir' directory if either (1) there
|
||
is no `foo.h' there or (2) the `foo.h' that exists came from the
|
||
Foo package.
|
||
|
||
To tell whether `foo.h' came from the Foo package, put a magic
|
||
string in the file--part of a comment--and `grep' for that string.
|
||
|
||
Unix-style man pages are installed in one of the following:
|
||
|
||
`mandir'
|
||
The top-level directory for installing the man pages (if any) for
|
||
this package. It will normally be `/usr/local/man', but you should
|
||
write it as `$(prefix)/man'. (If you are using Autoconf, write it
|
||
as `@mandir@'.)
|
||
|
||
`man1dir'
|
||
The directory for installing section 1 man pages. Write it as
|
||
`$(mandir)/man1'.
|
||
|
||
`man2dir'
|
||
The directory for installing section 2 man pages. Write it as
|
||
`$(mandir)/man2'
|
||
|
||
`...'
|
||
*Don't make the primary documentation for any GNU software be a
|
||
man page. Write a manual in Texinfo instead. Man pages are just
|
||
for the sake of people running GNU software on Unix, which is a
|
||
secondary application only.*
|
||
|
||
`manext'
|
||
The file name extension for the installed man page. This should
|
||
contain a period followed by the appropriate digit; it should
|
||
normally be `.1'.
|
||
|
||
`man1ext'
|
||
The file name extension for installed section 1 man pages.
|
||
|
||
`man2ext'
|
||
The file name extension for installed section 2 man pages.
|
||
|
||
`...'
|
||
Use these names instead of `manext' if the package needs to
|
||
install man pages in more than one section of the manual.
|
||
|
||
And finally, you should set the following variable:
|
||
|
||
`srcdir'
|
||
The directory for the sources being compiled. The value of this
|
||
variable is normally inserted by the `configure' shell script.
|
||
(If you are using Autconf, use `srcdir = @srcdir@'.)
|
||
|
||
For example:
|
||
|
||
# Common prefix for installation directories.
|
||
# NOTE: This directory must exist when you start the install.
|
||
prefix = /usr/local
|
||
exec_prefix = $(prefix)
|
||
# Where to put the executable for the command `gcc'.
|
||
bindir = $(exec_prefix)/bin
|
||
# Where to put the directories used by the compiler.
|
||
libexecdir = $(exec_prefix)/libexec
|
||
# Where to put the Info files.
|
||
infodir = $(prefix)/info
|
||
|
||
If your program installs a large number of files into one of the
|
||
standard user-specified directories, it might be useful to group them
|
||
into a subdirectory particular to that program. If you do this, you
|
||
should write the `install' rule to create these subdirectories.
|
||
|
||
Do not expect the user to include the subdirectory name in the value
|
||
of any of the variables listed above. The idea of having a uniform set
|
||
of variable names for installation directories is to enable the user to
|
||
specify the exact same values for several different GNU packages. In
|
||
order for this to be useful, all the packages must be designed so that
|
||
they will work sensibly when the user does so.
|
||
|
||
|
||
File: standards.info, Node: Standard Targets, Next: Install Command Categories, Prev: Directory Variables, Up: Makefile Conventions
|
||
|
||
Standard Targets for Users
|
||
--------------------------
|
||
|
||
All GNU programs should have the following targets in their
|
||
Makefiles:
|
||
|
||
`all'
|
||
Compile the entire program. This should be the default target.
|
||
This target need not rebuild any documentation files; Info files
|
||
should normally be included in the distribution, and DVI files
|
||
should be made only when explicitly asked for.
|
||
|
||
By default, the Make rules should compile and link with `-g', so
|
||
that executable programs have debugging symbols. Users who don't
|
||
mind being helpless can strip the executables later if they wish.
|
||
|
||
`install'
|
||
Compile the program and copy the executables, libraries, and so on
|
||
to the file names where they should reside for actual use. If
|
||
there is a simple test to verify that a program is properly
|
||
installed, this target should run that test.
|
||
|
||
Do not strip executables when installing them. Devil-may-care
|
||
users can use the `install-strip' target to do that.
|
||
|
||
If possible, write the `install' target rule so that it does not
|
||
modify anything in the directory where the program was built,
|
||
provided `make all' has just been done. This is convenient for
|
||
building the program under one user name and installing it under
|
||
another.
|
||
|
||
The commands should create all the directories in which files are
|
||
to be installed, if they don't already exist. This includes the
|
||
directories specified as the values of the variables `prefix' and
|
||
`exec_prefix', as well as all subdirectories that are needed. One
|
||
way to do this is by means of an `installdirs' target as described
|
||
below.
|
||
|
||
Use `-' before any command for installing a man page, so that
|
||
`make' will ignore any errors. This is in case there are systems
|
||
that don't have the Unix man page documentation system installed.
|
||
|
||
The way to install Info files is to copy them into `$(infodir)'
|
||
with `$(INSTALL_DATA)' (*note Command Variables::.), and then run
|
||
the `install-info' program if it is present. `install-info' is a
|
||
program that edits the Info `dir' file to add or update the menu
|
||
entry for the given Info file; it is part of the Texinfo package.
|
||
Here is a sample rule to install an Info file:
|
||
|
||
$(infodir)/foo.info: foo.info
|
||
$(POST_INSTALL)
|
||
# There may be a newer info file in . than in srcdir.
|
||
-if test -f foo.info; then d=.; \
|
||
else d=$(srcdir); fi; \
|
||
$(INSTALL_DATA) $$d/foo.info $@; \
|
||
# Run install-info only if it exists.
|
||
# Use `if' instead of just prepending `-' to the
|
||
# line so we notice real errors from install-info.
|
||
# We use `$(SHELL) -c' because some shells do not
|
||
# fail gracefully when there is an unknown command.
|
||
if $(SHELL) -c 'install-info --version' \
|
||
>/dev/null 2>&1; then \
|
||
install-info --dir-file=$(infodir)/dir \
|
||
$(infodir)/foo.info; \
|
||
else true; fi
|
||
|
||
When writing the `install' target, you must classify all the
|
||
commands into three categories: normal ones, "pre-installation"
|
||
commands and "post-installation" commands. *Note Install Command
|
||
Categories::.
|
||
|
||
`uninstall'
|
||
Delete all the installed files--the copies that the `install'
|
||
target creates.
|
||
|
||
This rule should not modify the directories where compilation is
|
||
done, only the directories where files are installed.
|
||
|
||
The uninstallation commands are divided into three categories,
|
||
just like the installation commands. *Note Install Command
|
||
Categories::.
|
||
|
||
`install-strip'
|
||
Like `install', but strip the executable files while installing
|
||
them. In many cases, the definition of this target can be very
|
||
simple:
|
||
|
||
install-strip:
|
||
$(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \
|
||
install
|
||
|
||
Normally we do not recommend stripping an executable unless you
|
||
are sure the program has no bugs. However, it can be reasonable
|
||
to install a stripped executable for actual execution while saving
|
||
the unstripped executable elsewhere in case there is a bug.
|
||
|
||
`clean'
|
||
Delete all files from the current directory that are normally
|
||
created by building the program. Don't delete the files that
|
||
record the configuration. Also preserve files that could be made
|
||
by building, but normally aren't because the distribution comes
|
||
with them.
|
||
|
||
Delete `.dvi' files here if they are not part of the distribution.
|
||
|
||
`distclean'
|
||
Delete all files from the current directory that are created by
|
||
configuring or building the program. If you have unpacked the
|
||
source and built the program without creating any other files,
|
||
`make distclean' should leave only the files that were in the
|
||
distribution.
|
||
|
||
`mostlyclean'
|
||
Like `clean', but may refrain from deleting a few files that people
|
||
normally don't want to recompile. For example, the `mostlyclean'
|
||
target for GCC does not delete `libgcc.a', because recompiling it
|
||
is rarely necessary and takes a lot of time.
|
||
|
||
`maintainer-clean'
|
||
Delete almost everything from the current directory that can be
|
||
reconstructed with this Makefile. This typically includes
|
||
everything deleted by `distclean', plus more: C source files
|
||
produced by Bison, tags tables, Info files, and so on.
|
||
|
||
The reason we say "almost everything" is that running the command
|
||
`make maintainer-clean' should not delete `configure' even if
|
||
`configure' can be remade using a rule in the Makefile. More
|
||
generally, `make maintainer-clean' should not delete anything that
|
||
needs to exist in order to run `configure' and then begin to build
|
||
the program. This is the only exception; `maintainer-clean' should
|
||
delete everything else that can be rebuilt.
|
||
|
||
The `maintainer-clean' target is intended to be used by a
|
||
maintainer of the package, not by ordinary users. You may need
|
||
special tools to reconstruct some of the files that `make
|
||
maintainer-clean' deletes. Since these files are normally
|
||
included in the distribution, we don't take care to make them easy
|
||
to reconstruct. If you find you need to unpack the full
|
||
distribution again, don't blame us.
|
||
|
||
To help make users aware of this, the commands for the special
|
||
`maintainer-clean' target should start with these two:
|
||
|
||
@echo 'This command is intended for maintainers to use; it'
|
||
@echo 'deletes files that may need special tools to rebuild.'
|
||
|
||
`TAGS'
|
||
Update a tags table for this program.
|
||
|
||
`info'
|
||
Generate any Info files needed. The best way to write the rules
|
||
is as follows:
|
||
|
||
info: foo.info
|
||
|
||
foo.info: foo.texi chap1.texi chap2.texi
|
||
$(MAKEINFO) $(srcdir)/foo.texi
|
||
|
||
You must define the variable `MAKEINFO' in the Makefile. It should
|
||
run the `makeinfo' program, which is part of the Texinfo
|
||
distribution.
|
||
|
||
Normally a GNU distribution comes with Info files, and that means
|
||
the Info files are present in the source directory. Therefore,
|
||
the Make rule for an info file should update it in the source
|
||
directory. When users build the package, ordinarily Make will not
|
||
update the Info files because they will already be up to date.
|
||
|
||
`dvi'
|
||
Generate DVI files for all Texinfo documentation. For example:
|
||
|
||
dvi: foo.dvi
|
||
|
||
foo.dvi: foo.texi chap1.texi chap2.texi
|
||
$(TEXI2DVI) $(srcdir)/foo.texi
|
||
|
||
You must define the variable `TEXI2DVI' in the Makefile. It should
|
||
run the program `texi2dvi', which is part of the Texinfo
|
||
distribution.(1) Alternatively, write just the dependencies, and
|
||
allow GNU `make' to provide the command.
|
||
|
||
`dist'
|
||
Create a distribution tar file for this program. The tar file
|
||
should be set up so that the file names in the tar file start with
|
||
a subdirectory name which is the name of the package it is a
|
||
distribution for. This name can include the version number.
|
||
|
||
For example, the distribution tar file of GCC version 1.40 unpacks
|
||
into a subdirectory named `gcc-1.40'.
|
||
|
||
The easiest way to do this is to create a subdirectory
|
||
appropriately named, use `ln' or `cp' to install the proper files
|
||
in it, and then `tar' that subdirectory.
|
||
|
||
Compress the tar file file with `gzip'. For example, the actual
|
||
distribution file for GCC version 1.40 is called `gcc-1.40.tar.gz'.
|
||
|
||
The `dist' target should explicitly depend on all non-source files
|
||
that are in the distribution, to make sure they are up to date in
|
||
the distribution. *Note Making Releases: Releases.
|
||
|
||
`check'
|
||
Perform self-tests (if any). The user must build the program
|
||
before running the tests, but need not install the program; you
|
||
should write the self-tests so that they work when the program is
|
||
built but not installed.
|
||
|
||
The following targets are suggested as conventional names, for
|
||
programs in which they are useful.
|
||
|
||
`installcheck'
|
||
Perform installation tests (if any). The user must build and
|
||
install the program before running the tests. You should not
|
||
assume that `$(bindir)' is in the search path.
|
||
|
||
`installdirs'
|
||
It's useful to add a target named `installdirs' to create the
|
||
directories where files are installed, and their parent
|
||
directories. There is a script called `mkinstalldirs' which is
|
||
convenient for this; you can find it in the Texinfo package. You
|
||
can use a rule like this:
|
||
|
||
# Make sure all installation directories (e.g. $(bindir))
|
||
# actually exist by making them if necessary.
|
||
installdirs: mkinstalldirs
|
||
$(srcdir)/mkinstalldirs $(bindir) $(datadir) \
|
||
$(libdir) $(infodir) \
|
||
$(mandir)
|
||
|
||
This rule should not modify the directories where compilation is
|
||
done. It should do nothing but create installation directories.
|
||
|
||
---------- Footnotes ----------
|
||
|
||
(1) `texi2dvi' uses TeX to do the real work of formatting. TeX is
|
||
not distributed with Texinfo.
|
||
|
||
|
||
File: standards.info, Node: Install Command Categories, Prev: Standard Targets, Up: Makefile Conventions
|
||
|
||
Install Command Categories
|
||
--------------------------
|
||
|
||
When writing the `install' target, you must classify all the
|
||
commands into three categories: normal ones, "pre-installation"
|
||
commands and "post-installation" commands.
|
||
|
||
Normal commands move files into their proper places, and set their
|
||
modes. They may not alter any files except the ones that come entirely
|
||
from the package they belong to.
|
||
|
||
Pre-installation and post-installation commands may alter other
|
||
files; in particular, they can edit global configuration files or data
|
||
bases.
|
||
|
||
Pre-installation commands are typically executed before the normal
|
||
commands, and post-installation commands are typically run after the
|
||
normal commands.
|
||
|
||
The most common use for a post-installation command is to run
|
||
`install-info'. This cannot be done with a normal command, since it
|
||
alters a file (the Info directory) which does not come entirely and
|
||
solely from the package being installed. It is a post-installation
|
||
command because it needs to be done after the normal command which
|
||
installs the package's Info files.
|
||
|
||
Most programs don't need any pre-installation commands, but we have
|
||
the feature just in case it is needed.
|
||
|
||
To classify the commands in the `install' rule into these three
|
||
categories, insert "category lines" among them. A category line
|
||
specifies the category for the commands that follow.
|
||
|
||
A category line consists of a tab and a reference to a special Make
|
||
variable, plus an optional comment at the end. There are three
|
||
variables you can use, one for each category; the variable name
|
||
specifies the category. Category lines are no-ops in ordinary execution
|
||
because these three Make variables are normally undefined (and you
|
||
*should not* define them in the makefile).
|
||
|
||
Here are the three possible category lines, each with a comment that
|
||
explains what it means:
|
||
|
||
$(PRE_INSTALL) # Pre-install commands follow.
|
||
$(POST_INSTALL) # Post-install commands follow.
|
||
$(NORMAL_INSTALL) # Normal commands follow.
|
||
|
||
If you don't use a category line at the beginning of the `install'
|
||
rule, all the commands are classified as normal until the first category
|
||
line. If you don't use any category lines, all the commands are
|
||
classified as normal.
|
||
|
||
These are the category lines for `uninstall':
|
||
|
||
$(PRE_UNINSTALL) # Pre-uninstall commands follow.
|
||
$(POST_UNINSTALL) # Post-uninstall commands follow.
|
||
$(NORMAL_UNINSTALL) # Normal commands follow.
|
||
|
||
Typically, a pre-uninstall command would be used for deleting entries
|
||
from the Info directory.
|
||
|
||
If the `install' or `uninstall' target has any dependencies which
|
||
act as subroutines of installation, then you should start *each*
|
||
dependency's commands with a category line, and start the main target's
|
||
commands with a category line also. This way, you can ensure that each
|
||
command is placed in the right category regardless of which of the
|
||
dependencies actually run.
|
||
|
||
Pre-installation and post-installation commands should not run any
|
||
programs except for these:
|
||
|
||
[ basename bash cat chgrp chmod chown cmp cp dd diff echo
|
||
egrep expand expr false fgrep find getopt grep gunzip gzip
|
||
hostname install install-info kill ldconfig ln ls md5sum
|
||
mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee
|
||
test touch true uname xargs yes
|
||
|
||
The reason for distinguishing the commands in this way is for the
|
||
sake of making binary packages. Typically a binary package contains
|
||
all the executables and other files that need to be installed, and has
|
||
its own method of installing them--so it does not need to run the normal
|
||
installation commands. But installing the binary package does need to
|
||
execute the pre-installation and post-installation commands.
|
||
|
||
Programs to build binary packages work by extracting the
|
||
pre-installation and post-installation commands. Here is one way of
|
||
extracting the pre-installation commands:
|
||
|
||
make -n install -o all \
|
||
PRE_INSTALL=pre-install \
|
||
POST_INSTALL=post-install \
|
||
NORMAL_INSTALL=normal-install \
|
||
| gawk -f pre-install.awk
|
||
|
||
where the file `pre-install.awk' could contain this:
|
||
|
||
$0 ~ /^\t[ \t]*(normal_install|post_install)[ \t]*$/ {on = 0}
|
||
on {print $0}
|
||
$0 ~ /^\t[ \t]*pre_install[ \t]*$/ {on = 1}
|
||
|
||
The resulting file of pre-installation commands is executed as a
|
||
shell script as part of installing the binary package.
|
||
|
||
|
||
File: standards.info, Node: Releases, Prev: Makefile Conventions, Up: Managing Releases
|
||
|
||
Making Releases
|
||
===============
|
||
|
||
Package the distribution of Foo version 69.96 in a gzipped tar file
|
||
named `foo-69.96.tar.gz'. It should unpack into a subdirectory named
|
||
`foo-69.96'.
|
||
|
||
Building and installing the program should never modify any of the
|
||
files contained in the distribution. This means that all the files
|
||
that form part of the program in any way must be classified into "source
|
||
files" and "non-source files". Source files are written by humans and
|
||
never changed automatically; non-source files are produced from source
|
||
files by programs under the control of the Makefile.
|
||
|
||
Naturally, all the source files must be in the distribution. It is
|
||
okay to include non-source files in the distribution, provided they are
|
||
up-to-date and machine-independent, so that building the distribution
|
||
normally will never modify them. We commonly include non-source files
|
||
produced by Bison, `lex', TeX, and `makeinfo'; this helps avoid
|
||
unnecessary dependencies between our distributions, so that users can
|
||
install whichever packages they want to install.
|
||
|
||
Non-source files that might actually be modified by building and
|
||
installing the program should *never* be included in the distribution.
|
||
So if you do distribute non-source files, always make sure they are up
|
||
to date when you make a new distribution.
|
||
|
||
Make sure that the directory into which the distribution unpacks (as
|
||
well as any subdirectories) are all world-writable (octal mode 777).
|
||
This is so that old versions of `tar' which preserve the ownership and
|
||
permissions of the files from the tar archive will be able to extract
|
||
all the files even if the user is unprivileged.
|
||
|
||
Make sure that all the files in the distribution are world-readable.
|
||
|
||
Make sure that no file name in the distribution is more than 14
|
||
characters long. Likewise, no file created by building the program
|
||
should have a name longer than 14 characters. The reason for this is
|
||
that some systems adhere to a foolish interpretation of the POSIX
|
||
standard, and refuse to open a longer name, rather than truncating as
|
||
they did in the past.
|
||
|
||
Don't include any symbolic links in the distribution itself. If the
|
||
tar file contains symbolic links, then people cannot even unpack it on
|
||
systems that don't support symbolic links. Also, don't use multiple
|
||
names for one file in different directories, because certain file
|
||
systems cannot handle this and that prevents unpacking the distribution.
|
||
|
||
Try to make sure that all the file names will be unique on MS-DOS. A
|
||
name on MS-DOS consists of up to 8 characters, optionally followed by a
|
||
period and up to three characters. MS-DOS will truncate extra
|
||
characters both before and after the period. Thus, `foobarhacker.c'
|
||
and `foobarhacker.o' are not ambiguous; they are truncated to
|
||
`foobarha.c' and `foobarha.o', which are distinct.
|
||
|
||
Include in your distribution a copy of the `texinfo.tex' you used to
|
||
test print any `*.texinfo' or `*.texi' files.
|
||
|
||
Likewise, if your program uses small GNU software packages like
|
||
regex, getopt, obstack, or termcap, include them in the distribution
|
||
file. Leaving them out would make the distribution file a little
|
||
smaller at the expense of possible inconvenience to a user who doesn't
|
||
know what other files to get.
|
||
|
||
|