File: make.info,  Node: Directory Variables,  Next: Standard Targets,  Prev: DESTDIR,  Up: Makefile Conventions

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.