make: Directory Variables
16.5 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 and the values they should have in GNU packages are described
below. They are based on a standard file system layout; variants of it
are used in GNU/Linux and other modern operating systems.
Installers are expected to override these values when calling 'make'
(e.g., 'make prefix=/usr install') or 'configure' (e.g., 'configure
--prefix=/usr'). GNU packages should not try to guess which value
should be appropriate for these variables on the system they are being
installed onto: use the default settings specified here so that all GNU
packages behave identically, allowing the installer to achieve any
desired layout.
All installation directories, and their parent directories, should be
created (if necessary) before they are installed into.
These first 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@'.)
Running 'make install' with a different value of 'prefix' from the
one used to build the program should _not_ recompile the program.
'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.
Running 'make install' with a different value of 'exec_prefix' from
the one used to build the program should _not_ recompile the
program.
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@'.)
The definition of 'libexecdir' is the same for all packages, so you
should install your data in a subdirectory thereof. Most packages
install their data under '$(libexecdir)/PACKAGE-NAME/', possibly
within additional subdirectories thereof, such as
'$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
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.
Here are the variables Makefiles should use to specify directories to
put these various kinds of files in:
'datarootdir'
The root of the directory tree for 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 '@datarootdir@'.) 'datadir''s default
value is based on this variable; so are 'infodir', 'mandir', and
others.
'datadir'
The directory for installing idiosyncratic read-only
architecture-independent data files for this program. This is
usually the same place as 'datarootdir', but we use the two
separate variables so that you can move these program-specific
files without altering the location for Info files, man pages, etc.
This should normally be '/usr/local/share', but write it as
'$(datarootdir)'. (If you are using Autoconf, write it as
'@datadir@'.)
The definition of 'datadir' is the same for all packages, so you
should install your data in a subdirectory thereof. Most packages
install their data under '$(datadir)/PACKAGE-NAME/'.
'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 here 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@'.)
'runstatedir'
The directory for installing data files which the programs modify
while they run, that pertain to one specific machine, and which
need not persist longer than the execution of the program--which is
generally long-lived, for example, until the next reboot. PID
files for system daemons are a typical use. In addition, this
directory should not be cleaned except perhaps at reboot, while the
general '/tmp' ('TMPDIR') may be cleaned arbitrarily. This should
normally be '/var/run', but write it as '$(localstatedir)/run'.
Having it as a separate variable allows the use of '/run' if
desired, for example. (If you are using Autoconf 2.70 or later,
write it as '@runstatedir@'.)
These variables specify the directory for installing certain specific
types of files, if your program has them. Every GNU package should have
Info files, so every program needs 'infodir', but not all need 'libdir'
or '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
directory '/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.
'docdir'
The directory for installing documentation files (other than Info)
for this package. By default, it should be
'/usr/local/share/doc/YOURPKG', but it should be written as
'$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write it
as '@docdir@'.) The YOURPKG subdirectory, which may include a
version number, prevents collisions among files with common names,
such as 'README'.
'infodir'
The directory for installing the Info files for this package. By
default, it should be '/usr/local/share/info', but it should be
written as '$(datarootdir)/info'. (If you are using Autoconf,
write it as '@infodir@'.) 'infodir' is separate from 'docdir' for
compatibility with existing practice.
'htmldir'
'dvidir'
'pdfdir'
'psdir'
Directories for installing documentation files in the particular
format. They should all be set to '$(docdir)' by default. (If you
are using Autoconf, write them as '@htmldir@', '@dvidir@', etc.)
Packages which supply several translations of their documentation
should install them in '$(htmldir)/'LL, '$(pdfdir)/'LL, etc. where
LL is a locale abbreviation such as 'en' or 'pt_BR'.
'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@'.)
'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 '$(datarootdir)/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.ac' file:
lispdir='${datarootdir}/emacs/site-lisp'
AC_SUBST(lispdir)
'localedir'
The directory for installing locale-specific message catalogs for
this package. By default, it should be '/usr/local/share/locale',
but it should be written as '$(datarootdir)/locale'. (If you are
using Autoconf, write it as '@localedir@'.) This directory usually
has a subdirectory per locale.
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/share/man', but you
should write it as '$(datarootdir)/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 Autoconf, use 'srcdir = @srcdir@'.)
For example:
# Common prefix for installation directories.
# NOTE: This directory must exist when you start the install.
prefix = /usr/local
datarootdir = $(prefix)/share
datadir = $(datarootdir)
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 = $(datarootdir)/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.
At times, not all of these variables may be implemented in the
current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
believe all of them are. When any are missing, the descriptions here
serve as specifications for what Autoconf will implement. As a
programmer, you can either use a development version of Autoconf or
avoid using these variables until a stable release is made which
supports them.