docsrc: build Documentation/ sources

Currently source files in the Documentation/ sub-dir can easily bit-rot
since they are not generally buildable, either because they are hidden in
text files or because there are no Makefile rules for them.  This needs to
be fixed so that the source files remain usable and good examples of code
instead of bad examples.

Add the ability to build source files that are in the Documentation/ dir.
Add to Kconfig as "BUILD_DOCSRC" config symbol.

Use "CONFIG_BUILD_DOCSRC=1 make ..." to build objects from the
Documentation/ sources.  Or enable BUILD_DOCSRC in the *config system.
However, this symbol depends on HEADERS_CHECK since the header files need
to be installed (for userspace builds).

Built (using cross-tools) for x86-64, i386, alpha, ia64, sparc32,
sparc64, powerpc, sh, m68k, & mips.

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Reviewed-by: Sam Ravnborg <sam@ravnborg.org>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 1d1b34500b69278e5f217c6b521d729a1c78b4f9..1615350b7b53b4b681ed187e176e896ca0b0845e 100644 (file)
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -102,6 +102,13 @@ C-procfs-example = procfs_example.xml
 C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
 $(obj)/procfs-guide.xml: $(C-procfs-example2)
 
 C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
 $(obj)/procfs-guide.xml: $(C-procfs-example2)
 

+# List of programs to build
+##oops, this is a kernel module::hostprogs-y := procfs_example
+obj-m += procfs_example.o
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)
+

 notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
                   exit 1
 db2xtemplate = db2TYPE -o $(dir $@) $<
 notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
                   exit 1
 db2xtemplate = db2TYPE -o $(dir $@) $<

diff --git a/Documentation/Makefile b/Documentation/Makefile
new file mode 100644 (file)
index 0000000..94b9457
--- /dev/null
+++ b/Documentation/Makefile
@@ -0,0 +1,3 @@
+obj-m := DocBook/ accounting/ auxdisplay/ connector/ \
+       filesystems/configfs/ ia64/ networking/ \
+       pcmcia/ spi/ video4linux/ vm/ watchdog/src/

diff --git a/Documentation/accounting/Makefile b/Documentation/accounting/Makefile
new file mode 100644 (file)
index 0000000..31929eb
--- /dev/null
+++ b/Documentation/accounting/Makefile
@@ -0,0 +1,10 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := getdelays
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)
+
+HOSTCFLAGS_getdelays.o += -I$(objtree)/usr/include

diff --git a/Documentation/auxdisplay/Makefile b/Documentation/auxdisplay/Makefile
new file mode 100644 (file)
index 0000000..51fe233
--- /dev/null
+++ b/Documentation/auxdisplay/Makefile
@@ -0,0 +1,10 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := cfag12864b-example
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)
+
+HOSTCFLAGS_cfag12864b-example.o += -I$(objtree)/usr/include

diff --git a/Documentation/connector/Makefile b/Documentation/connector/Makefile
new file mode 100644 (file)
index 0000000..8df1a72
--- /dev/null
+++ b/Documentation/connector/Makefile
@@ -0,0 +1,11 @@
+ifneq ($(CONFIG_CONNECTOR),)
+obj-m += cn_test.o
+endif
+
+# List of programs to build
+hostprogs-y := ucon
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)
+
+HOSTCFLAGS_ucon.o += -I$(objtree)/usr/include

diff --git a/Documentation/filesystems/configfs/Makefile b/Documentation/filesystems/configfs/Makefile
new file mode 100644 (file)
index 0000000..be7ec5e
--- /dev/null
+++ b/Documentation/filesystems/configfs/Makefile
@@ -0,0 +1,3 @@
+ifneq ($(CONFIG_CONFIGFS_FS),)
+obj-m += configfs_example_explicit.o configfs_example_macros.o
+endif

diff --git a/Documentation/ia64/Makefile b/Documentation/ia64/Makefile
new file mode 100644 (file)
index 0000000..b75db69
--- /dev/null
+++ b/Documentation/ia64/Makefile
@@ -0,0 +1,8 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := aliasing-test
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)

diff --git a/Documentation/networking/Makefile b/Documentation/networking/Makefile
new file mode 100644 (file)
index 0000000..6d8af1a
--- /dev/null
+++ b/Documentation/networking/Makefile
@@ -0,0 +1,8 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := ifenslave
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)

diff --git a/Documentation/pcmcia/Makefile b/Documentation/pcmcia/Makefile
new file mode 100644 (file)
index 0000000..accde87
--- /dev/null
+++ b/Documentation/pcmcia/Makefile
@@ -0,0 +1,10 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := crc32hash
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)
+
+HOSTCFLAGS_crc32hash.o += -I$(objtree)/usr/include

diff --git a/Documentation/spi/Makefile b/Documentation/spi/Makefile
new file mode 100644 (file)
index 0000000..a5b03c8
--- /dev/null
+++ b/Documentation/spi/Makefile
@@ -0,0 +1,11 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := spidev_test spidev_fdx
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)
+
+HOSTCFLAGS_spidev_test.o += -I$(objtree)/usr/include
+HOSTCFLAGS_spidev_fdx.o += -I$(objtree)/usr/include

diff --git a/Documentation/video4linux/Makefile b/Documentation/video4linux/Makefile
new file mode 100644 (file)
index 0000000..1ed0e98
--- /dev/null
+++ b/Documentation/video4linux/Makefile
@@ -0,0 +1,8 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := v4lgrab
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)

diff --git a/Documentation/vm/Makefile b/Documentation/vm/Makefile
new file mode 100644 (file)
index 0000000..6f562f7
--- /dev/null
+++ b/Documentation/vm/Makefile
@@ -0,0 +1,8 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := slabinfo
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)

diff --git a/Documentation/watchdog/src/Makefile b/Documentation/watchdog/src/Makefile
new file mode 100644 (file)
index 0000000..40e5f46
--- /dev/null
+++ b/Documentation/watchdog/src/Makefile
@@ -0,0 +1,8 @@
+# kbuild trick to avoid linker error. Can be omitted if a module is built.
+obj- := dummy.o
+
+# List of programs to build
+hostprogs-y := watchdog-simple watchdog-test
+
+# Tell kbuild to always build the programs
+always := $(hostprogs-y)

diff --git a/Makefile b/Makefile
index f3e206509ee1fc740e4b17357c39d64e97c0939a..fd3ca6e8188a6fe35c7dd4f1cc2b7d283078f9e3 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -821,6 +821,9 @@ ifdef CONFIG_HEADERS_CHECK
 endif
 ifdef CONFIG_SAMPLES
        $(Q)$(MAKE) $(build)=samples
 endif
 ifdef CONFIG_SAMPLES
        $(Q)$(MAKE) $(build)=samples

+endif
+ifdef CONFIG_BUILD_DOCSRC
+       $(Q)$(MAKE) $(build)=Documentation

 endif
        $(call vmlinux-modpost)
        $(call if_changed_rule,vmlinux__)
 endif
        $(call vmlinux-modpost)
        $(call if_changed_rule,vmlinux__)


@@ -1166,7 +1169,7 @@ MRPROPER_FILES += .config .config.old include/asm .version .old_version \
 #
 clean: rm-dirs  := $(CLEAN_DIRS)
 clean: rm-files := $(CLEAN_FILES)
 #
 clean: rm-dirs  := $(CLEAN_DIRS)
 clean: rm-files := $(CLEAN_FILES)

-clean-dirs      := $(addprefix _clean_,$(srctree) $(vmlinux-alldirs))
+clean-dirs      := $(addprefix _clean_,$(srctree) $(vmlinux-alldirs) Documentation)

 
 PHONY += $(clean-dirs) clean archclean
 $(clean-dirs):
 
 PHONY += $(clean-dirs) clean archclean
 $(clean-dirs):

diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index e1d4764435ed842ea1875c7739bfd668f6453fae..800ac848554425015c626e60ce2f6a02e949c229 100644 (file)
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -735,6 +735,15 @@ config FIREWIRE_OHCI_REMOTE_DMA
 
          If unsure, say N.
 
 
          If unsure, say N.
 

+menuconfig BUILD_DOCSRC
+       bool "Build targets in Documentation/ tree"
+       depends on HEADERS_CHECK
+       help
+         This option attempts to build objects from the source files in the
+         kernel Documentation/ tree.
+
+         Say N if you are unsure.
+

 source "samples/Kconfig"
 
 source "lib/Kconfig.kgdb"
 source "samples/Kconfig"
 
 source "lib/Kconfig.kgdb"