Makefile 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224
  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. DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
  9. kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
  10. procfs-guide.xml writing_usb_driver.xml \
  11. kernel-api.xml filesystems.xml lsm.xml usb.xml \
  12. gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
  13. genericirq.xml
  14. ###
  15. # The build process is as follows (targets):
  16. # (xmldocs)
  17. # file.tmpl --> file.xml +--> file.ps (psdocs)
  18. # +--> file.pdf (pdfdocs)
  19. # +--> DIR=file (htmldocs)
  20. # +--> man/ (mandocs)
  21. # for PDF and PS output you can choose between xmlto and docbook-utils tools
  22. PDF_METHOD = $(prefer-db2x)
  23. PS_METHOD = $(prefer-db2x)
  24. ###
  25. # The targets that may be used.
  26. PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs
  27. BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
  28. xmldocs: $(BOOKS)
  29. sgmldocs: xmldocs
  30. PS := $(patsubst %.xml, %.ps, $(BOOKS))
  31. psdocs: $(PS)
  32. PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
  33. pdfdocs: $(PDF)
  34. HTML := $(patsubst %.xml, %.html, $(BOOKS))
  35. htmldocs: $(HTML)
  36. MAN := $(patsubst %.xml, %.9, $(BOOKS))
  37. mandocs: $(MAN)
  38. installmandocs: mandocs
  39. mkdir -p /usr/local/man/man9/
  40. install Documentation/DocBook/man/*.9.gz /usr/local/man/man9/
  41. ###
  42. #External programs used
  43. KERNELDOC = $(srctree)/scripts/kernel-doc
  44. DOCPROC = $(objtree)/scripts/basic/docproc
  45. XMLTOFLAGS = -m $(srctree)/Documentation/DocBook/stylesheet.xsl
  46. #XMLTOFLAGS += --skip-validation
  47. ###
  48. # DOCPROC is used for two purposes:
  49. # 1) To generate a dependency list for a .tmpl file
  50. # 2) To preprocess a .tmpl file and call kernel-doc with
  51. # appropriate parameters.
  52. # The following rules are used to generate the .xml documentation
  53. # required to generate the final targets. (ps, pdf, html).
  54. quiet_cmd_docproc = DOCPROC $@
  55. cmd_docproc = SRCTREE=$(srctree)/ $(DOCPROC) doc $< >$@
  56. define rule_docproc
  57. set -e; \
  58. $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
  59. $(cmd_$(1)); \
  60. ( \
  61. echo 'cmd_$@ := $(cmd_$(1))'; \
  62. echo $@: `SRCTREE=$(srctree) $(DOCPROC) depend $<`; \
  63. ) > $(dir $@).$(notdir $@).cmd
  64. endef
  65. %.xml: %.tmpl FORCE
  66. $(call if_changed_rule,docproc)
  67. ###
  68. #Read in all saved dependency files
  69. cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
  70. ifneq ($(cmd_files),)
  71. include $(cmd_files)
  72. endif
  73. ###
  74. # Changes in kernel-doc force a rebuild of all documentation
  75. $(BOOKS): $(KERNELDOC)
  76. ###
  77. # procfs guide uses a .c file as example code.
  78. # This requires an explicit dependency
  79. C-procfs-example = procfs_example.xml
  80. C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
  81. $(obj)/procfs-guide.xml: $(C-procfs-example2)
  82. notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
  83. exit 1
  84. db2xtemplate = db2TYPE -o $(dir $@) $<
  85. xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
  86. # determine which methods are available
  87. ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
  88. use-db2x = db2x
  89. prefer-db2x = db2x
  90. else
  91. use-db2x = notfound
  92. prefer-db2x = $(use-xmlto)
  93. endif
  94. ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
  95. use-xmlto = xmlto
  96. prefer-xmlto = xmlto
  97. else
  98. use-xmlto = notfound
  99. prefer-xmlto = $(use-db2x)
  100. endif
  101. # the commands, generated from the chosen template
  102. quiet_cmd_db2ps = PS $@
  103. cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
  104. %.ps : %.xml
  105. $(call cmd,db2ps)
  106. quiet_cmd_db2pdf = PDF $@
  107. cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
  108. %.pdf : %.xml
  109. $(call cmd,db2pdf)
  110. quiet_cmd_db2html = HTML $@
  111. cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
  112. echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
  113. Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
  114. %.html: %.xml
  115. @(which xmlto > /dev/null 2>&1) || \
  116. (echo "*** You need to install xmlto ***"; \
  117. exit 1)
  118. @rm -rf $@ $(patsubst %.html,%,$@)
  119. $(call cmd,db2html)
  120. @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
  121. cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
  122. quiet_cmd_db2man = MAN $@
  123. cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
  124. %.9 : %.xml
  125. @(which xmlto > /dev/null 2>&1) || \
  126. (echo "*** You need to install xmlto ***"; \
  127. exit 1)
  128. $(call cmd,db2man)
  129. @touch $@
  130. ###
  131. # Rules to generate postscripts and PNG imgages from .fig format files
  132. quiet_cmd_fig2eps = FIG2EPS $@
  133. cmd_fig2eps = fig2dev -Leps $< $@
  134. %.eps: %.fig
  135. @(which fig2dev > /dev/null 2>&1) || \
  136. (echo "*** You need to install transfig ***"; \
  137. exit 1)
  138. $(call cmd,fig2eps)
  139. quiet_cmd_fig2png = FIG2PNG $@
  140. cmd_fig2png = fig2dev -Lpng $< $@
  141. %.png: %.fig
  142. @(which fig2dev > /dev/null 2>&1) || \
  143. (echo "*** You need to install transfig ***"; \
  144. exit 1)
  145. $(call cmd,fig2png)
  146. ###
  147. # Rule to convert a .c file to inline XML documentation
  148. %.xml: %.c
  149. @echo ' GEN $@'
  150. @( \
  151. echo "<programlisting>"; \
  152. expand --tabs=8 < $< | \
  153. sed -e "s/&/\\&amp;/g" \
  154. -e "s/</\\&lt;/g" \
  155. -e "s/>/\\&gt;/g"; \
  156. echo "</programlisting>") > $@
  157. ###
  158. # Help targets as used by the top-level makefile
  159. dochelp:
  160. @echo ' Linux kernel internal documentation in different formats:'
  161. @echo ' htmldocs - HTML'
  162. @echo ' installmandocs - install man pages generated by mandocs'
  163. @echo ' mandocs - man pages'
  164. @echo ' pdfdocs - PDF'
  165. @echo ' psdocs - Postscript'
  166. @echo ' xmldocs - XML DocBook'
  167. ###
  168. # Temporary files left by various tools
  169. clean-files := $(DOCBOOKS) \
  170. $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
  171. $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
  172. $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
  173. $(patsubst %.xml, %.log, $(DOCBOOKS)) \
  174. $(patsubst %.xml, %.out, $(DOCBOOKS)) \
  175. $(patsubst %.xml, %.ps, $(DOCBOOKS)) \
  176. $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
  177. $(patsubst %.xml, %.html, $(DOCBOOKS)) \
  178. $(patsubst %.xml, %.9, $(DOCBOOKS)) \
  179. $(C-procfs-example)
  180. clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS))
  181. #man put files in man subdir - traverse down
  182. subdir- := man/
  183. # Declare the contents of the .PHONY variable as phony. We keep that
  184. # information in a variable se we can use it in if_changed and friends.
  185. .PHONY: $(PHONY)