Linux Audio

Check our new training course

Loading...
  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 device-drivers.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	    80211.xml debugobjects.xml sh.xml regulator.xml \
 16	    alsa-driver-api.xml writing-an-alsa-driver.xml \
 17	    tracepoint.xml drm.xml media_api.xml
 18
 19include $(srctree)/Documentation/DocBook/media/Makefile
 20
 21###
 22# The build process is as follows (targets):
 23#              (xmldocs) [by docproc]
 24# file.tmpl --> file.xml +--> file.ps   (psdocs)   [by db2ps or xmlto]
 25#                        +--> file.pdf  (pdfdocs)  [by db2pdf or xmlto]
 26#                        +--> DIR=file  (htmldocs) [by xmlto]
 27#                        +--> man      (mandocs)  [by xmlto]
 28
 29
 30# for PDF and PS output you can choose between xmlto and docbook-utils tools
 31PDF_METHOD	= $(prefer-db2x)
 32PS_METHOD	= $(prefer-db2x)
 33
 34
 35###
 36# The targets that may be used.
 37PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
 38
 39BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
 40xmldocs: $(BOOKS)
 41sgmldocs: xmldocs
 42
 43PS := $(patsubst %.xml, %.ps, $(BOOKS))
 44psdocs: $(PS)
 45
 46PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
 47pdfdocs: $(PDF)
 48
 49HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
 50htmldocs: $(HTML)
 51	$(call build_main_index)
 52	$(call build_images)
 53	$(call install_media_images)
 54
 55MAN := $(patsubst %.xml, %.9, $(BOOKS))
 56mandocs: $(MAN)
 57
 58installmandocs: mandocs
 59	mkdir -p /usr/local/man/man9/
 60	install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
 61
 62###
 63#External programs used
 64KERNELDOC = $(srctree)/scripts/kernel-doc
 65DOCPROC   = $(objtree)/scripts/docproc
 66
 67XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl
 68XMLTOFLAGS += --skip-validation
 69
 70###
 71# DOCPROC is used for two purposes:
 72# 1) To generate a dependency list for a .tmpl file
 73# 2) To preprocess a .tmpl file and call kernel-doc with
 74#     appropriate parameters.
 75# The following rules are used to generate the .xml documentation
 76# required to generate the final targets. (ps, pdf, html).
 77quiet_cmd_docproc = DOCPROC $@
 78      cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
 79define rule_docproc
 80	set -e;								\
 81        $(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';) 	\
 82        $(cmd_$(1)); 							\
 83        ( 								\
 84          echo 'cmd_$@ := $(cmd_$(1))'; 				\
 85          echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; 		\
 86        ) > $(dir $@).$(notdir $@).cmd
 87endef
 88
 89%.xml: %.tmpl FORCE
 90	$(call if_changed_rule,docproc)
 91
 92###
 93#Read in all saved dependency files
 94cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
 95
 96ifneq ($(cmd_files),)
 97  include $(cmd_files)
 98endif
 99
100###
101# Changes in kernel-doc force a rebuild of all documentation
102$(BOOKS): $(KERNELDOC)
103
104# Tell kbuild to always build the programs
105always := $(hostprogs-y)
106
107notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
108		   exit 1
109db2xtemplate = db2TYPE -o $(dir $@) $<
110xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
111
112# determine which methods are available
113ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
114	use-db2x = db2x
115	prefer-db2x = db2x
116else
117	use-db2x = notfound
118	prefer-db2x = $(use-xmlto)
119endif
120ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
121	use-xmlto = xmlto
122	prefer-xmlto = xmlto
123else
124	use-xmlto = notfound
125	prefer-xmlto = $(use-db2x)
126endif
127
128# the commands, generated from the chosen template
129quiet_cmd_db2ps = PS      $@
130      cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
131%.ps : %.xml
132	$(call cmd,db2ps)
133
134quiet_cmd_db2pdf = PDF     $@
135      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
136%.pdf : %.xml
137	$(call cmd,db2pdf)
138
139
140index = index.html
141main_idx = Documentation/DocBook/$(index)
142build_main_index = rm -rf $(main_idx); \
143		   echo '<h1>Linux Kernel HTML Documentation</h1>' >> $(main_idx) && \
144		   echo '<h2>Kernel Version: $(KERNELVERSION)</h2>' >> $(main_idx) && \
145		   cat $(HTML) >> $(main_idx)
146
147quiet_cmd_db2html = HTML    $@
148      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
149		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
150        $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
151
152%.html:	%.xml
153	@(which xmlto > /dev/null 2>&1) || \
154	 (echo "*** You need to install xmlto ***"; \
155	  exit 1)
156	@rm -rf $@ $(patsubst %.html,%,$@)
157	$(call cmd,db2html)
158	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
159            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
160
161quiet_cmd_db2man = MAN     $@
162      cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
163%.9 : %.xml
164	@(which xmlto > /dev/null 2>&1) || \
165	 (echo "*** You need to install xmlto ***"; \
166	  exit 1)
167	$(Q)mkdir -p $(obj)/man
168	$(call cmd,db2man)
169	@touch $@
170
171###
172# Rules to generate postscripts and PNG images from .fig format files
173quiet_cmd_fig2eps = FIG2EPS $@
174      cmd_fig2eps = fig2dev -Leps $< $@
175
176%.eps: %.fig
177	@(which fig2dev > /dev/null 2>&1) || \
178	 (echo "*** You need to install transfig ***"; \
179	  exit 1)
180	$(call cmd,fig2eps)
181
182quiet_cmd_fig2png = FIG2PNG $@
183      cmd_fig2png = fig2dev -Lpng $< $@
184
185%.png: %.fig
186	@(which fig2dev > /dev/null 2>&1) || \
187	 (echo "*** You need to install transfig ***"; \
188	  exit 1)
189	$(call cmd,fig2png)
190
191###
192# Rule to convert a .c file to inline XML documentation
193       gen_xml = :
194 quiet_gen_xml = echo '  GEN     $@'
195silent_gen_xml = :
196%.xml: %.c
197	@$($(quiet)gen_xml)
198	@(                            \
199	   echo "<programlisting>";   \
200	   expand --tabs=8 < $< |     \
201	   sed -e "s/&/\\&amp;/g"     \
202	       -e "s/</\\&lt;/g"      \
203	       -e "s/>/\\&gt;/g";     \
204	   echo "</programlisting>")  > $@
205
206###
207# Help targets as used by the top-level makefile
208dochelp:
209	@echo  ' Linux kernel internal documentation in different formats:'
210	@echo  '  htmldocs        - HTML'
211	@echo  '  pdfdocs         - PDF'
212	@echo  '  psdocs          - Postscript'
213	@echo  '  xmldocs         - XML DocBook'
214	@echo  '  mandocs         - man pages'
215	@echo  '  installmandocs  - install man pages generated by mandocs'
216	@echo  '  cleandocs       - clean all generated DocBook files'
217
218###
219# Temporary files left by various tools
220clean-files := $(DOCBOOKS) \
221	$(patsubst %.xml, %.dvi,  $(DOCBOOKS)) \
222	$(patsubst %.xml, %.aux,  $(DOCBOOKS)) \
223	$(patsubst %.xml, %.tex,  $(DOCBOOKS)) \
224	$(patsubst %.xml, %.log,  $(DOCBOOKS)) \
225	$(patsubst %.xml, %.out,  $(DOCBOOKS)) \
226	$(patsubst %.xml, %.ps,   $(DOCBOOKS)) \
227	$(patsubst %.xml, %.pdf,  $(DOCBOOKS)) \
228	$(patsubst %.xml, %.html, $(DOCBOOKS)) \
229	$(patsubst %.xml, %.9,    $(DOCBOOKS)) \
230	$(index)
231
232clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
233
234cleandocs: cleanmediadocs
235	$(Q)rm -f $(call objectify, $(clean-files))
236	$(Q)rm -rf $(call objectify, $(clean-dirs))
237
238# Declare the contents of the .PHONY variable as phony.  We keep that
239# information in a variable se we can use it in if_changed and friends.
240
241.PHONY: $(PHONY)