[PATCH 2/5] Description of _shipped files handling in kbuild

2014-12-02 Thread Nicholas Mc Guire 

Description of _shipped files handling in kbuild

This adds a section on handling of _shipped files in Kbuild
Makefiles and the build process.

This patch is against linux 3.18.0-rc6

Signed-off-by: Nicholas Mc Guire 
---
 Documentation/kbuild/makefiles.txt |   58 +++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/Documentation/kbuild/makefiles.txt 
b/Documentation/kbuild/makefiles.txt
index a311db8..df3a96a 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -19,6 +19,7 @@ This document describes the Linux kernel Makefiles.
   --- 3.10 Special Rules
   --- 3.11 $(CC) support functions
   --- 3.12 $(LD) support functions
+  --- 3.13 _shipped - generated files
 
=== 4 Host Program support
   --- 4.1 Simple Host Program
@@ -594,6 +595,61 @@ more details, with real examples.
#Makefile
LDFLAGS_vmlinux += $(call ld-option, -X)
 
+--- 3.13 _shipped - generated files
+
+   Some sources in the kernel are generated by tools or special
+   purpose scripts so that the build process dependencies can be kept
+   at a reasonable level. Also in cases where the translation is not
+   configuration dependent but might impact build time, _shipped files
+   may be added along with the actual sources to speed up the build
+   process.
+
+   For standard tools like lex and yacc the make process will actually
+   generate the _shipped files (see scripts/Makefile.lib) and retain
+   them by marking them .PRECIOUS so they are not removed by the clean
+   targets.
+
+   For non-standard tools the generation of the _shipped file itself
+   may be manually achieved by building and then renaming. A makefile
+   target to generate the actual target file should to be provided
+   though and can be conditioned on an environment variable.
+
+   Example:
+   ifdef GENERATE_KEYMAP
+
+   $(obj)/defkeymap.c: $(obj)/%.c: $(src)/%.map
+   loadkeys --mktable $< > $@
+
+   endif
+
+   The _shipped file does not appear in the actual Makefile, this is
+   handled by the rules found in scripts/Makefile.lib.
+
+   
+   cmd_shipped = cat $< > $@
+
+   $(obj)/%: $(src)/%_shipped
+   $(call cmd,shipped)
+   
+
+   which simply will copy the target_shipped to the target
+
+   If a file of a make target is found in the build directory with the
+   extension _shipped, make will use it rather than generating the
+   respective target file from source.
+
+   The build will indicate the use of the _shipped file by the SHIPPED
+   quiet command in the make output.
+
+   Example:
+   LD  drivers/scsi/aic7xxx/built-in.o
+   SHIPPED drivers/scsi/aic7xxx/aic79xx_seq.h
+   SHIPPED drivers/scsi/aic7xxx/aic79xx_reg.h
+   CC [M]  drivers/scsi/aic7xxx/aic79xx_core.o
+   CC [M]  drivers/scsi/aic7xxx/aic79xx_pci.o
+   SHIPPED drivers/scsi/aic7xxx/aic79xx_reg_print.c
+   CC [M]  drivers/scsi/aic7xxx/aic79xx_reg_print.o
+
 
 === 4 Host Program support
 
@@ -1399,10 +1455,10 @@ Original version made by Michael Elizabeth Chastain, 

 Updates by Kai Germaschewski 
 Updates by Sam Ravnborg 
 Language QA by Jan Engelhardt 
+Kbuild support for shipped files Nicholas Mc Guire 
 
 === 11 TODO
 
-- Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.
 - Add more variables to section 7?
 
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[PATCH 2/5] Description of _shipped files handling in kbuild

2014-12-02 Thread Nicholas Mc Guire 

Description of _shipped files handling in kbuild

This adds a section on handling of _shipped files in Kbuild
Makefiles and the build process.

This patch is against linux 3.18.0-rc6

Signed-off-by: Nicholas Mc Guire der.h...@hofr.at
---
 Documentation/kbuild/makefiles.txt |   58 +++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/Documentation/kbuild/makefiles.txt 
b/Documentation/kbuild/makefiles.txt
index a311db8..df3a96a 100644
--- a/Documentation/kbuild/makefiles.txt
+++ b/Documentation/kbuild/makefiles.txt
@@ -19,6 +19,7 @@ This document describes the Linux kernel Makefiles.
   --- 3.10 Special Rules
   --- 3.11 $(CC) support functions
   --- 3.12 $(LD) support functions
+  --- 3.13 _shipped - generated files
 
=== 4 Host Program support
   --- 4.1 Simple Host Program
@@ -594,6 +595,61 @@ more details, with real examples.
#Makefile
LDFLAGS_vmlinux += $(call ld-option, -X)
 
+--- 3.13 _shipped - generated files
+
+   Some sources in the kernel are generated by tools or special
+   purpose scripts so that the build process dependencies can be kept
+   at a reasonable level. Also in cases where the translation is not
+   configuration dependent but might impact build time, _shipped files
+   may be added along with the actual sources to speed up the build
+   process.
+
+   For standard tools like lex and yacc the make process will actually
+   generate the _shipped files (see scripts/Makefile.lib) and retain
+   them by marking them .PRECIOUS so they are not removed by the clean
+   targets.
+
+   For non-standard tools the generation of the _shipped file itself
+   may be manually achieved by building and then renaming. A makefile
+   target to generate the actual target file should to be provided
+   though and can be conditioned on an environment variable.
+
+   Example:
+   ifdef GENERATE_KEYMAP
+
+   $(obj)/defkeymap.c: $(obj)/%.c: $(src)/%.map
+   loadkeys --mktable $  $@
+
+   endif
+
+   The _shipped file does not appear in the actual Makefile, this is
+   handled by the rules found in scripts/Makefile.lib.
+
+   snip
+   cmd_shipped = cat $  $@
+
+   $(obj)/%: $(src)/%_shipped
+   $(call cmd,shipped)
+   snip
+
+   which simply will copy the target_shipped to the target
+
+   If a file of a make target is found in the build directory with the
+   extension _shipped, make will use it rather than generating the
+   respective target file from source.
+
+   The build will indicate the use of the _shipped file by the SHIPPED
+   quiet command in the make output.
+
+   Example:
+   LD  drivers/scsi/aic7xxx/built-in.o
+   SHIPPED drivers/scsi/aic7xxx/aic79xx_seq.h
+   SHIPPED drivers/scsi/aic7xxx/aic79xx_reg.h
+   CC [M]  drivers/scsi/aic7xxx/aic79xx_core.o
+   CC [M]  drivers/scsi/aic7xxx/aic79xx_pci.o
+   SHIPPED drivers/scsi/aic7xxx/aic79xx_reg_print.c
+   CC [M]  drivers/scsi/aic7xxx/aic79xx_reg_print.o
+
 
 === 4 Host Program support
 
@@ -1399,10 +1455,10 @@ Original version made by Michael Elizabeth Chastain, 
mailto:m...@shout.net
 Updates by Kai Germaschewski k...@tp1.ruhr-uni-bochum.de
 Updates by Sam Ravnborg s...@ravnborg.org
 Language QA by Jan Engelhardt jeng...@gmx.de
+Kbuild support for shipped files Nicholas Mc Guire der.h...@hofr.at
 
 === 11 TODO
 
-- Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.
 - Add more variables to section 7?
 
-- 
1.7.10.4

--
To unsubscribe from this list: send the line unsubscribe linux-kernel in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/