Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
1###
2# This makefile is used to generate the kernel documentation,
3# primarily based on in-line comments in various source files.
4# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
5# to document the SRC - and how to read it.
6# To add a new book the only step required is to add the book to the
7# list of DOCBOOKS.
8
9DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11 procfs-guide.xml writing_usb_driver.xml networking.xml \
12 kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15 mac80211.xml debugobjects.xml sh.xml
16
17###
18# The build process is as follows (targets):
19# (xmldocs) [by docproc]
20# file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto]
21# +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
22# +--> DIR=file (htmldocs) [by xmlto]
23# +--> man/ (mandocs) [by xmlto]
24
25
26# for PDF and PS output you can choose between xmlto and docbook-utils tools
27PDF_METHOD = $(prefer-db2x)
28PS_METHOD = $(prefer-db2x)
29
30
31###
32# The targets that may be used.
33PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs
34
35BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
36xmldocs: $(BOOKS)
37sgmldocs: xmldocs
38
39PS := $(patsubst %.xml, %.ps, $(BOOKS))
40psdocs: $(PS)
41
42PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
43pdfdocs: $(PDF)
44
45HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
46htmldocs: $(HTML)
47 $(call build_main_index)
48
49MAN := $(patsubst %.xml, %.9, $(BOOKS))
50mandocs: $(MAN)
51
52installmandocs: mandocs
53 mkdir -p /usr/local/man/man9/
54 install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
55
56###
57#External programs used
58KERNELDOC = $(srctree)/scripts/kernel-doc
59DOCPROC = $(objtree)/scripts/basic/docproc
60
61XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl
62#XMLTOFLAGS += --skip-validation
63
64###
65# DOCPROC is used for two purposes:
66# 1) To generate a dependency list for a .tmpl file
67# 2) To preprocess a .tmpl file and call kernel-doc with
68# appropriate parameters.
69# The following rules are used to generate the .xml documentation
70# required to generate the final targets. (ps, pdf, html).
71quiet_cmd_docproc = DOCPROC $@
72 cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
73define rule_docproc
74 set -e; \
75 $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
76 $(cmd_$(1)); \
77 ( \
78 echo 'cmd_$@ := $(cmd_$(1))'; \
79 echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
80 ) > $(dir $@).$(notdir $@).cmd
81endef
82
83%.xml: %.tmpl FORCE
84 $(call if_changed_rule,docproc)
85
86###
87#Read in all saved dependency files
88cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
89
90ifneq ($(cmd_files),)
91 include $(cmd_files)
92endif
93
94###
95# Changes in kernel-doc force a rebuild of all documentation
96$(BOOKS): $(KERNELDOC)
97
98###
99# procfs guide uses a .c file as example code.
100# This requires an explicit dependency
101C-procfs-example = procfs_example.xml
102C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
103$(obj)/procfs-guide.xml: $(C-procfs-example2)
104
105notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
106 exit 1
107db2xtemplate = db2TYPE -o $(dir $@) $<
108xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
109
110# determine which methods are available
111ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
112 use-db2x = db2x
113 prefer-db2x = db2x
114else
115 use-db2x = notfound
116 prefer-db2x = $(use-xmlto)
117endif
118ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
119 use-xmlto = xmlto
120 prefer-xmlto = xmlto
121else
122 use-xmlto = notfound
123 prefer-xmlto = $(use-db2x)
124endif
125
126# the commands, generated from the chosen template
127quiet_cmd_db2ps = PS $@
128 cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
129%.ps : %.xml
130 $(call cmd,db2ps)
131
132quiet_cmd_db2pdf = PDF $@
133 cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
134%.pdf : %.xml
135 $(call cmd,db2pdf)
136
137
138main_idx = Documentation/DocBook/index.html
139build_main_index = rm -rf $(main_idx) && \
140 echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
141 echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
142 cat $(HTML) >> $(main_idx)
143
144quiet_cmd_db2html = HTML $@
145 cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
146 echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
147 $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
148
149%.html: %.xml
150 @(which xmlto > /dev/null 2>&1) || \
151 (echo "*** You need to install xmlto ***"; \
152 exit 1)
153 @rm -rf $@ $(patsubst %.html,%,$@)
154 $(call cmd,db2html)
155 @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
156 cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
157
158quiet_cmd_db2man = MAN $@
159 cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
160%.9 : %.xml
161 @(which xmlto > /dev/null 2>&1) || \
162 (echo "*** You need to install xmlto ***"; \
163 exit 1)
164 $(Q)mkdir -p $(obj)/man
165 $(call cmd,db2man)
166 @touch $@
167
168###
169# Rules to generate postscripts and PNG images from .fig format files
170quiet_cmd_fig2eps = FIG2EPS $@
171 cmd_fig2eps = fig2dev -Leps $< $@
172
173%.eps: %.fig
174 @(which fig2dev > /dev/null 2>&1) || \
175 (echo "*** You need to install transfig ***"; \
176 exit 1)
177 $(call cmd,fig2eps)
178
179quiet_cmd_fig2png = FIG2PNG $@
180 cmd_fig2png = fig2dev -Lpng $< $@
181
182%.png: %.fig
183 @(which fig2dev > /dev/null 2>&1) || \
184 (echo "*** You need to install transfig ***"; \
185 exit 1)
186 $(call cmd,fig2png)
187
188###
189# Rule to convert a .c file to inline XML documentation
190 gen_xml = :
191 quiet_gen_xml = echo ' GEN $@'
192silent_gen_xml = :
193%.xml: %.c
194 @$($(quiet)gen_xml)
195 @( \
196 echo "<programlisting>"; \
197 expand --tabs=8 < $< | \
198 sed -e "s/&/\\&/g" \
199 -e "s/</\\</g" \
200 -e "s/>/\\>/g"; \
201 echo "</programlisting>") > $@
202
203###
204# Help targets as used by the top-level makefile
205dochelp:
206 @echo ' Linux kernel internal documentation in different formats:'
207 @echo ' htmldocs - HTML'
208 @echo ' installmandocs - install man pages generated by mandocs'
209 @echo ' mandocs - man pages'
210 @echo ' pdfdocs - PDF'
211 @echo ' psdocs - Postscript'
212 @echo ' xmldocs - XML DocBook'
213
214###
215# Temporary files left by various tools
216clean-files := $(DOCBOOKS) \
217 $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
218 $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
219 $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
220 $(patsubst %.xml, %.log, $(DOCBOOKS)) \
221 $(patsubst %.xml, %.out, $(DOCBOOKS)) \
222 $(patsubst %.xml, %.ps, $(DOCBOOKS)) \
223 $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
224 $(patsubst %.xml, %.html, $(DOCBOOKS)) \
225 $(patsubst %.xml, %.9, $(DOCBOOKS)) \
226 $(C-procfs-example)
227
228clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
229
230# Declare the contents of the .PHONY variable as phony. We keep that
231# information in a variable se we can use it in if_changed and friends.
232
233.PHONY: $(PHONY)