Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.
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 9 DOCBOOKS := z8530book.xml \ 10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ 11 writing_usb_driver.xml networking.xml \ 12 kernel-api.xml filesystems.xml lsm.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 sh.xml regulator.xml w1.xml \ 16 writing_musb_glue_layer.xml iio.xml 17 18 ifeq ($(DOCBOOKS),) 19 20 # Skip DocBook build if the user explicitly requested no DOCBOOKS. 21 .DEFAULT: 22 @echo " SKIP DocBook $@ target (DOCBOOKS=\"\" specified)." 23 else 24 ifneq ($(SPHINXDIRS),) 25 26 # Skip DocBook build if the user explicitly requested a sphinx dir 27 .DEFAULT: 28 @echo " SKIP DocBook $@ target (SPHINXDIRS specified)." 29 else 30 31 32 ### 33 # The build process is as follows (targets): 34 # (xmldocs) [by docproc] 35 # file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto] 36 # +--> file.pdf (pdfdocs) [by db2pdf or xmlto] 37 # +--> DIR=file (htmldocs) [by xmlto] 38 # +--> man/ (mandocs) [by xmlto] 39 40 41 # for PDF and PS output you can choose between xmlto and docbook-utils tools 42 PDF_METHOD = $(prefer-db2x) 43 PS_METHOD = $(prefer-db2x) 44 45 46 targets += $(DOCBOOKS) 47 BOOKS := $(addprefix $(obj)/,$(DOCBOOKS)) 48 xmldocs: $(BOOKS) 49 sgmldocs: xmldocs 50 51 PS := $(patsubst %.xml, %.ps, $(BOOKS)) 52 psdocs: $(PS) 53 54 PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) 55 pdfdocs: $(PDF) 56 57 HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) 58 htmldocs: $(HTML) 59 $(call cmd,build_main_index) 60 61 MAN := $(patsubst %.xml, %.9, $(BOOKS)) 62 mandocs: $(MAN) 63 find $(obj)/man -name '*.9' | xargs gzip -nf 64 65 installmandocs: mandocs 66 mkdir -p /usr/local/man/man9/ 67 find $(obj)/man -name '*.9.gz' -printf '%h %f\n' | \ 68 sort -k 2 -k 1 | uniq -f 1 | sed -e 's: :/:' | \ 69 xargs install -m 644 -t /usr/local/man/man9/ 70 71 # no-op for the DocBook toolchain 72 epubdocs: 73 latexdocs: 74 75 ### 76 #External programs used 77 KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref 78 KERNELDOC = $(srctree)/scripts/kernel-doc 79 DOCPROC = $(objtree)/scripts/docproc 80 CHECK_LC_CTYPE = $(objtree)/scripts/check-lc_ctype 81 82 # Use a fixed encoding - UTF-8 if the C library has support built-in 83 # or ASCII if not 84 LC_CTYPE := $(call try-run, LC_CTYPE=C.UTF-8 $(CHECK_LC_CTYPE),C.UTF-8,C) 85 export LC_CTYPE 86 87 XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl 88 XMLTOFLAGS += --skip-validation 89 90 ### 91 # DOCPROC is used for two purposes: 92 # 1) To generate a dependency list for a .tmpl file 93 # 2) To preprocess a .tmpl file and call kernel-doc with 94 # appropriate parameters. 95 # The following rules are used to generate the .xml documentation 96 # required to generate the final targets. (ps, pdf, html). 97 quiet_cmd_docproc = DOCPROC $@ 98 cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@ 99 define rule_docproc 100 set -e; \ 101 $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \ 102 $(cmd_$(1)); \ 103 ( \ 104 echo 'cmd_$@ := $(cmd_$(1))'; \ 105 echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \ 106 ) > $(dir $@).$(notdir $@).cmd 107 endef 108 109 %.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE 110 $(call if_changed_rule,docproc) 111 112 # Tell kbuild to always build the programs 113 always := $(hostprogs-y) 114 115 notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \ 116 exit 1 117 db2xtemplate = db2TYPE -o $(dir $@) $< 118 xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $< 119 120 # determine which methods are available 121 ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found) 122 use-db2x = db2x 123 prefer-db2x = db2x 124 else 125 use-db2x = notfound 126 prefer-db2x = $(use-xmlto) 127 endif 128 ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found) 129 use-xmlto = xmlto 130 prefer-xmlto = xmlto 131 else 132 use-xmlto = notfound 133 prefer-xmlto = $(use-db2x) 134 endif 135 136 # the commands, generated from the chosen template 137 quiet_cmd_db2ps = PS $@ 138 cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template)) 139 %.ps : %.xml 140 $(call cmd,db2ps) 141 142 quiet_cmd_db2pdf = PDF $@ 143 cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template)) 144 %.pdf : %.xml 145 $(call cmd,db2pdf) 146 147 148 index = index.html 149 main_idx = $(obj)/$(index) 150 quiet_cmd_build_main_index = HTML $(main_idx) 151 cmd_build_main_index = rm -rf $(main_idx); \ 152 echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \ 153 echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \ 154 cat $(HTML) >> $(main_idx) 155 156 quiet_cmd_db2html = HTML $@ 157 cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ 158 echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ 159 $(patsubst %.html,%,$(notdir $@))</a><p>' > $@ 160 161 ### 162 # Rules to create an aux XML and .db, and use them to re-process the DocBook XML 163 # to fill internal hyperlinks 164 gen_aux_xml = : 165 quiet_gen_aux_xml = echo ' XMLREF $@' 166 silent_gen_aux_xml = : 167 %.aux.xml: %.xml 168 @$($(quiet)gen_aux_xml) 169 @rm -rf $@ 170 @(cat $< | egrep "^<refentry id" | egrep -o "\".*\"" | cut -f 2 -d \" > $<.db) 171 @$(KERNELDOCXMLREF) -db $<.db $< > $@ 172 .PRECIOUS: %.aux.xml 173 174 %.html: %.aux.xml 175 @(which xmlto > /dev/null 2>&1) || \ 176 (echo "*** You need to install xmlto ***"; \ 177 exit 1) 178 @rm -rf $@ $(patsubst %.html,%,$@) 179 $(call cmd,db2html) 180 @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ 181 cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi 182 183 quiet_cmd_db2man = MAN $@ 184 cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi 185 %.9 : %.xml 186 @(which xmlto > /dev/null 2>&1) || \ 187 (echo "*** You need to install xmlto ***"; \ 188 exit 1) 189 $(Q)mkdir -p $(obj)/man/$(*F) 190 $(call cmd,db2man) 191 @touch $@ 192 193 ### 194 # Rules to generate postscripts and PNG images from .fig format files 195 quiet_cmd_fig2eps = FIG2EPS $@ 196 cmd_fig2eps = fig2dev -Leps $< $@ 197 198 %.eps: %.fig 199 @(which fig2dev > /dev/null 2>&1) || \ 200 (echo "*** You need to install transfig ***"; \ 201 exit 1) 202 $(call cmd,fig2eps) 203 204 quiet_cmd_fig2png = FIG2PNG $@ 205 cmd_fig2png = fig2dev -Lpng $< $@ 206 207 %.png: %.fig 208 @(which fig2dev > /dev/null 2>&1) || \ 209 (echo "*** You need to install transfig ***"; \ 210 exit 1) 211 $(call cmd,fig2png) 212 213 ### 214 # Rule to convert a .c file to inline XML documentation 215 gen_xml = : 216 quiet_gen_xml = echo ' GEN $@' 217 silent_gen_xml = : 218 %.xml: %.c 219 @$($(quiet)gen_xml) 220 @( \ 221 echo "<programlisting>"; \ 222 expand --tabs=8 < $< | \ 223 sed -e "s/&/\\&/g" \ 224 -e "s/</\\</g" \ 225 -e "s/>/\\>/g"; \ 226 echo "</programlisting>") > $@ 227 228 endif # DOCBOOKS="" 229 endif # SPHINDIR=... 230 231 ### 232 # Help targets as used by the top-level makefile 233 dochelp: 234 @echo ' Linux kernel internal documentation in different formats (DocBook):' 235 @echo ' htmldocs - HTML' 236 @echo ' pdfdocs - PDF' 237 @echo ' psdocs - Postscript' 238 @echo ' xmldocs - XML DocBook' 239 @echo ' mandocs - man pages' 240 @echo ' installmandocs - install man pages generated by mandocs' 241 @echo ' cleandocs - clean all generated DocBook files' 242 @echo 243 @echo ' make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml' 244 @echo ' valid values for DOCBOOKS are: $(DOCBOOKS)' 245 @echo 246 @echo " make DOCBOOKS=\"\" [target] Don't generate docs from Docbook" 247 @echo ' This is useful to generate only the ReST docs (Sphinx)' 248 249 250 ### 251 # Temporary files left by various tools 252 clean-files := $(DOCBOOKS) \ 253 $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \ 254 $(patsubst %.xml, %.aux, $(DOCBOOKS)) \ 255 $(patsubst %.xml, %.tex, $(DOCBOOKS)) \ 256 $(patsubst %.xml, %.log, $(DOCBOOKS)) \ 257 $(patsubst %.xml, %.out, $(DOCBOOKS)) \ 258 $(patsubst %.xml, %.ps, $(DOCBOOKS)) \ 259 $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \ 260 $(patsubst %.xml, %.html, $(DOCBOOKS)) \ 261 $(patsubst %.xml, %.9, $(DOCBOOKS)) \ 262 $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ 263 $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ 264 $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ 265 $(patsubst %.xml, .%.xml.cmd, $(DOCBOOKS)) \ 266 $(index) 267 268 clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man 269 270 cleandocs: 271 $(Q)rm -f $(call objectify, $(clean-files)) 272 $(Q)rm -rf $(call objectify, $(clean-dirs)) 273 274 # Declare the contents of the .PHONY variable as phony. We keep that 275 # information in a variable se we can use it in if_changed and friends. 276 277 .PHONY: $(PHONY)