Makefile 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229
  1. ###
  2. # This makefile is used to generate the kernel documentation,
  3. # primarily based on in-line comments in various source files.
  4. # See doc/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. include $(TOPDIR)/config.mk
  9. DOCBOOKS := fs.xml linker_lists.xml stdio.xml
  10. ###
  11. # The build process is as follows (targets):
  12. # (xmldocs) [by docproc]
  13. # file.tmpl --> file.xml +--> file.ps (psdocs) [by db2ps or xmlto]
  14. # +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
  15. # +--> DIR=file (htmldocs) [by xmlto]
  16. # +--> man/ (mandocs) [by xmlto]
  17. # for PDF and PS output you can choose between xmlto and docbook-utils tools
  18. PDF_METHOD = $(prefer-db2x)
  19. PS_METHOD = $(prefer-db2x)
  20. ###
  21. # The targets that may be used.
  22. PHONY += $(obj).depend xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs cleandocs
  23. BOOKS := $(addprefix $(OBJTREE)/doc/DocBook/,$(DOCBOOKS))
  24. xmldocs: $(BOOKS)
  25. sgmldocs: xmldocs
  26. PS := $(patsubst %.xml, %.ps, $(BOOKS))
  27. psdocs: $(PS)
  28. PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
  29. pdfdocs: $(PDF)
  30. HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
  31. htmldocs: $(HTML)
  32. $(call build_main_index)
  33. $(call build_images)
  34. $(call install_media_images)
  35. MAN := $(patsubst %.xml, %.9, $(BOOKS))
  36. mandocs: $(MAN)
  37. installmandocs: mandocs
  38. mkdir -p /usr/local/man/man9/
  39. install doc/DocBook/man/*.9.gz /usr/local/man/man9/
  40. ###
  41. #External programs used
  42. KERNELDOC = $(SRCTREE)/tools/kernel-doc/kernel-doc
  43. DOCPROC = $(OBJTREE)/tools/kernel-doc/docproc
  44. XMLTOFLAGS = -m $(SRCTREE)/doc/DocBook/stylesheet.xsl
  45. XMLTOFLAGS += --skip-validation
  46. ###
  47. # DOCPROC is used for two purposes:
  48. # 1) To generate a dependency list for a .tmpl file
  49. # 2) To preprocess a .tmpl file and call kernel-doc with
  50. # appropriate parameters.
  51. # The following rules are used to generate the .xml documentation
  52. # required to generate the final targets. (ps, pdf, html).
  53. %.xml: %.tmpl
  54. $(DOCPROC) doc $< >$@
  55. ifeq ($@, "cleandocs")
  56. sinclude $(obj).depend
  57. $(obj).depend: $(patsubst %.xml, %.tmpl, $(DOCBOOKS))
  58. rm -f $(obj).depend ; \
  59. touch $(obj).depend ; \
  60. for file in $^ ; do \
  61. xmlfile=`echo "$${file}" | \
  62. sed "s/tmpl$$/xml/"` ; \
  63. echo -n "$${xmlfile}: ">> $(obj).depend ; \
  64. $(DOCPROC) depend $$file >> $(obj).depend ; \
  65. echo -e "\n\t$(DOCPROC) doc $< >$${xmlfile} " >> \
  66. $(obj).depend ; \
  67. done
  68. endif
  69. ###
  70. # Changes in kernel-doc force a rebuild of all documentation
  71. $(BOOKS): $(KERNELDOC)
  72. notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
  73. exit 1
  74. db2xtemplate = db2TYPE -o $(dir $@) $<
  75. xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
  76. # determine which methods are available
  77. ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
  78. use-db2x = db2x
  79. prefer-db2x = db2x
  80. else
  81. use-db2x = notfound
  82. prefer-db2x = $(use-xmlto)
  83. endif
  84. ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
  85. use-xmlto = xmlto
  86. prefer-xmlto = xmlto
  87. else
  88. use-xmlto = notfound
  89. prefer-xmlto = $(use-db2x)
  90. endif
  91. # the commands, generated from the chosen template
  92. quiet_cmd_db2ps = PS $@
  93. cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
  94. %.ps : %.xml
  95. $(call cmd_db2ps)
  96. quiet_cmd_db2pdf = PDF $@
  97. cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
  98. %.pdf : %.xml
  99. $(call cmd_db2pdf)
  100. index = index.html
  101. main_idx = $(index)
  102. build_main_index = rm -rf $(main_idx); \
  103. echo '<h1>U-Boot Bootloader HTML Documentation</h1>' >> $(main_idx) && \
  104. echo '<h2>U-Boot Version: $(U_BOOT_VERSION)</h2>' >> $(main_idx) && \
  105. cat $(HTML) >> $(main_idx)
  106. # To work around bug [1] in docbook-xsl-stylesheets 1.76.1 , generate only html
  107. # docs instead of xhtml with xmlto.
  108. # [1] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=654338
  109. quiet_cmd_db2html = HTML $@
  110. cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
  111. echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
  112. $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
  113. %.html: %.xml
  114. @(which xmlto > /dev/null 2>&1) || \
  115. (echo "*** You need to install xmlto ***"; \
  116. exit 1)
  117. @rm -rf $@ $(patsubst %.html,%,$@)
  118. $(call cmd_db2html)
  119. @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
  120. cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
  121. quiet_cmd_db2man = MAN $@
  122. cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
  123. %.9 : %.xml
  124. @(which xmlto > /dev/null 2>&1) || \
  125. (echo "*** You need to install xmlto ***"; \
  126. exit 1)
  127. $(Q)mkdir -p $(obj)man
  128. $(call cmd_db2man)
  129. @touch $@
  130. ###
  131. # Rules to generate postscripts and PNG images 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. gen_xml = :
  149. quiet_gen_xml = echo ' GEN $@'
  150. silent_gen_xml = :
  151. %.xml: %.c
  152. @$($(quiet)gen_xml)
  153. @( \
  154. echo "<programlisting>"; \
  155. expand --tabs=8 < $< | \
  156. sed -e "s/&/\\&amp;/g" \
  157. -e "s/</\\&lt;/g" \
  158. -e "s/>/\\&gt;/g"; \
  159. echo "</programlisting>") > $@
  160. ###
  161. # Help targets as used by the top-level makefile
  162. dochelp:
  163. @echo ' U-Boot bootloader internal documentation in different formats:'
  164. @echo ' htmldocs - HTML'
  165. @echo ' pdfdocs - PDF'
  166. @echo ' psdocs - Postscript'
  167. @echo ' xmldocs - XML DocBook'
  168. @echo ' mandocs - man pages'
  169. @echo ' installmandocs - install man pages generated by mandocs'
  170. @echo ' cleandocs - clean all generated DocBook files'
  171. ###
  172. # Temporary files left by various tools
  173. clean-files := $(DOCBOOKS) \
  174. $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
  175. $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
  176. $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
  177. $(patsubst %.xml, %.log, $(DOCBOOKS)) \
  178. $(patsubst %.xml, %.out, $(DOCBOOKS)) \
  179. $(patsubst %.xml, %.ps, $(DOCBOOKS)) \
  180. $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
  181. $(patsubst %.xml, %.html, $(DOCBOOKS)) \
  182. $(patsubst %.xml, %.9, $(DOCBOOKS)) \
  183. $(index)
  184. clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
  185. cleandocs:
  186. @rm -f $(obj).depend
  187. @$(Q)rm -f $(call objectify, $(clean-files))
  188. @$(Q)rm -rf $(call objectify, $(clean-dirs))
  189. # Declare the contents of the .PHONY variable as phony. We keep that
  190. # information in a variable se we can use it in if_changed and friends.
  191. .PHONY: $(PHONY)