2005-04-16 16:20:36 -06:00
|
|
|
###
|
|
|
|
# This makefile is used to generate the kernel documentation,
|
|
|
|
# primarily based on in-line comments in various source files.
|
|
|
|
# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
|
2006-03-31 16:04:59 -07:00
|
|
|
# to document the SRC - and how to read it.
|
2005-04-16 16:20:36 -06:00
|
|
|
# To add a new book the only step required is to add the book to the
|
|
|
|
# list of DOCBOOKS.
|
|
|
|
|
2012-05-17 17:06:13 -06:00
|
|
|
DOCBOOKS := z8530book.xml device-drivers.xml \
|
2005-05-01 09:59:27 -06:00
|
|
|
kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
|
2009-12-15 17:46:59 -07:00
|
|
|
writing_usb_driver.xml networking.xml \
|
2008-03-20 12:43:45 -06:00
|
|
|
kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
|
2006-06-29 03:24:47 -06:00
|
|
|
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
|
2008-02-26 06:34:06 -07:00
|
|
|
genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
|
2010-08-17 04:04:34 -06:00
|
|
|
80211.xml debugobjects.xml sh.xml regulator.xml \
|
2009-04-30 11:29:42 -06:00
|
|
|
alsa-driver-api.xml writing-an-alsa-driver.xml \
|
2015-10-07 01:55:28 -06:00
|
|
|
tracepoint.xml gpu.xml media_api.xml w1.xml \
|
2015-08-04 08:20:08 -06:00
|
|
|
writing_musb_glue_layer.xml crypto-API.xml iio.xml
|
2011-05-31 13:27:44 -06:00
|
|
|
|
2014-04-01 00:36:10 -06:00
|
|
|
include Documentation/DocBook/media/Makefile
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
###
|
|
|
|
# The build process is as follows (targets):
|
2007-07-19 02:48:23 -06:00
|
|
|
# (xmldocs) [by docproc]
|
|
|
|
# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto]
|
|
|
|
# +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
|
|
|
|
# +--> DIR=file (htmldocs) [by xmlto]
|
|
|
|
# +--> man/ (mandocs) [by xmlto]
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2005-11-13 17:08:15 -07:00
|
|
|
|
|
|
|
# for PDF and PS output you can choose between xmlto and docbook-utils tools
|
|
|
|
PDF_METHOD = $(prefer-db2x)
|
|
|
|
PS_METHOD = $(prefer-db2x)
|
|
|
|
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
###
|
|
|
|
# The targets that may be used.
|
2011-05-31 13:27:44 -06:00
|
|
|
PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2014-01-19 22:10:10 -07:00
|
|
|
targets += $(DOCBOOKS)
|
2005-04-16 16:20:36 -06:00
|
|
|
BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
|
2010-08-10 19:02:51 -06:00
|
|
|
xmldocs: $(BOOKS)
|
2005-04-16 16:20:36 -06:00
|
|
|
sgmldocs: xmldocs
|
|
|
|
|
|
|
|
PS := $(patsubst %.xml, %.ps, $(BOOKS))
|
|
|
|
psdocs: $(PS)
|
|
|
|
|
|
|
|
PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
|
|
|
|
pdfdocs: $(PDF)
|
|
|
|
|
2007-04-11 09:44:12 -06:00
|
|
|
HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
|
2011-05-25 09:24:48 -06:00
|
|
|
htmldocs: $(HTML)
|
2015-11-19 07:38:46 -07:00
|
|
|
$(call cmd,build_main_index)
|
2011-06-15 20:13:19 -06:00
|
|
|
$(call install_media_images)
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
MAN := $(patsubst %.xml, %.9, $(BOOKS))
|
|
|
|
mandocs: $(MAN)
|
2015-07-08 13:06:44 -06:00
|
|
|
find $(obj)/man -name '*.9' | xargs gzip -nf
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
installmandocs: mandocs
|
2005-05-01 09:59:27 -06:00
|
|
|
mkdir -p /usr/local/man/man9/
|
2015-08-06 16:36:52 -06:00
|
|
|
find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \
|
|
|
|
sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \
|
|
|
|
xargs install -m 644 -t /usr/local/man/man9/
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
###
|
|
|
|
#External programs used
|
2015-07-28 13:45:15 -06:00
|
|
|
KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
|
|
|
|
KERNELDOC = $(srctree)/scripts/kernel-doc
|
|
|
|
DOCPROC = $(objtree)/scripts/docproc
|
2015-09-27 18:09:52 -06:00
|
|
|
CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype
|
|
|
|
|
|
|
|
# Use a fixed encoding - UTF-8 if the C library has support built-in
|
|
|
|
# or ASCII if not
|
|
|
|
LC_CTYPE := $(call try-run, LC_CTYPE=C.UTF-8 $(CHECK_LC_CTYPE),C.UTF-8,C)
|
|
|
|
export LC_CTYPE
|
2005-05-01 09:59:27 -06:00
|
|
|
|
2014-03-18 00:47:13 -06:00
|
|
|
XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
|
2009-12-15 17:46:59 -07:00
|
|
|
XMLTOFLAGS += --skip-validation
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
###
|
|
|
|
# DOCPROC is used for two purposes:
|
|
|
|
# 1) To generate a dependency list for a .tmpl file
|
|
|
|
# 2) To preprocess a .tmpl file and call kernel-doc with
|
|
|
|
# appropriate parameters.
|
|
|
|
# The following rules are used to generate the .xml documentation
|
|
|
|
# required to generate the final targets. (ps, pdf, html).
|
|
|
|
quiet_cmd_docproc = DOCPROC $@
|
|
|
|
cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
|
|
|
|
define rule_docproc
|
|
|
|
set -e; \
|
|
|
|
$(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
|
|
|
|
$(cmd_$(1)); \
|
|
|
|
( \
|
|
|
|
echo 'cmd_$@ := $(cmd_$(1))'; \
|
|
|
|
echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
|
|
|
|
) > $(dir $@).$(notdir $@).cmd
|
|
|
|
endef
|
|
|
|
|
2015-07-28 13:45:15 -06:00
|
|
|
%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
|
2005-04-16 16:20:36 -06:00
|
|
|
$(call if_changed_rule,docproc)
|
|
|
|
|
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>
2008-08-12 16:09:06 -06:00
|
|
|
# Tell kbuild to always build the programs
|
|
|
|
always := $(hostprogs-y)
|
|
|
|
|
2005-11-13 17:08:15 -07:00
|
|
|
notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
|
|
|
|
exit 1
|
|
|
|
db2xtemplate = db2TYPE -o $(dir $@) $<
|
|
|
|
xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
|
|
|
|
|
|
|
|
# determine which methods are available
|
|
|
|
ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
|
|
|
|
use-db2x = db2x
|
|
|
|
prefer-db2x = db2x
|
|
|
|
else
|
|
|
|
use-db2x = notfound
|
|
|
|
prefer-db2x = $(use-xmlto)
|
|
|
|
endif
|
|
|
|
ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
|
|
|
|
use-xmlto = xmlto
|
|
|
|
prefer-xmlto = xmlto
|
|
|
|
else
|
|
|
|
use-xmlto = notfound
|
|
|
|
prefer-xmlto = $(use-db2x)
|
|
|
|
endif
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2005-11-13 17:08:15 -07:00
|
|
|
# the commands, generated from the chosen template
|
|
|
|
quiet_cmd_db2ps = PS $@
|
|
|
|
cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
|
2005-04-16 16:20:36 -06:00
|
|
|
%.ps : %.xml
|
|
|
|
$(call cmd,db2ps)
|
|
|
|
|
2008-10-29 15:00:57 -06:00
|
|
|
quiet_cmd_db2pdf = PDF $@
|
2005-11-13 17:08:15 -07:00
|
|
|
cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
|
2005-04-16 16:20:36 -06:00
|
|
|
%.pdf : %.xml
|
|
|
|
$(call cmd,db2pdf)
|
|
|
|
|
2007-05-08 01:29:36 -06:00
|
|
|
|
2009-04-17 19:28:55 -06:00
|
|
|
index = index.html
|
2014-03-18 00:47:13 -06:00
|
|
|
main_idx = $(obj)/$(index)
|
2015-11-19 07:38:46 -07:00
|
|
|
quiet_cmd_build_main_index = HTML $(main_idx)
|
|
|
|
cmd_build_main_index = rm -rf $(main_idx); \
|
2007-05-08 01:29:36 -06:00
|
|
|
echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
|
|
|
|
echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
|
|
|
|
cat $(HTML) >> $(main_idx)
|
|
|
|
|
2008-10-29 15:00:57 -06:00
|
|
|
quiet_cmd_db2html = HTML $@
|
2013-11-06 14:18:27 -07:00
|
|
|
cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
|
2005-05-01 09:59:28 -06:00
|
|
|
echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
|
2014-03-18 00:47:13 -06:00
|
|
|
$(patsubst %.html,%,$(notdir $@))</a><p>' > $@
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2015-07-28 13:45:15 -06:00
|
|
|
###
|
|
|
|
# Rules to create an aux XML and .db, and use them to re-process the DocBook XML
|
|
|
|
# to fill internal hyperlinks
|
|
|
|
gen_aux_xml = :
|
|
|
|
quiet_gen_aux_xml = echo ' XMLREF $@'
|
|
|
|
silent_gen_aux_xml = :
|
|
|
|
%.aux.xml: %.xml
|
|
|
|
@$($(quiet)gen_aux_xml)
|
|
|
|
@rm -rf $@
|
|
|
|
@(cat $< | egrep "^<refentry id" | egrep -o "\".*\"" | cut -f 2 -d \" > $<.db)
|
|
|
|
@$(KERNELDOCXMLREF) -db $<.db $< > $@
|
|
|
|
.PRECIOUS: %.aux.xml
|
|
|
|
|
|
|
|
%.html: %.aux.xml
|
2005-05-01 09:59:27 -06:00
|
|
|
@(which xmlto > /dev/null 2>&1) || \
|
2005-05-01 09:59:28 -06:00
|
|
|
(echo "*** You need to install xmlto ***"; \
|
2005-04-16 16:20:36 -06:00
|
|
|
exit 1)
|
|
|
|
@rm -rf $@ $(patsubst %.html,%,$@)
|
|
|
|
$(call cmd,db2html)
|
|
|
|
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
|
|
|
|
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
|
|
|
|
|
2005-11-13 17:08:15 -07:00
|
|
|
quiet_cmd_db2man = MAN $@
|
2015-08-06 16:36:52 -06:00
|
|
|
cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi
|
2005-05-01 09:59:27 -06:00
|
|
|
%.9 : %.xml
|
|
|
|
@(which xmlto > /dev/null 2>&1) || \
|
2005-05-01 09:59:28 -06:00
|
|
|
(echo "*** You need to install xmlto ***"; \
|
2005-05-01 09:59:27 -06:00
|
|
|
exit 1)
|
2015-08-06 16:36:52 -06:00
|
|
|
$(Q)mkdir -p $(obj)/man/$(*F)
|
2005-05-01 09:59:27 -06:00
|
|
|
$(call cmd,db2man)
|
|
|
|
@touch $@
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
###
|
2007-10-19 17:30:25 -06:00
|
|
|
# Rules to generate postscripts and PNG images from .fig format files
|
2005-04-16 16:20:36 -06:00
|
|
|
quiet_cmd_fig2eps = FIG2EPS $@
|
|
|
|
cmd_fig2eps = fig2dev -Leps $< $@
|
|
|
|
|
|
|
|
%.eps: %.fig
|
|
|
|
@(which fig2dev > /dev/null 2>&1) || \
|
|
|
|
(echo "*** You need to install transfig ***"; \
|
|
|
|
exit 1)
|
|
|
|
$(call cmd,fig2eps)
|
|
|
|
|
|
|
|
quiet_cmd_fig2png = FIG2PNG $@
|
|
|
|
cmd_fig2png = fig2dev -Lpng $< $@
|
|
|
|
|
|
|
|
%.png: %.fig
|
|
|
|
@(which fig2dev > /dev/null 2>&1) || \
|
|
|
|
(echo "*** You need to install transfig ***"; \
|
|
|
|
exit 1)
|
|
|
|
$(call cmd,fig2png)
|
|
|
|
|
|
|
|
###
|
|
|
|
# Rule to convert a .c file to inline XML documentation
|
2008-03-28 15:30:58 -06:00
|
|
|
gen_xml = :
|
|
|
|
quiet_gen_xml = echo ' GEN $@'
|
|
|
|
silent_gen_xml = :
|
2005-04-16 16:20:36 -06:00
|
|
|
%.xml: %.c
|
2008-03-28 15:30:58 -06:00
|
|
|
@$($(quiet)gen_xml)
|
2005-04-16 16:20:36 -06:00
|
|
|
@( \
|
|
|
|
echo "<programlisting>"; \
|
|
|
|
expand --tabs=8 < $< | \
|
|
|
|
sed -e "s/&/\\&/g" \
|
|
|
|
-e "s/</\\</g" \
|
|
|
|
-e "s/>/\\>/g"; \
|
|
|
|
echo "</programlisting>") > $@
|
|
|
|
|
|
|
|
###
|
|
|
|
# Help targets as used by the top-level makefile
|
|
|
|
dochelp:
|
2006-12-06 16:16:26 -07:00
|
|
|
@echo ' Linux kernel internal documentation in different formats:'
|
|
|
|
@echo ' htmldocs - HTML'
|
|
|
|
@echo ' pdfdocs - PDF'
|
|
|
|
@echo ' psdocs - Postscript'
|
|
|
|
@echo ' xmldocs - XML DocBook'
|
2009-04-10 15:20:54 -06:00
|
|
|
@echo ' mandocs - man pages'
|
|
|
|
@echo ' installmandocs - install man pages generated by mandocs'
|
|
|
|
@echo ' cleandocs - clean all generated DocBook files'
|
2015-11-19 07:38:44 -07:00
|
|
|
@echo
|
|
|
|
@echo 'make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
|
|
|
|
@echo ' valid values for DOCBOOKS are: $(DOCBOOKS)'
|
|
|
|
|
2005-04-16 16:20:36 -06:00
|
|
|
|
|
|
|
###
|
|
|
|
# Temporary files left by various tools
|
|
|
|
clean-files := $(DOCBOOKS) \
|
2015-07-28 13:45:15 -06:00
|
|
|
$(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.aux, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.tex, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.log, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.out, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.ps, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.html, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.9, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \
|
|
|
|
$(patsubst %.xml, %.xml, $(DOCBOOKS)) \
|
2009-12-15 17:46:59 -07:00
|
|
|
$(index)
|
2005-04-16 16:20:36 -06:00
|
|
|
|
2011-05-31 13:27:44 -06:00
|
|
|
clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
|
2006-03-05 15:14:10 -07:00
|
|
|
|
2011-05-31 13:27:44 -06:00
|
|
|
cleandocs: cleanmediadocs
|
2009-04-10 15:20:54 -06:00
|
|
|
$(Q)rm -f $(call objectify, $(clean-files))
|
|
|
|
$(Q)rm -rf $(call objectify, $(clean-dirs))
|
|
|
|
|
2006-03-05 15:14:10 -07:00
|
|
|
# Declare the contents of the .PHONY variable as phony. We keep that
|
|
|
|
# information in a variable se we can use it in if_changed and friends.
|
|
|
|
|
|
|
|
.PHONY: $(PHONY)
|