[linux-2.6-block.git] / Documentation / kbuild / headers_install.rst

=============================================
Exporting kernel headers for use by userspace
=============================================

The "make headers_install" command exports the kernel's header files in a
form suitable for use by userspace programs.

The linux kernel's exported header files describe the API for user space
programs attempting to use kernel services.  These kernel header files are
used by the system's C library (such as glibc or uClibc) to define available
system calls, as well as constants and structures to be used with these
system calls.  The C library's header files include the kernel header files
from the "linux" subdirectory.  The system's libc headers are usually
installed at the default location /usr/include and the kernel headers in
subdirectories under that (most notably /usr/include/linux and
/usr/include/asm).

Kernel headers are backwards compatible, but not forwards compatible.  This
means that a program built against a C library using older kernel headers
should run on a newer kernel (although it may not have access to new
features), but a program built against newer kernel headers may not work on an
older kernel.

The "make headers_install" command can be run in the top level directory of the
kernel source code (or using a standard out-of-tree build).  It takes two
optional arguments::

  make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr

ARCH indicates which architecture to produce headers for, and defaults to the
current architecture.  The linux/asm directory of the exported kernel headers
is platform-specific, to see a complete list of supported architectures use
the command::

  ls -d include/asm-* | sed 's/.*-//'

INSTALL_HDR_PATH indicates where to install the headers. It defaults to
"./usr".

An 'include' directory is automatically created inside INSTALL_HDR_PATH and
headers are installed in 'INSTALL_HDR_PATH/include'.

The kernel header export infrastructure is maintained by David Woodhouse
<dwmw2@infradead.org>.
Commit	Line	Data
cd238eff	1	=============================================
451ad114 RL	2	Exporting kernel headers for use by userspace
	3	=============================================
	4
	5	The "make headers_install" command exports the kernel's header files in a
	6	form suitable for use by userspace programs.
	7
	8	The linux kernel's exported header files describe the API for user space
	9	programs attempting to use kernel services. These kernel header files are
	10	used by the system's C library (such as glibc or uClibc) to define available
	11	system calls, as well as constants and structures to be used with these
	12	system calls. The C library's header files include the kernel header files
	13	from the "linux" subdirectory. The system's libc headers are usually
	14	installed at the default location /usr/include and the kernel headers in
	15	subdirectories under that (most notably /usr/include/linux and
	16	/usr/include/asm).
	17
	18	Kernel headers are backwards compatible, but not forwards compatible. This
	19	means that a program built against a C library using older kernel headers
	20	should run on a newer kernel (although it may not have access to new
	21	features), but a program built against newer kernel headers may not work on an
	22	older kernel.
	23
	24	The "make headers_install" command can be run in the top level directory of the
	25	kernel source code (or using a standard out-of-tree build). It takes two
cd238eff	26	optional arguments::
451ad114	27
ed45d403	28	make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr
451ad114 RL	29
	30	ARCH indicates which architecture to produce headers for, and defaults to the
	31	current architecture. The linux/asm directory of the exported kernel headers
	32	is platform-specific, to see a complete list of supported architectures use
cd238eff	33	the command::
451ad114 RL	34
	35	ls -d include/asm-* \| sed 's/.*-//'
	36
ed45d403 AB	37	INSTALL_HDR_PATH indicates where to install the headers. It defaults to
	38	"./usr".
	39
	40	An 'include' directory is automatically created inside INSTALL_HDR_PATH and
	41	headers are installed in 'INSTALL_HDR_PATH/include'.
451ad114	42
451ad114 RL	43	The kernel header export infrastructure is maintained by David Woodhouse
451ad114 RL	44	<dwmw2@infradead.org>.