Makefile 8.55 KB
Newer Older
Linus Torvalds's avatar
Linus Torvalds committed
1 2 3 4
###
# 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
Adrian Bunk's avatar
Adrian Bunk committed
5
# to document the SRC - and how to read it.
Linus Torvalds's avatar
Linus Torvalds committed
6 7 8
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.

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
	    80211.xml debugobjects.xml sh.xml regulator.xml \
16
	    tracepoint.xml w1.xml \
17
	    writing_musb_glue_layer.xml crypto-API.xml iio.xml
18

19 20 21 22 23
ifeq ($(DOCBOOKS),)

# Skip DocBook build if the user explicitly requested no DOCBOOKS.
.DEFAULT:
	@echo "  SKIP    DocBook $@ target (DOCBOOKS=\"\" specified)."
24 25
else
ifneq ($(SPHINXDIRS),)
26

27 28 29
# Skip DocBook build if the user explicitly requested a sphinx dir
.DEFAULT:
	@echo "  SKIP    DocBook $@ target (SPHINXDIRS specified)."
30 31
else

32

Linus Torvalds's avatar
Linus Torvalds committed
33 34
###
# The build process is as follows (targets):
35 36 37 38 39
#              (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]
Linus Torvalds's avatar
Linus Torvalds committed
40

41 42 43 44 45 46

# for PDF and PS output you can choose between xmlto and docbook-utils tools
PDF_METHOD	= $(prefer-db2x)
PS_METHOD	= $(prefer-db2x)


47
targets += $(DOCBOOKS)
Linus Torvalds's avatar
Linus Torvalds committed
48
BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
49
xmldocs: $(BOOKS)
Linus Torvalds's avatar
Linus Torvalds committed
50 51 52 53 54 55 56 57
sgmldocs: xmldocs

PS := $(patsubst %.xml, %.ps, $(BOOKS))
psdocs: $(PS)

PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
pdfdocs: $(PDF)

58
HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
59
htmldocs: $(HTML)
60
	$(call cmd,build_main_index)
Linus Torvalds's avatar
Linus Torvalds committed
61 62 63

MAN := $(patsubst %.xml, %.9, $(BOOKS))
mandocs: $(MAN)
64
	find $(obj)/man -name '*.9' | xargs gzip -nf
Linus Torvalds's avatar
Linus Torvalds committed
65 66

installmandocs: mandocs
67
	mkdir -p /usr/local/man/man9/
68 69 70
	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/
Linus Torvalds's avatar
Linus Torvalds committed
71

72 73
# no-op for the DocBook toolchain
epubdocs:
74
latexdocs:
75

Linus Torvalds's avatar
Linus Torvalds committed
76 77
###
#External programs used
78 79 80
KERNELDOCXMLREF = $(srctree)/scripts/kernel-doc-xml-ref
KERNELDOC       = $(srctree)/scripts/kernel-doc
DOCPROC         = $(objtree)/scripts/docproc
81 82 83 84 85 86
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
87

88
XMLTOFLAGS = -m $(srctree)/$(src)/stylesheet.xsl
89
XMLTOFLAGS += --skip-validation
Linus Torvalds's avatar
Linus Torvalds committed
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109

###
# 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

110
%.xml: %.tmpl $(KERNELDOC) $(DOCPROC) $(KERNELDOCXMLREF) FORCE
Linus Torvalds's avatar
Linus Torvalds committed
111 112
	$(call if_changed_rule,docproc)

113 114 115
# Tell kbuild to always build the programs
always := $(hostprogs-y)

116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
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
Linus Torvalds's avatar
Linus Torvalds committed
136

137 138 139
# the commands, generated from the chosen template
quiet_cmd_db2ps = PS      $@
      cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
Linus Torvalds's avatar
Linus Torvalds committed
140 141 142
%.ps : %.xml
	$(call cmd,db2ps)

143
quiet_cmd_db2pdf = PDF     $@
144
      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
Linus Torvalds's avatar
Linus Torvalds committed
145 146 147
%.pdf : %.xml
	$(call cmd,db2pdf)

148

Randy Dunlap's avatar
Randy Dunlap committed
149
index = index.html
150
main_idx = $(obj)/$(index)
151 152
quiet_cmd_build_main_index = HTML    $(main_idx)
      cmd_build_main_index = rm -rf $(main_idx); \
153 154 155 156
		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
		   cat $(HTML) >> $(main_idx)

157
quiet_cmd_db2html = HTML    $@
158
      cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
159
		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
160
		$(patsubst %.html,%,$(notdir $@))</a><p>' > $@
Linus Torvalds's avatar
Linus Torvalds committed
161

162 163 164 165 166 167 168 169 170 171 172 173 174 175
###
# 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
176
	@(which xmlto > /dev/null 2>&1) || \
177
	 (echo "*** You need to install xmlto ***"; \
Linus Torvalds's avatar
Linus Torvalds committed
178 179 180 181 182 183
	  exit 1)
	@rm -rf $@ $(patsubst %.html,%,$@)
	$(call cmd,db2html)
	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi

184
quiet_cmd_db2man = MAN     $@
185
      cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man/$(*F) $< ; fi
186 187
%.9 : %.xml
	@(which xmlto > /dev/null 2>&1) || \
188
	 (echo "*** You need to install xmlto ***"; \
189
	  exit 1)
190
	$(Q)mkdir -p $(obj)/man/$(*F)
191 192
	$(call cmd,db2man)
	@touch $@
Linus Torvalds's avatar
Linus Torvalds committed
193 194

###
195
# Rules to generate postscripts and PNG images from .fig format files
Linus Torvalds's avatar
Linus Torvalds committed
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
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
216 217 218
       gen_xml = :
 quiet_gen_xml = echo '  GEN     $@'
silent_gen_xml = :
Linus Torvalds's avatar
Linus Torvalds committed
219
%.xml: %.c
220
	@$($(quiet)gen_xml)
Linus Torvalds's avatar
Linus Torvalds committed
221 222 223 224 225 226 227 228
	@(                            \
	   echo "<programlisting>";   \
	   expand --tabs=8 < $< |     \
	   sed -e "s/&/\\&amp;/g"     \
	       -e "s/</\\&lt;/g"      \
	       -e "s/>/\\&gt;/g";     \
	   echo "</programlisting>")  > $@

229
endif # DOCBOOKS=""
230
endif # SPHINDIR=...
231

Linus Torvalds's avatar
Linus Torvalds committed
232 233 234
###
# Help targets as used by the top-level makefile
dochelp:
235
	@echo  ' Linux kernel internal documentation in different formats (DocBook):'
236 237 238 239
	@echo  '  htmldocs        - HTML'
	@echo  '  pdfdocs         - PDF'
	@echo  '  psdocs          - Postscript'
	@echo  '  xmldocs         - XML DocBook'
Randy Dunlap's avatar
Randy Dunlap committed
240 241 242
	@echo  '  mandocs         - man pages'
	@echo  '  installmandocs  - install man pages generated by mandocs'
	@echo  '  cleandocs       - clean all generated DocBook files'
243
	@echo
244
	@echo  '  make DOCBOOKS="s1.xml s2.xml" [target] Generate only docs s1.xml s2.xml'
245
	@echo  '  valid values for DOCBOOKS are: $(DOCBOOKS)'
246
	@echo
247
	@echo  "  make DOCBOOKS=\"\" [target] Don't generate docs from Docbook"
248
	@echo  '     This is useful to generate only the ReST docs (Sphinx)'
249

Linus Torvalds's avatar
Linus Torvalds committed
250 251 252 253

###
# Temporary files left by various tools
clean-files := $(DOCBOOKS) \
254 255 256 257 258 259 260 261 262 263 264 265
	$(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)) \
266
	$(patsubst %.xml, .%.xml.cmd, $(DOCBOOKS)) \
267
	$(index)
Linus Torvalds's avatar
Linus Torvalds committed
268

269
clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
270

271
cleandocs:
Randy Dunlap's avatar
Randy Dunlap committed
272 273 274
	$(Q)rm -f $(call objectify, $(clean-files))
	$(Q)rm -rf $(call objectify, $(clean-dirs))

275 276 277 278
# 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)