Makefile 6.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 9
# To add a new book the only step required is to add the book to the
# list of DOCBOOKS.

DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \
10
	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
11
	    procfs-guide.xml writing_usb_driver.xml \
12
	    kernel-api.xml filesystems.xml lsm.xml usb.xml \
13 14
	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
	    genericirq.xml
L
Linus Torvalds 已提交
15 16 17 18 19 20 21 22 23

###
# The build process is as follows (targets):
#              (xmldocs)
# file.tmpl --> file.xml +--> file.ps   (psdocs)
#                        +--> file.pdf  (pdfdocs)
#                        +--> DIR=file  (htmldocs)
#                        +--> man/      (mandocs)

24 25 26 27 28 29

# 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 已提交
30 31
###
# The targets that may be used.
32
PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs
L
Linus Torvalds 已提交
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50

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

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

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

HTML := $(patsubst %.xml, %.html, $(BOOKS))
htmldocs: $(HTML)

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

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

###
#External programs used
KERNELDOC = scripts/kernel-doc
DOCPROC   = scripts/basic/docproc
58

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

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

103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122
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 已提交
123

124 125 126
# the commands, generated from the chosen template
quiet_cmd_db2ps = PS      $@
      cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
L
Linus Torvalds 已提交
127 128 129
%.ps : %.xml
	$(call cmd,db2ps)

130 131
quiet_cmd_db2pdf = PDF      $@
      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
L
Linus Torvalds 已提交
132 133 134
%.pdf : %.xml
	$(call cmd,db2pdf)

135
quiet_cmd_db2html = HTML   $@
136
      cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
M
Martin Waitz 已提交
137
		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
L
Linus Torvalds 已提交
138 139 140
         Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@

%.html:	%.xml
141
	@(which xmlto > /dev/null 2>&1) || \
142
	 (echo "*** You need to install xmlto ***"; \
L
Linus Torvalds 已提交
143 144 145 146 147 148
	  exit 1)
	@rm -rf $@ $(patsubst %.html,%,$@)
	$(call cmd,db2html)
	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi

149
quiet_cmd_db2man = MAN     $@
150 151 152
      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) || \
153
	 (echo "*** You need to install xmlto ***"; \
154 155 156
	  exit 1)
	$(call cmd,db2man)
	@touch $@
L
Linus Torvalds 已提交
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192

###
# Rules to generate postscripts and PNG imgages from .fig format files
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
%.xml: %.c
	@echo '  GEN     $@'
	@(                            \
	   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:
193 194 195 196 197 198 199
	@echo  ' Linux kernel internal documentation in different formats:'
	@echo  '  htmldocs        - HTML'
	@echo  '  installmandocs  - install man pages generated by mandocs'
	@echo  '  mandocs         - man pages'
	@echo  '  pdfdocs         - PDF'
	@echo  '  psdocs          - Postscript'
	@echo  '  xmldocs         - XML DocBook'
L
Linus Torvalds 已提交
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218

###
# 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)) \
	$(C-procfs-example)

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

#man put files in man subdir - traverse down
subdir- := man/
219 220 221 222 223 224


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