standards: Directory Variables
1
1 7.2.5 Variables for Installation Directories
1 --------------------------------------------
1
1 Installation directories should always be named by variables, so it is
1 easy to install in a nonstandard place. The standard names for these
1 variables and the values they should have in GNU packages are described
1 below. They are based on a standard file system layout; variants of it
1 are used in GNU/Linux and other modern operating systems.
1
1 Installers are expected to override these values when calling 'make'
1 (e.g., 'make prefix=/usr install') or 'configure' (e.g., 'configure
1 --prefix=/usr'). GNU packages should not try to guess which value
1 should be appropriate for these variables on the system they are being
1 installed onto: use the default settings specified here so that all GNU
1 packages behave identically, allowing the installer to achieve any
1 desired layout.
1
1 All installation directories, and their parent directories, should be
1 created (if necessary) before they are installed into.
1
1 These first two variables set the root for the installation. All the
1 other installation directories should be subdirectories of one of these
1 two, and nothing should be directly installed into these two
1 directories.
1
1 'prefix'
1 A prefix used in constructing the default values of the variables
1 listed below. The default value of 'prefix' should be
1 '/usr/local'. When building the complete GNU system, the prefix
1 will be empty and '/usr' will be a symbolic link to '/'. (If you
1 are using Autoconf, write it as '@prefix@'.)
1
1 Running 'make install' with a different value of 'prefix' from the
1 one used to build the program should _not_ recompile the program.
1
1 'exec_prefix'
1 A prefix used in constructing the default values of some of the
1 variables listed below. The default value of 'exec_prefix' should
1 be '$(prefix)'. (If you are using Autoconf, write it as
1 '@exec_prefix@'.)
1
1 Generally, '$(exec_prefix)' is used for directories that contain
1 machine-specific files (such as executables and subroutine
1 libraries), while '$(prefix)' is used directly for other
1 directories.
1
1 Running 'make install' with a different value of 'exec_prefix' from
1 the one used to build the program should _not_ recompile the
1 program.
1
1 Executable programs are installed in one of the following
1 directories.
1
1 'bindir'
1 The directory for installing executable programs that users can
1 run. This should normally be '/usr/local/bin', but write it as
1 '$(exec_prefix)/bin'. (If you are using Autoconf, write it as
1 '@bindir@'.)
1
1 'sbindir'
1 The directory for installing executable programs that can be run
1 from the shell, but are only generally useful to system
1 administrators. This should normally be '/usr/local/sbin', but
1 write it as '$(exec_prefix)/sbin'. (If you are using Autoconf,
1 write it as '@sbindir@'.)
1
1 'libexecdir'
1 The directory for installing executable programs to be run by other
1 programs rather than by users. This directory should normally be
1 '/usr/local/libexec', but write it as '$(exec_prefix)/libexec'.
1 (If you are using Autoconf, write it as '@libexecdir@'.)
1
1 The definition of 'libexecdir' is the same for all packages, so you
1 should install your data in a subdirectory thereof. Most packages
1 install their data under '$(libexecdir)/PACKAGE-NAME/', possibly
1 within additional subdirectories thereof, such as
1 '$(libexecdir)/PACKAGE-NAME/MACHINE/VERSION'.
1
1 Data files used by the program during its execution are divided into
1 categories in two ways.
1
1 * Some files are normally modified by programs; others are never
1 normally modified (though users may edit some of these).
1
1 * Some files are architecture-independent and can be shared by all
1 machines at a site; some are architecture-dependent and can be
1 shared only by machines of the same kind and operating system;
1 others may never be shared between two machines.
1
1 This makes for six different possibilities. However, we want to
1 discourage the use of architecture-dependent files, aside from object
1 files and libraries. It is much cleaner to make other data files
1 architecture-independent, and it is generally not hard.
1
1 Here are the variables Makefiles should use to specify directories to
1 put these various kinds of files in:
1
1 'datarootdir'
1 The root of the directory tree for read-only
1 architecture-independent data files. This should normally be
1 '/usr/local/share', but write it as '$(prefix)/share'. (If you are
1 using Autoconf, write it as '@datarootdir@'.) 'datadir''s default
1 value is based on this variable; so are 'infodir', 'mandir', and
1 others.
1
1 'datadir'
1 The directory for installing idiosyncratic read-only
1 architecture-independent data files for this program. This is
1 usually the same place as 'datarootdir', but we use the two
1 separate variables so that you can move these program-specific
1 files without altering the location for Info files, man pages, etc.
1
1 This should normally be '/usr/local/share', but write it as
1 '$(datarootdir)'. (If you are using Autoconf, write it as
1 '@datadir@'.)
1
1 The definition of 'datadir' is the same for all packages, so you
1 should install your data in a subdirectory thereof. Most packages
1 install their data under '$(datadir)/PACKAGE-NAME/'.
1
1 'sysconfdir'
1 The directory for installing read-only data files that pertain to a
1 single machine-that is to say, files for configuring a host.
1 Mailer and network configuration files, '/etc/passwd', and so forth
1 belong here. All the files in this directory should be ordinary
1 ASCII text files. This directory should normally be
1 '/usr/local/etc', but write it as '$(prefix)/etc'. (If you are
1 using Autoconf, write it as '@sysconfdir@'.)
1
1 Do not install executables here in this directory (they probably
1 belong in '$(libexecdir)' or '$(sbindir)'). Also do not install
1 files that are modified in the normal course of their use (programs
1 whose purpose is to change the configuration of the system
1 excluded). Those probably belong in '$(localstatedir)'.
1
1 'sharedstatedir'
1 The directory for installing architecture-independent data files
1 which the programs modify while they run. This should normally be
1 '/usr/local/com', but write it as '$(prefix)/com'. (If you are
1 using Autoconf, write it as '@sharedstatedir@'.)
1
1 'localstatedir'
1 The directory for installing data files which the programs modify
1 while they run, and that pertain to one specific machine. Users
1 should never need to modify files in this directory to configure
1 the package's operation; put such configuration information in
1 separate files that go in '$(datadir)' or '$(sysconfdir)'.
1 '$(localstatedir)' should normally be '/usr/local/var', but write
1 it as '$(prefix)/var'. (If you are using Autoconf, write it as
1 '@localstatedir@'.)
1
1 'runstatedir'
1 The directory for installing data files which the programs modify
1 while they run, that pertain to one specific machine, and which
1 need not persist longer than the execution of the program--which is
1 generally long-lived, for example, until the next reboot. PID
1 files for system daemons are a typical use. In addition, this
1 directory should not be cleaned except perhaps at reboot, while the
1 general '/tmp' ('TMPDIR') may be cleaned arbitrarily. This should
1 normally be '/var/run', but write it as '$(localstatedir)/run'.
1 Having it as a separate variable allows the use of '/run' if
1 desired, for example. (If you are using Autoconf 2.70 or later,
1 write it as '@runstatedir@'.)
1
1 These variables specify the directory for installing certain specific
1 types of files, if your program has them. Every GNU package should have
1 Info files, so every program needs 'infodir', but not all need 'libdir'
1 or 'lispdir'.
1
1 'includedir'
1 The directory for installing header files to be included by user
1 programs with the C '#include' preprocessor directive. This should
1 normally be '/usr/local/include', but write it as
1 '$(prefix)/include'. (If you are using Autoconf, write it as
1 '@includedir@'.)
1
1 Most compilers other than GCC do not look for header files in
1 directory '/usr/local/include'. So installing the header files
1 this way is only useful with GCC. Sometimes this is not a problem
1 because some libraries are only really intended to work with GCC.
1 But some libraries are intended to work with other compilers. They
1 should install their header files in two places, one specified by
1 'includedir' and one specified by 'oldincludedir'.
1
1 'oldincludedir'
1 The directory for installing '#include' header files for use with
1 compilers other than GCC. This should normally be '/usr/include'.
1 (If you are using Autoconf, you can write it as '@oldincludedir@'.)
1
1 The Makefile commands should check whether the value of
1 'oldincludedir' is empty. If it is, they should not try to use it;
1 they should cancel the second installation of the header files.
1
1 A package should not replace an existing header in this directory
1 unless the header came from the same package. Thus, if your Foo
1 package provides a header file 'foo.h', then it should install the
1 header file in the 'oldincludedir' directory if either (1) there is
1 no 'foo.h' there or (2) the 'foo.h' that exists came from the Foo
1 package.
1
1 To tell whether 'foo.h' came from the Foo package, put a magic
1 string in the file--part of a comment--and 'grep' for that string.
1
1 'docdir'
1 The directory for installing documentation files (other than Info)
1 for this package. By default, it should be
1 '/usr/local/share/doc/YOURPKG', but it should be written as
1 '$(datarootdir)/doc/YOURPKG'. (If you are using Autoconf, write it
1 as '@docdir@'.) The YOURPKG subdirectory, which may include a
1 version number, prevents collisions among files with common names,
1 such as 'README'.
1
1 'infodir'
1 The directory for installing the Info files for this package. By
1 default, it should be '/usr/local/share/info', but it should be
1 written as '$(datarootdir)/info'. (If you are using Autoconf,
1 write it as '@infodir@'.) 'infodir' is separate from 'docdir' for
1 compatibility with existing practice.
1
1 'htmldir'
1 'dvidir'
1 'pdfdir'
1 'psdir'
1 Directories for installing documentation files in the particular
1 format. They should all be set to '$(docdir)' by default. (If you
1 are using Autoconf, write them as '@htmldir@', '@dvidir@', etc.)
1 Packages which supply several translations of their documentation
1 should install them in '$(htmldir)/'LL, '$(pdfdir)/'LL, etc. where
1 LL is a locale abbreviation such as 'en' or 'pt_BR'.
1
1 'libdir'
1 The directory for object files and libraries of object code. Do
1 not install executables here, they probably ought to go in
1 '$(libexecdir)' instead. The value of 'libdir' should normally be
1 '/usr/local/lib', but write it as '$(exec_prefix)/lib'. (If you
1 are using Autoconf, write it as '@libdir@'.)
1
1 'lispdir'
1 The directory for installing any Emacs Lisp files in this package.
1 By default, it should be '/usr/local/share/emacs/site-lisp', but it
1 should be written as '$(datarootdir)/emacs/site-lisp'.
1
1 If you are using Autoconf, write the default as '@lispdir@'. In
1 order to make '@lispdir@' work, you need the following lines in
1 your 'configure.ac' file:
1
1 lispdir='${datarootdir}/emacs/site-lisp'
1 AC_SUBST(lispdir)
1
1 'localedir'
1 The directory for installing locale-specific message catalogs for
1 this package. By default, it should be '/usr/local/share/locale',
1 but it should be written as '$(datarootdir)/locale'. (If you are
1 using Autoconf, write it as '@localedir@'.) This directory usually
1 has a subdirectory per locale.
1
1 Unix-style man pages are installed in one of the following:
1
1 'mandir'
1 The top-level directory for installing the man pages (if any) for
1 this package. It will normally be '/usr/local/share/man', but you
1 should write it as '$(datarootdir)/man'. (If you are using
1 Autoconf, write it as '@mandir@'.)
1
1 'man1dir'
1 The directory for installing section 1 man pages. Write it as
1 '$(mandir)/man1'.
1 'man2dir'
1 The directory for installing section 2 man pages. Write it as
1 '$(mandir)/man2'
1 '...'
1
1 *Don't make the primary documentation for any GNU software be a man
1 page. Write a manual in Texinfo instead. Man pages are just for
1 the sake of people running GNU software on Unix, which is a
1 secondary application only.*
1
1 'manext'
1 The file name extension for the installed man page. This should
1 contain a period followed by the appropriate digit; it should
1 normally be '.1'.
1
1 'man1ext'
1 The file name extension for installed section 1 man pages.
1 'man2ext'
1 The file name extension for installed section 2 man pages.
1 '...'
1 Use these names instead of 'manext' if the package needs to install
1 man pages in more than one section of the manual.
1
1 And finally, you should set the following variable:
1
1 'srcdir'
1 The directory for the sources being compiled. The value of this
1 variable is normally inserted by the 'configure' shell script. (If
1 you are using Autoconf, use 'srcdir = @srcdir@'.)
1
1 For example:
1
1 # Common prefix for installation directories.
1 # NOTE: This directory must exist when you start the install.
1 prefix = /usr/local
1 datarootdir = $(prefix)/share
1 datadir = $(datarootdir)
1 exec_prefix = $(prefix)
1 # Where to put the executable for the command 'gcc'.
1 bindir = $(exec_prefix)/bin
1 # Where to put the directories used by the compiler.
1 libexecdir = $(exec_prefix)/libexec
1 # Where to put the Info files.
1 infodir = $(datarootdir)/info
1
1 If your program installs a large number of files into one of the
1 standard user-specified directories, it might be useful to group them
1 into a subdirectory particular to that program. If you do this, you
1 should write the 'install' rule to create these subdirectories.
1
1 Do not expect the user to include the subdirectory name in the value
1 of any of the variables listed above. The idea of having a uniform set
1 of variable names for installation directories is to enable the user to
1 specify the exact same values for several different GNU packages. In
1 order for this to be useful, all the packages must be designed so that
1 they will work sensibly when the user does so.
1
1 At times, not all of these variables may be implemented in the
1 current release of Autoconf and/or Automake; but as of Autoconf 2.60, we
1 believe all of them are. When any are missing, the descriptions here
1 serve as specifications for what Autoconf will implement. As a
1 programmer, you can either use a development version of Autoconf or
1 avoid using these variables until a stable release is made which
1 supports them.
1