kbuild: introduce destination-y for exported headers

xtensa and arm have asked for a possibility to export headers and locate them in a specific directory when exported. Introduce destiantion-y to support this. This patch in additiona adds some limited documentation for the variables used for exported headers. Signed-off-by: Sam Ravnborg <sam@ravnborg.org> Cc: Oskar Schirmer <os@emlix.com> Cc: Mikael Starvik <mikael.starvik@axis.com>

kbuild: introduce destination-y for exported headers
xtensa and arm have asked for a possibility to export headers and locate them in a specific directory when exported. Introduce destiantion-y to support this. This patch in additiona adds some limited documentation for the variables used for exported headers. Signed-off-by: Sam Ravnborg <sam@ravnborg.org> Cc: Oskar Schirmer <os@emlix.com> Cc: Mikael Starvik <mikael.starvik@axis.com>
Sam Ravnborg
1 parent 4774bb1ced
Showing 2 changed files with 77 additions and 8 deletions Side-by-side Diff
Documentation/kbuild/makefiles.txt
scripts/Makefile.headersinst
@@ -40,11 +40,17 @@
 	   --- 6.7 Custom kbuild commands
 	   --- 6.8 Preprocessing linker scripts
  
-	=== 7 Kbuild Variables
-	=== 8 Makefile language
-	=== 9 Credits
-	=== 10 TODO
+	=== 7 Kbuild syntax for exported headers
+		--- 7.1 header-y
+		--- 7.2 objhdr-y
+		--- 7.3 destination-y
+		--- 7.4 unifdef-y (deprecated)
  
+	=== 8 Kbuild Variables
+	=== 9 Makefile language
+	=== 10 Credits
+	=== 11 TODO
+
 === 1 Overview
  
 The Makefiles have five parts:
  
  
@@ -1143,9 +1149,70 @@
 	The kbuild infrastructure for *lds file are used in several
 	architecture-specific files.
  
+=== 7 Kbuild syntax for exported headers
  
-=== 7 Kbuild Variables
+The kernel include a set of headers that is exported to userspace.
+Many headers can be exported as-is but other headers requires  a
+minimal pre-processing before they are ready for user-space.
+The pre-processing does:
+- drop kernel specific annotations
+- drop include of compiler.h
+- drop all sections that is kernel internat (guarded by ifdef __KERNEL__)
  
+Each relevant directory contain a file name "Kbuild" which specify the
+headers to be exported.
+See subsequent chapter for the syntax of the Kbuild file.
+
+	--- 7.1 header-y
+
+	header-y specify header files to be exported.
+
+		Example:
+			#include/linux/Kbuild
+			header-y += usb/
+			header-y += aio_abi.h
+
+	The convention is to list one file per line and
+	preferably in alphabetic order.
+
+	header-y also specify which subdirectories to visit.
+	A subdirectory is identified by a trailing '/' which
+	can be seen in the example above for the usb subdirectory.
+
+	Subdirectories are visited before their parent directories.
+
+	--- 7.2 objhdr-y
+
+	objhdr-y specifies generated files to be exported.
+	Generated files are special as they need to be looked
+	up in another directory when doing 'make O=...' builds.
+
+		Example:
+			#include/linux/Kbuild
+			objhdr-y += version.h
+
+	--- 7.3 destination-y
+
+	When an architecture have a set of exported headers that needs to be
+	exported to a different directory destination-y is used.
+	destination-y specify the destination directory for all exported
+	headers in the file where it is present.
+
+		Example:
+			#arch/xtensa/platforms/s6105/include/platform/Kbuild
+			destination-y := include/linux
+
+	In the example above all exported headers in the Kbuild file
+	will be located in the directory "include/linux" when exported.
+
+
+	--- 7.4 unifdef-y (deprecated)
+
+	unifdef-y is deprecated. A direct replacement is header-y.
+
+
+=== 8 Kbuild Variables
+
 The top Makefile exports the following variables:
  
     VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
@@ -1206,7 +1273,7 @@
 	INSTALL_MOD_STRIP will used as the option(s) to the strip command.
  
  
-=== 8 Makefile language
+=== 9 Makefile language
  
 The kernel Makefiles are designed to be run with GNU Make.  The Makefiles
 use only the documented features of GNU Make, but they do use many
  
@@ -1225,14 +1292,14 @@
 There are some cases where "=" is appropriate.  Usually, though, ":="
 is the right choice.
  
-=== 9 Credits
+=== 10 Credits
  
 Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
 Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
 Updates by Sam Ravnborg <sam@ravnborg.org>
 Language QA by Jan Engelhardt <jengelh@gmx.de>
  
-=== 10 TODO
+=== 11 TODO
  
 - Describe how kbuild supports shipped files with _shipped.
 - Generating offset header files.
@@ -14,6 +14,8 @@
 kbuild-file := $(srctree)/$(obj)/Kbuild
 include $(kbuild-file)
  
+_dst := $(if $(destination-y),$(destination-y),$(_dst))
+
 include scripts/Kbuild.include
  
 install       := $(INSTALL_HDR_PATH)/$(_dst)
...	...	@@ -40,11 +40,17 @@
40	40	--- 6.7 Custom kbuild commands
41	41	--- 6.8 Preprocessing linker scripts
42	42
43		- === 7 Kbuild Variables
44		- === 8 Makefile language
45		- === 9 Credits
46		- === 10 TODO
	43	+ === 7 Kbuild syntax for exported headers
	44	+ --- 7.1 header-y
	45	+ --- 7.2 objhdr-y
	46	+ --- 7.3 destination-y
	47	+ --- 7.4 unifdef-y (deprecated)
47	48
	49	+ === 8 Kbuild Variables
	50	+ === 9 Makefile language
	51	+ === 10 Credits
	52	+ === 11 TODO
	53	+
48	54	=== 1 Overview
49	55
50	56	The Makefiles have five parts:
51	57
52	58
...	...	@@ -1143,9 +1149,70 @@
1143	1149	The kbuild infrastructure for *lds file are used in several
1144	1150	architecture-specific files.
1145	1151
	1152	+=== 7 Kbuild syntax for exported headers
1146	1153
1147		-=== 7 Kbuild Variables
	1154	+The kernel include a set of headers that is exported to userspace.
	1155	+Many headers can be exported as-is but other headers requires a
	1156	+minimal pre-processing before they are ready for user-space.
	1157	+The pre-processing does:
	1158	+- drop kernel specific annotations
	1159	+- drop include of compiler.h
	1160	+- drop all sections that is kernel internat (guarded by ifdef __KERNEL__)
1148	1161
	1162	+Each relevant directory contain a file name "Kbuild" which specify the
	1163	+headers to be exported.
	1164	+See subsequent chapter for the syntax of the Kbuild file.
	1165	+
	1166	+ --- 7.1 header-y
	1167	+
	1168	+ header-y specify header files to be exported.
	1169	+
	1170	+ Example:
	1171	+ #include/linux/Kbuild
	1172	+ header-y += usb/
	1173	+ header-y += aio_abi.h
	1174	+
	1175	+ The convention is to list one file per line and
	1176	+ preferably in alphabetic order.
	1177	+
	1178	+ header-y also specify which subdirectories to visit.
	1179	+ A subdirectory is identified by a trailing '/' which
	1180	+ can be seen in the example above for the usb subdirectory.
	1181	+
	1182	+ Subdirectories are visited before their parent directories.
	1183	+
	1184	+ --- 7.2 objhdr-y
	1185	+
	1186	+ objhdr-y specifies generated files to be exported.
	1187	+ Generated files are special as they need to be looked
	1188	+ up in another directory when doing 'make O=...' builds.
	1189	+
	1190	+ Example:
	1191	+ #include/linux/Kbuild
	1192	+ objhdr-y += version.h
	1193	+
	1194	+ --- 7.3 destination-y
	1195	+
	1196	+ When an architecture have a set of exported headers that needs to be
	1197	+ exported to a different directory destination-y is used.
	1198	+ destination-y specify the destination directory for all exported
	1199	+ headers in the file where it is present.
	1200	+
	1201	+ Example:
	1202	+ #arch/xtensa/platforms/s6105/include/platform/Kbuild
	1203	+ destination-y := include/linux
	1204	+
	1205	+ In the example above all exported headers in the Kbuild file
	1206	+ will be located in the directory "include/linux" when exported.
	1207	+
	1208	+
	1209	+ --- 7.4 unifdef-y (deprecated)
	1210	+
	1211	+ unifdef-y is deprecated. A direct replacement is header-y.
	1212	+
	1213	+
	1214	+=== 8 Kbuild Variables
	1215	+
1149	1216	The top Makefile exports the following variables:
1150	1217
1151	1218	VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
...	...	@@ -1206,7 +1273,7 @@
1206	1273	INSTALL_MOD_STRIP will used as the option(s) to the strip command.
1207	1274
1208	1275
1209		-=== 8 Makefile language
	1276	+=== 9 Makefile language
1210	1277
1211	1278	The kernel Makefiles are designed to be run with GNU Make. The Makefiles
1212	1279	use only the documented features of GNU Make, but they do use many
1213	1280
...	...	@@ -1225,14 +1292,14 @@
1225	1292	There are some cases where "=" is appropriate. Usually, though, ":="
1226	1293	is the right choice.
1227	1294
1228		-=== 9 Credits
	1295	+=== 10 Credits
1229	1296
1230	1297	Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net>
1231	1298	Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
1232	1299	Updates by Sam Ravnborg <sam@ravnborg.org>
1233	1300	Language QA by Jan Engelhardt <jengelh@gmx.de>
1234	1301
1235		-=== 10 TODO
	1302	+=== 11 TODO
1236	1303
1237	1304	- Describe how kbuild supports shipped files with _shipped.
1238	1305	- Generating offset header files.
...	...	@@ -14,6 +14,8 @@
14	14	kbuild-file := $(srctree)/$(obj)/Kbuild
15	15	include $(kbuild-file)
16	16
	17	+_dst := $(if $(destination-y),$(destination-y),$(_dst))
	18	+
17	19	include scripts/Kbuild.include
18	20
19	21	install := $(INSTALL_HDR_PATH)/$(_dst)