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