Makefile 7.5 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.
R
Randy Dunlap 已提交
35
PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
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)))
L
Linus Torvalds 已提交
48
htmldocs: $(HTML)
49
	$(call build_main_index)
L
Linus Torvalds 已提交
50 51 52 53 54

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

installmandocs: mandocs
55 56
	mkdir -p /usr/local/man/man9/
	install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
L
Linus Torvalds 已提交
57 58 59

###
#External programs used
60 61
KERNELDOC = $(srctree)/scripts/kernel-doc
DOCPROC   = $(objtree)/scripts/basic/docproc
62

J
Jiri Slaby 已提交
63
XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl
64
#XMLTOFLAGS += --skip-validation
L
Linus Torvalds 已提交
65 66 67 68 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

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

107 108 109 110 111 112 113
# 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)

114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
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 已提交
134

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

141
quiet_cmd_db2pdf = PDF     $@
142
      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
L
Linus Torvalds 已提交
143 144 145
%.pdf : %.xml
	$(call cmd,db2pdf)

146

R
Randy Dunlap 已提交
147 148
index = index.html
main_idx = Documentation/DocBook/$(index)
149 150 151 152 153
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)

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

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

168
quiet_cmd_db2man = MAN     $@
169 170 171
      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) || \
172
	 (echo "*** You need to install xmlto ***"; \
173
	  exit 1)
174
	$(Q)mkdir -p $(obj)/man
175 176
	$(call cmd,db2man)
	@touch $@
L
Linus Torvalds 已提交
177 178

###
S
Simon Arlott 已提交
179
# Rules to generate postscripts and PNG images from .fig format files
L
Linus Torvalds 已提交
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199
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
200 201 202
       gen_xml = :
 quiet_gen_xml = echo '  GEN     $@'
silent_gen_xml = :
L
Linus Torvalds 已提交
203
%.xml: %.c
204
	@$($(quiet)gen_xml)
L
Linus Torvalds 已提交
205 206 207 208 209 210 211 212 213 214 215
	@(                            \
	   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:
216 217 218 219 220
	@echo  ' Linux kernel internal documentation in different formats:'
	@echo  '  htmldocs        - HTML'
	@echo  '  pdfdocs         - PDF'
	@echo  '  psdocs          - Postscript'
	@echo  '  xmldocs         - XML DocBook'
R
Randy Dunlap 已提交
221 222 223
	@echo  '  mandocs         - man pages'
	@echo  '  installmandocs  - install man pages generated by mandocs'
	@echo  '  cleandocs       - clean all generated DocBook files'
L
Linus Torvalds 已提交
224 225 226 227 228 229 230 231 232 233 234 235 236

###
# 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 已提交
237
	$(C-procfs-example) $(index)
L
Linus Torvalds 已提交
238

239
clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
240

R
Randy Dunlap 已提交
241 242 243 244
cleandocs:
	$(Q)rm -f $(call objectify, $(clean-files))
	$(Q)rm -rf $(call objectify, $(clean-dirs))

245 246 247 248
# 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)