Makefile 7.7 KB
Newer Older
L
Linus Torvalds 已提交
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
A
Adrian Bunk 已提交
5
# to document the SRC - and how to read it.
L
Linus Torvalds 已提交
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 mcabook.xml device-drivers.xml \
10
	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11
	    procfs-guide.xml writing_usb_driver.xml networking.xml \
J
Jason Wessel 已提交
12
	    kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
13
	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
J
Johannes Berg 已提交
14
	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15
	    mac80211.xml debugobjects.xml sh.xml regulator.xml \
16
	    alsa-driver-api.xml writing-an-alsa-driver.xml \
17
	    tracepoint.xml media.xml
L
Linus Torvalds 已提交
18 19 20

###
# The build process is as follows (targets):
21 22 23 24 25
#              (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]
L
Linus Torvalds 已提交
26

27 28 29 30 31 32

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


L
Linus Torvalds 已提交
33 34
###
# The targets that may be used.
35
PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs media
L
Linus Torvalds 已提交
36 37 38 39 40 41 42 43 44 45 46

BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
xmldocs: $(BOOKS)
sgmldocs: xmldocs

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

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

47
HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
48
htmldocs: media $(HTML)
49
	$(call build_main_index)
L
Linus Torvalds 已提交
50 51 52 53

MAN := $(patsubst %.xml, %.9, $(BOOKS))
mandocs: $(MAN)

54 55 56 57
media:
	mkdir -p $(srctree)/Documentation/DocBook/media/
	cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(srctree)/Documentation/DocBook/media/

L
Linus Torvalds 已提交
58
installmandocs: mandocs
59 60
	mkdir -p /usr/local/man/man9/
	install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
L
Linus Torvalds 已提交
61 62 63

###
#External programs used
64 65
KERNELDOC = $(srctree)/scripts/kernel-doc
DOCPROC   = $(objtree)/scripts/basic/docproc
66

J
Jiri Slaby 已提交
67
XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl
68
#XMLTOFLAGS += --skip-validation
L
Linus Torvalds 已提交
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110

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

%.xml: %.tmpl FORCE
	$(call if_changed_rule,docproc)

###
#Read in all saved dependency files 
cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))

ifneq ($(cmd_files),)
  include $(cmd_files)
endif

###
# Changes in kernel-doc force a rebuild of all documentation
$(BOOKS): $(KERNELDOC)

###
# procfs guide uses a .c file as example code.
# This requires an explicit dependency
C-procfs-example = procfs_example.xml
C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
$(obj)/procfs-guide.xml: $(C-procfs-example2)

111 112 113 114 115 116 117
# List of programs to build
##oops, this is a kernel module::hostprogs-y := procfs_example
obj-m += procfs_example.o

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

118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
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
L
Linus Torvalds 已提交
138

139 140 141
# the commands, generated from the chosen template
quiet_cmd_db2ps = PS      $@
      cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
L
Linus Torvalds 已提交
142 143 144
%.ps : %.xml
	$(call cmd,db2ps)

145
quiet_cmd_db2pdf = PDF     $@
146
      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
L
Linus Torvalds 已提交
147 148 149
%.pdf : %.xml
	$(call cmd,db2pdf)

150

R
Randy Dunlap 已提交
151 152
index = index.html
main_idx = Documentation/DocBook/$(index)
153 154 155 156 157
build_main_index = rm -rf $(main_idx) && \
		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
		   cat $(HTML) >> $(main_idx)

158
quiet_cmd_db2html = HTML    $@
159
      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
M
Martin Waitz 已提交
160
		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
161
        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
L
Linus Torvalds 已提交
162 163

%.html:	%.xml
164
	@(which xmlto > /dev/null 2>&1) || \
165
	 (echo "*** You need to install xmlto ***"; \
L
Linus Torvalds 已提交
166 167 168 169 170 171
	  exit 1)
	@rm -rf $@ $(patsubst %.html,%,$@)
	$(call cmd,db2html)
	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi

172
quiet_cmd_db2man = MAN     $@
173 174 175
      cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
%.9 : %.xml
	@(which xmlto > /dev/null 2>&1) || \
176
	 (echo "*** You need to install xmlto ***"; \
177
	  exit 1)
178
	$(Q)mkdir -p $(obj)/man
179 180
	$(call cmd,db2man)
	@touch $@
L
Linus Torvalds 已提交
181 182

###
S
Simon Arlott 已提交
183
# Rules to generate postscripts and PNG images from .fig format files
L
Linus Torvalds 已提交
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
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
204 205 206
       gen_xml = :
 quiet_gen_xml = echo '  GEN     $@'
silent_gen_xml = :
L
Linus Torvalds 已提交
207
%.xml: %.c
208
	@$($(quiet)gen_xml)
L
Linus Torvalds 已提交
209 210 211 212 213 214 215 216 217 218 219
	@(                            \
	   echo "<programlisting>";   \
	   expand --tabs=8 < $< |     \
	   sed -e "s/&/\\&amp;/g"     \
	       -e "s/</\\&lt;/g"      \
	       -e "s/>/\\&gt;/g";     \
	   echo "</programlisting>")  > $@

###
# Help targets as used by the top-level makefile
dochelp:
220 221 222 223 224
	@echo  ' Linux kernel internal documentation in different formats:'
	@echo  '  htmldocs        - HTML'
	@echo  '  pdfdocs         - PDF'
	@echo  '  psdocs          - Postscript'
	@echo  '  xmldocs         - XML DocBook'
R
Randy Dunlap 已提交
225 226 227
	@echo  '  mandocs         - man pages'
	@echo  '  installmandocs  - install man pages generated by mandocs'
	@echo  '  cleandocs       - clean all generated DocBook files'
L
Linus Torvalds 已提交
228 229 230 231 232 233 234 235 236 237 238 239 240

###
# Temporary files left by various tools
clean-files := $(DOCBOOKS) \
	$(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)) \
R
Randy Dunlap 已提交
241
	$(C-procfs-example) $(index)
L
Linus Torvalds 已提交
242

243
clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
244

R
Randy Dunlap 已提交
245 246 247 248
cleandocs:
	$(Q)rm -f $(call objectify, $(clean-files))
	$(Q)rm -rf $(call objectify, $(clean-dirs))

249 250 251 252
# 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)