[PATCH] Documentation/make/headers_install.txt

[PATCH] Documentation/make/headers_install.txt

[Rob Landley]

From: Rob Landley <rob@landley.net>

Signed-off-by: Rob Landley <rob@landley.net>

Some documentation for "make headers_install".

---

Earlier discussion was at http://lkml.org/lkml/2007/6/22/7 and I
believe I've responded to all of David's comments.

--- /dev/null	2007-04-23 10:59:00.000000000 -0500
+++ linux-2.6/Documentation/make/headers_install.txt	2007-08-04 13:04:51.000000000 -0500
@@ -0,0 +1,46 @@
+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/include
+
+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/include".
+
+The command "make headers_install_all" exports headers for all architectures
+simultaneously.  (This is mostly of interest to distribution maintainers,
+who create an architecture-independent tarball from the resulting include
+directory.)  Remember to provide the appropriate linux/asm directory via "mv"
+or "ln -s" before building a C library with headers exported this way.
+
+The kernel header export infrastructure is maintained by David Woodhouse
+<dwmw2@infradead.org>.


-- 
"One of my most productive days was throwing away 1000 lines of code."
  - Ken Thompson.

Re: [PATCH] Documentation/make/headers_install.txt

[Jesper Juhl]

On 04/08/07, Rob Landley <rob@landley.net> wrote:
> From: Rob Landley <rob@landley.net>
>
> Signed-off-by: Rob Landley <rob@landley.net>
>
> Some documentation for "make headers_install".
>
> ---
>
> Earlier discussion was at http://lkml.org/lkml/2007/6/22/7 and I
> believe I've responded to all of David's comments.
>
> --- /dev/null   2007-04-23 10:59:00.000000000 -0500
> +++ linux-2.6/Documentation/make/headers_install.txt    2007-08-04 13:04:51.000000000 -0500
> @@ -0,0 +1,46 @@
> +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

Perhaps change the text "are backwards compatible" into "try very hard
to be backwards compatible" ... ?

> +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/include
> +
> +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:

how about s/"the command"/"the following command from inside a kernel
source tree"/ ?

> +
> +  ls -d include/asm-* | sed 's/.*-//'
> +
> +INSTALL_HDR_PATH indicates where to install the headers.  It defaults to
> +"./usr/include".
> +
> +The command "make headers_install_all" exports headers for all architectures
> +simultaneously.  (This is mostly of interest to distribution maintainers,
> +who create an architecture-independent tarball from the resulting include
> +directory.)  Remember to provide the appropriate linux/asm directory via "mv"
> +or "ln -s" before building a C library with headers exported this way.
> +
> +The kernel header export infrastructure is maintained by David Woodhouse
> +<dwmw2@infradead.org>.
>

Overall, looks good.

Acked by: Jesper Juhl <jesper.juhl@gmail.com>


-- 
Jesper Juhl <jesper.juhl@gmail.com>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

Re: [PATCH] Documentation/make/headers_install.txt

[Sam Ravnborg]

On Sat, Aug 04, 2007 at 02:07:18PM -0400, Rob Landley wrote:
> From: Rob Landley <rob@landley.net>
> 
> Signed-off-by: Rob Landley <rob@landley.net>
> 
> Some documentation for "make headers_install".
> 
> ---
> 
> Earlier discussion was at http://lkml.org/lkml/2007/6/22/7 and I
> believe I've responded to all of David's comments.
> 
> --- /dev/null	2007-04-23 10:59:00.000000000 -0500
> +++ linux-2.6/Documentation/make/headers_install.txt	2007-08-04 13:04:51.000000000 -0500

Any specific reason not to include this in Documentation/kbuild?
I would prefer to have all kernel build stuff in one directory and
we have Documentation/kbuild now.

	Sam

Re: [PATCH] Documentation/make/headers_install.txt

[Rob Landley]

On Saturday 04 August 2007 3:05:25 pm Sam Ravnborg wrote:
> On Sat, Aug 04, 2007 at 02:07:18PM -0400, Rob Landley wrote:
> > From: Rob Landley <rob@landley.net>
> >
> > Signed-off-by: Rob Landley <rob@landley.net>
> >
> > Some documentation for "make headers_install".
> >
> > ---
> >
> > Earlier discussion was at http://lkml.org/lkml/2007/6/22/7 and I
> > believe I've responded to all of David's comments.
> >
> > --- /dev/null	2007-04-23 10:59:00.000000000 -0500
> > +++ linux-2.6/Documentation/make/headers_install.txt	2007-08-04
> > 13:04:51.000000000 -0500
>
> Any specific reason not to include this in Documentation/kbuild?
> I would prefer to have all kernel build stuff in one directory and
> we have Documentation/kbuild now.

That directory contains internal implementation details of the kernel 
makefiles, and is not about how to use them if you don't plan to modify them.  
This document is about how people can use one of the commands listed in "make 
help", and is not about modifying the make files.  It's a different category 
of documentation.  (Ideally, kbuild would go under make.)

That said, I don't really care where it goes, so if you prefer kbuild I can 
drop it there.  The organization of Documentation/ is fairly irrelevant to me 
at this point.

Like most documentation, this file needs to be linked to from more than one 
place: it needs to be brought to the attention of people building their own 
linux-from-scratch style systems (the "what's in a linux root filesystem" 
section of the index I'm building), it should be linked from a "building the 
kernel" page (what kinds of output can the build produce), there should be 
a "make help" page with hotlinks to the individual commands (like this and 
menuconfig) that have more extensive documentation, etc.

Trying to do that in Documentation would be a pain.  (Lots of symlinks with no 
explanatory text?  Lots of files called "index.txt" in each directory 
reinventing Gopher, pointing you at a directory other than the one you're in 
and hoping nothing ever moves?)

> 	Sam

Rob
-- 
"One of my most productive days was throwing away 1000 lines of code."
  - Ken Thompson.