[PATCH] Documentation/make/headers_install.txt: update documentation

[PATCH] Documentation/make/headers_install.txt: update documentation

[Yann Droneaud]

Documentation in make/headers_install.txt is not
up to date regarding:
- way to list the various architectures;
- path where the headers are installed.

This patch try to fix these issues.

Cc: Kirill A. Shutemov <kirill@shutemov.name>
Cc: Michal Marek <mmarek@suse.cz>
Cc: David Woodhouse <dwmw2@infradead.org>
Cc: Rob Landley <rob@landley.net>
Cc: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>
---
 Documentation/make/headers_install.txt | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/make/headers_install.txt b/Documentation/make/headers_install.txt
index 951eb9f1e040..8b6751f10dd3 100644
--- a/Documentation/make/headers_install.txt
+++ b/Documentation/make/headers_install.txt
@@ -24,23 +24,24 @@ 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
+  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
+current architecture.  The asm/ directory of the exported kernel headers
+is platform-specific, to see a list of supported architectures use
 the command:
 
-  ls -d include/asm-* | sed 's/.*-//'
+  /bin/ls -1 arch/*/include/asm/Kbuild | sed -e 's,^arch/,,' \
+                                             -e 's,/include/asm/Kbuild$,,'
 
-INSTALL_HDR_PATH indicates where to install the headers.  It defaults to
-"./usr/include".
+INSTALL_HDR_PATH indicates where to create include/ directory to install the
+headers. It defaults to "./usr/".
 
 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.)  You also can use HDR_ARCH_LIST to specify list of architectures.
-Remember to provide the appropriate linux/asm directory via "mv" or "ln -s"
+Remember to provide the appropriate 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
-- 
1.9.3

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

[Michal Marek]

Dne 30.6.2014 21:11, Yann Droneaud napsal(a):
> Documentation in make/headers_install.txt is not
> up to date regarding:
> - way to list the various architectures;
> - path where the headers are installed.
> 
> This patch try to fix these issues.
> 
> Cc: Kirill A. Shutemov <kirill@shutemov.name>
> Cc: Michal Marek <mmarek@suse.cz>
> Cc: David Woodhouse <dwmw2@infradead.org>
> Cc: Rob Landley <rob@landley.net>
> Cc: Sam Ravnborg <sam@ravnborg.org>
> Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>
> ---
>  Documentation/make/headers_install.txt | 15 ++++++++-------

I have never noticed this file :). How about moving it to
Documentation/kbuild?


>  1 file changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/make/headers_install.txt b/Documentation/make/headers_install.txt
> index 951eb9f1e040..8b6751f10dd3 100644
> --- a/Documentation/make/headers_install.txt
> +++ b/Documentation/make/headers_install.txt
> @@ -24,23 +24,24 @@ 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
> +  make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr

ARCH=x86 maybe?


>  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
> +current architecture.  The asm/ directory of the exported kernel headers
> +is platform-specific, to see a list of supported architectures use
>  the command:
>  
> -  ls -d include/asm-* | sed 's/.*-//'
> +  /bin/ls -1 arch/*/include/asm/Kbuild | sed -e 's,^arch/,,' \
> +                                             -e 's,/include/asm/Kbuild$,,'

Or, more simply, 'ls arch/'.


> -INSTALL_HDR_PATH indicates where to install the headers.  It defaults to
> -"./usr/include".
> +INSTALL_HDR_PATH indicates where to create include/ directory to install the
> +headers. It defaults to "./usr/".
>  
>  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.)  You also can use HDR_ARCH_LIST to specify list of architectures.
> -Remember to provide the appropriate linux/asm directory via "mv" or "ln -s"
> +Remember to provide the appropriate 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
> 

Looks good,

Thanks,
Michal

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

[Sam Ravnborg]

On Thu, Jul 03, 2014 at 11:12:20PM +0200, Michal Marek wrote:
> Dne 30.6.2014 21:11, Yann Droneaud napsal(a):
> > Documentation in make/headers_install.txt is not
> > up to date regarding:
> > - way to list the various architectures;
> > - path where the headers are installed.
> > 
> > This patch try to fix these issues.
> > 
> > Cc: Kirill A. Shutemov <kirill@shutemov.name>
> > Cc: Michal Marek <mmarek@suse.cz>
> > Cc: David Woodhouse <dwmw2@infradead.org>
> > Cc: Rob Landley <rob@landley.net>
> > Cc: Sam Ravnborg <sam@ravnborg.org>
> > Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>
> > ---
> >  Documentation/make/headers_install.txt | 15 ++++++++-------
> 
> I have never noticed this file :). How about moving it to
> Documentation/kbuild?
Agree - please get this file moved.

	Sam

[PATCHv1 0/2] Documentation: move and update headers_install.txt

[Yann Droneaud]

On Wed, Jul 09, 2014 at 22:49 +0200, Sam Ravnborg wrote:
> On Thu, Jul 03, 2014 at 11:12:20PM +0200, Michal Marek wrote:
> > I have never noticed this file :). How about moving it to
> > Documentation/kbuild?
> Agree - please get this file moved.
> 

Please find a patchset to move and update headers_install.txt.

Regards.

Yann Droneaud (2):
  Documentation: headers_install.txt is part of kbuild
  Documentation/kbuild/headers_install.txt: update documentation

 Documentation/kbuild/00-INDEX                      |  2 ++
 Documentation/{make => kbuild}/headers_install.txt | 15 ++++++++-------
 2 files changed, 10 insertions(+), 7 deletions(-)
 rename Documentation/{make => kbuild}/headers_install.txt (78%)

-- 
1.9.3

[PATCHv1 1/2] Documentation: headers_install.txt is part of kbuild

[Yann Droneaud]

'headers_install.txt' from Documentation/make/ is related to Kbuild
so it must be moved in Documentation/kbuild/ directory.

As Documentation/make/ directory has only one file, it will be removed
as a consequence of moving 'headers_install.txt'.

Cc: Kirill A. Shutemov <kirill@shutemov.name>
Cc: Michal Marek <mmarek@suse.cz>
Cc: David Woodhouse <dwmw2@infradead.org>
Cc: Rob Landley <rob@landley.net>
Cc: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>
---
 Documentation/kbuild/00-INDEX                      | 2 ++
 Documentation/{make => kbuild}/headers_install.txt | 0
 2 files changed, 2 insertions(+)
 rename Documentation/{make => kbuild}/headers_install.txt (100%)

diff --git a/Documentation/kbuild/00-INDEX b/Documentation/kbuild/00-INDEX
index e8d2b6d83a3d..8c5e6aa78004 100644
--- a/Documentation/kbuild/00-INDEX
+++ b/Documentation/kbuild/00-INDEX
@@ -1,5 +1,7 @@
 00-INDEX
 	- this file: info on the kernel build process
+headers_install.txt
+	- how to export Linux headers for use by userspace
 kbuild.txt
 	- developer information on kbuild
 kconfig.txt
diff --git a/Documentation/make/headers_install.txt b/Documentation/kbuild/headers_install.txt
similarity index 100%
rename from Documentation/make/headers_install.txt
rename to Documentation/kbuild/headers_install.txt
-- 
1.9.3

Re: [PATCHv1 1/2] Documentation: headers_install.txt is part of kbuild

[Sam Ravnborg]

On Sun, Jul 13, 2014 at 12:15:29PM +0200, Yann Droneaud wrote:
> 'headers_install.txt' from Documentation/make/ is related to Kbuild
> so it must be moved in Documentation/kbuild/ directory.
> 
> As Documentation/make/ directory has only one file, it will be removed
> as a consequence of moving 'headers_install.txt'.
> 
> Cc: Kirill A. Shutemov <kirill@shutemov.name>
> Cc: Michal Marek <mmarek@suse.cz>
> Cc: David Woodhouse <dwmw2@infradead.org>
> Cc: Rob Landley <rob@landley.net>
> Cc: Sam Ravnborg <sam@ravnborg.org>
> Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>

This is much better - thanks.
Acked-by: Sam Ravnborg <sam@ravnborg.org>

> ---
>  Documentation/kbuild/00-INDEX                      | 2 ++
>  Documentation/{make => kbuild}/headers_install.txt | 0
>  2 files changed, 2 insertions(+)
>  rename Documentation/{make => kbuild}/headers_install.txt (100%)

Re: [PATCHv1 1/2] Documentation: headers_install.txt is part of kbuild

[Michal Marek]

On 2014-07-13 23:18, Sam Ravnborg wrote:
> On Sun, Jul 13, 2014 at 12:15:29PM +0200, Yann Droneaud wrote:
>> 'headers_install.txt' from Documentation/make/ is related to Kbuild
>> so it must be moved in Documentation/kbuild/ directory.
>>
>> As Documentation/make/ directory has only one file, it will be removed
>> as a consequence of moving 'headers_install.txt'.
>>
>> Cc: Kirill A. Shutemov <kirill@shutemov.name>
>> Cc: Michal Marek <mmarek@suse.cz>
>> Cc: David Woodhouse <dwmw2@infradead.org>
>> Cc: Rob Landley <rob@landley.net>
>> Cc: Sam Ravnborg <sam@ravnborg.org>
>> Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>
> 
> This is much better - thanks.
> Acked-by: Sam Ravnborg <sam@ravnborg.org>

Applied to kbuild.git#misc, thanks.

Michal

[PATCHv1 2/2] Documentation/kbuild/headers_install.txt: update documentation

[Yann Droneaud]

Documentation in kbuild/headers_install.txt is not
up to date regarding:
- way to list the various architectures;
- path where the headers are installed.

This patch try to fix these issues.

Cc: Kirill A. Shutemov <kirill@shutemov.name>
Cc: Michal Marek <mmarek@suse.cz>
Cc: David Woodhouse <dwmw2@infradead.org>
Cc: Rob Landley <rob@landley.net>
Cc: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>
---
 Documentation/kbuild/headers_install.txt | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/kbuild/headers_install.txt b/Documentation/kbuild/headers_install.txt
index 951eb9f1e040..8b6751f10dd3 100644
--- a/Documentation/kbuild/headers_install.txt
+++ b/Documentation/kbuild/headers_install.txt
@@ -24,23 +24,24 @@ 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
+  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
+current architecture.  The asm/ directory of the exported kernel headers
+is platform-specific, to see a list of supported architectures use
 the command:
 
-  ls -d include/asm-* | sed 's/.*-//'
+  /bin/ls -1 arch/*/include/asm/Kbuild | sed -e 's,^arch/,,' \
+                                             -e 's,/include/asm/Kbuild$,,'
 
-INSTALL_HDR_PATH indicates where to install the headers.  It defaults to
-"./usr/include".
+INSTALL_HDR_PATH indicates where to create include/ directory to install the
+headers. It defaults to "./usr/".
 
 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.)  You also can use HDR_ARCH_LIST to specify list of architectures.
-Remember to provide the appropriate linux/asm directory via "mv" or "ln -s"
+Remember to provide the appropriate 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
-- 
1.9.3

Re: [PATCHv1 2/2] Documentation/kbuild/headers_install.txt: update documentation

[Sam Ravnborg]

On Sun, Jul 13, 2014 at 12:15:30PM +0200, Yann Droneaud wrote:
> Documentation in kbuild/headers_install.txt is not
> up to date regarding:
> - way to list the various architectures;
> - path where the headers are installed.
> 
> This patch try to fix these issues.
> 
> Cc: Kirill A. Shutemov <kirill@shutemov.name>
> Cc: Michal Marek <mmarek@suse.cz>
> Cc: David Woodhouse <dwmw2@infradead.org>
> Cc: Rob Landley <rob@landley.net>
> Cc: Sam Ravnborg <sam@ravnborg.org>
> Signed-off-by: Yann Droneaud <ydroneaud@opteya.com>
> ---
>  Documentation/kbuild/headers_install.txt | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/kbuild/headers_install.txt b/Documentation/kbuild/headers_install.txt
> index 951eb9f1e040..8b6751f10dd3 100644
> --- a/Documentation/kbuild/headers_install.txt
> +++ b/Documentation/kbuild/headers_install.txt
> @@ -24,23 +24,24 @@ 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
> +  make headers_install ARCH=i386 INSTALL_HDR_PATH=/usr
OK

>  

> to see a list of supported architectures use
>  the command:
>  
> -  ls -d include/asm-* | sed 's/.*-//'
> +  /bin/ls -1 arch/*/include/asm/Kbuild | sed -e 's,^arch/,,' \
> +                                             -e 's,/include/asm/Kbuild$,,'
This information is nor relevant these days as all architectures support exporting userspace headers.
So drop this part of the documentation.
cris is broken - I will send a patch to fix this.
In reality um does not support exporting headers - but it makes no sense either.
We do not want to do anything special just to mention that um is not included.

>  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.)
I have seriously considered dropping the "headers_install_all" target.
It does not make any sense as some files are optional for the individual archs
and only pure luck will define if the relevant fiels are included or not.

We would still like the "headers_check_all" feature but this is better done in
a small shell script than as it is today where we need special handling
to support it in Makefile.headersinst - and it adds complexity
to the top-level Makefile which we shall avoid.
But this is unrelated to your documentation clean-up.

	Sam