summaryrefslogtreecommitdiffstats
path: root/documentation/Makefile
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/Makefile')
-rw-r--r--documentation/Makefile395
1 files changed, 395 insertions, 0 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
new file mode 100644
index 0000000000..3bc9a213ee
--- /dev/null
+++ b/documentation/Makefile
@@ -0,0 +1,395 @@
1# This is a single Makefile to handle all generated Yocto Project documents.
2# The Makefile needs to live in the documents directory and all figures used
3# in any manuals must be .PNG files and live in the individual book's figures
4# directory as well as in the figures directory for the mega-manual.
5# Note that the figures for the Yocto Project Development Manual
6# differ depending on the BRANCH being built.
7#
8# The Makefile has these targets:
9#
10# pdf: generates a PDF version of a manual. Not valid for the Quick Start
11# or the mega-manual (single, large HTML file comprised of all
12# Yocto Project manuals).
13# html: generates an HTML version of a manual.
14# eclipse: generates an HTML version of a manual that can be used as
15# eclipse help (including necessary metadata files).
16# tarball: creates a tarball for the doc files.
17# validate: validates
18# publish: pushes generated files to the Yocto Project website
19# clean: removes files
20#
21# The Makefile generates an HTML and PDF version of every document except the
22# Yocto Project Quick Start and the single, HTML mega-manual, which is comprised
23# of all the individual Yocto Project manuals. These two manuals are in HTML
24# form only. The variable DOC indicates the folder name for a given manual. The
25# variable VER represents the distro version of the Yocto Release for which the
26# manuals are being generated. The variable BRANCH is used to indicate the
27# branch (edison or denzil) and is used only when DOC=dev-manual or
28# DOC=mega-manual. If you do not specify a BRANCH, the default branch used
29# will be for the latest Yocto Project release. If you build for either
30# edison or denzil, you must use BRANCH. You do not need to use BRANCH for
31# any release beyond denzil.
32#
33# To build a manual, you must invoke Makefile with the DOC argument. If you
34# are going to publish the manual, then you must invoke Makefile with both the
35# DOC and the VER argument. Furthermore, if you are building or publishing
36# the edison or denzil versions of the Yocto Poject Development Manual or
37# the mega-manual, you must also use the BRANCH argument.
38#
39# Examples:
40#
41# make DOC=bsp-guide
42# make DOC=yocto-project-qs
43# make pdf DOC=ref-manual
44# make DOC=dev-manual BRANCH=edison
45# make DOC=mega-manual BRANCH=denzil
46#
47# The first example generates the HTML and PDF versions of the BSP Guide.
48# The second example generates the HTML version only of the Quick Start. Note that
49# the Quick Start only has an HTML version available. The third example generates
50# both the PDF and HTML versions of the Yocto Project Reference Manual. The
51# fourth example generates both the PDF and HTML 'edison' versions of the YP
52# Development Manual. The last exmample generates the HTML version of the
53# mega-manual and uses the 'denzil' branch when choosing figures for the
54# tarball of figures. Any example that does not use the BRANCH argument
55# builds the current version of the manual set.
56#
57# Use the publish target to push the generated manuals to the Yocto Project
58# website. All files needed for the manual's HTML form are pushed as well as the
59# PDF version (if applicable).
60# Examples:
61#
62# make publish DOC=bsp-guide VER=1.3
63# make publish DOC=adt-manual VER=1.3
64# make publish DOC=dev-manual VER=1.1.1 BRANCH=edison
65# make publish DOC=dev-manual VER=1.2 BRANCH=denzil
66#
67# The first example publishes the 1.3 version of both the PDF and HTML versions of
68# the BSP Guide. The second example publishes the 1.3 version of both the PDF and
69# HTML versions of the ADT Manual. The third example publishes the PDF and HTML
70# 'edison' versions of the YP Development Manual. The fourth example publishes
71# the PDF and HTML 'denzil' versions of the YP Development Manual.
72#
73
74ifeq ($(DOC),bsp-guide)
75XSLTOPTS = --xinclude
76ALLPREQ = html pdf eclipse tarball
77TARFILES = bsp-style.css bsp-guide.html bsp-guide.pdf figures/bsp-title.png \
78 eclipse
79MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
80FIGURES = figures
81STYLESHEET = $(DOC)/*.css
82
83endif
84
85ifeq ($(DOC),dev-manual)
86XSLTOPTS = --xinclude
87ALLPREQ = html pdf eclipse tarball
88#
89# Note that the tarfile might produce the "Cannot stat: No such file or directory" error
90# message for .PNG files that are not present when building a particular branch. The
91# list of files is all-inclusive for all branches. Note, if you don't provide a BRANCH
92# option, it defaults to the latest stuff. This would be appropriate for "master" branch.
93#
94
95 ifeq ($(BRANCH),edison)
96TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
97 figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
98 figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
99 figures/kernel-example-repos-edison.png \
100 figures/kernel-overview-1.png figures/kernel-overview-2.png \
101 figures/kernel-overview-3-edison.png \
102 figures/source-repos.png figures/yp-download.png \
103 figures/wip.png
104 else ifeq ($(BRANCH),denzil)
105TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
106 figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
107 figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
108 figures/kernel-example-repos-denzil.png \
109 figures/kernel-overview-1.png figures/kernel-overview-2.png \
110 figures/kernel-overview-3-denzil.png \
111 figures/source-repos.png figures/yp-download.png \
112 figures/wip.png
113 else
114TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
115 figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
116 figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
117 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
118 figures/source-repos.png figures/yp-download.png figures/recipe-workflow.png \
119 eclipse
120 endif
121
122MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
123FIGURES = figures
124STYLESHEET = $(DOC)/*.css
125
126endif
127
128ifeq ($(DOC),yocto-project-qs)
129XSLTOPTS = --xinclude
130ALLPREQ = html eclipse tarball
131TARFILES = yocto-project-qs.html qs-style.css figures/yocto-environment.png \
132 figures/building-an-image.png figures/using-a-pre-built-image.png \
133 figures/yocto-project-transp.png \
134 eclipse
135MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
136FIGURES = figures
137STYLESHEET = $(DOC)/*.css
138endif
139
140ifeq ($(DOC),mega-manual)
141XSLTOPTS = --stringparam html.stylesheet mega-style.css \
142 --stringparam chapter.autolabel 1 \
143 --stringparam section.autolabel 1 \
144 --stringparam section.label.includes.component.label 1 \
145 --xinclude
146ALLPREQ = html tarball
147
148 ifeq ($(BRANCH),edison)
149TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \
150 figures/using-a-pre-built-image.png \
151 figures/poky-title.png \
152 figures/adt-title.png figures/bsp-title.png \
153 figures/kernel-title.png figures/kernel-architecture-overview.png \
154 figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
155 figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
156 figures/kernel-example-repos-edison.png \
157 figures/kernel-overview-1.png figures/kernel-overview-2.png \
158 figures/kernel-overview-3-edison.png \
159 figures/source-repos.png figures/yp-download.png \
160 figures/wip.png
161 else ifeq ($(BRANCH),denzil)
162TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \
163 figures/using-a-pre-built-image.png \
164 figures/poky-title.png \
165 figures/adt-title.png figures/bsp-title.png \
166 figures/kernel-title.png figures/kernel-architecture-overview.png \
167 figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
168 figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
169 figures/kernel-example-repos-denzil.png \
170 figures/kernel-overview-1.png figures/kernel-overview-2.png \
171 figures/kernel-overview-3-denzil.png \
172 figures/source-repos.png figures/yp-download.png \
173 figures/wip.png
174 else
175TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \
176 figures/using-a-pre-built-image.png \
177 figures/poky-title.png figures/buildhistory.png figures/buildhistory-web.png \
178 figures/adt-title.png figures/bsp-title.png \
179 figures/kernel-dev-title.png figures/kernel-architecture-overview.png \
180 figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
181 figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
182 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
183 figures/source-repos.png figures/yp-download.png \
184 figures/profile-title.png figures/kernelshark-all.png \
185 figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \
186 figures/kernelshark-output-display.png figures/lttngmain0.png \
187 figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \
188 figures/oprofileui-downloading.png figures/oprofileui-processes.png \
189 figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \
190 figures/perf-systemwide.png figures/perf-systemwide-libc.png \
191 figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \
192 figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \
193 figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \
194 figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \
195 figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \
196 figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \
197 figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \
198 figures/sched-wakeup-profile.png figures/sysprof-callers.png \
199 figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \
200 figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \
201 figures/package-feeds.png figures/layer-input.png figures/images.png figures/sdk.png \
202 figures/source-fetching.png figures/patching.png figures/configuration-compile-autoreconf.png \
203 figures/analysis-for-package-splitting.png figures/image-generation.png \
204 figures/sdk-generation.png figures/recipe-workflow.png
205 endif
206
207MANUALS = $(DOC)/$(DOC).html
208FIGURES = figures
209STYLESHEET = $(DOC)/*.css
210
211endif
212
213ifeq ($(DOC),ref-manual)
214XSLTOPTS = --xinclude
215ALLPREQ = html pdf eclipse tarball
216TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
217 figures/buildhistory.png figures/buildhistory-web.png eclipse \
218 figures/cross-development-toolchains.png figures/layer-input.png \
219 figures/package-feeds.png figures/source-input.png \
220 figures/user-configuration.png figures/yocto-environment-ref.png \
221 figures/images.png figures/sdk.png figures/source-fetching.png \
222 figures/patching.png figures/configuration-compile-autoreconf.png \
223 figures/analysis-for-package-splitting.png figures/image-generation.png \
224 figures/sdk-generation.png
225MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
226FIGURES = figures
227STYLESHEET = $(DOC)/*.css
228endif
229
230
231ifeq ($(DOC),adt-manual)
232XSLTOPTS = --xinclude
233ALLPREQ = html pdf eclipse tarball
234TARFILES = adt-manual.html adt-manual.pdf adt-style.css figures/adt-title.png \
235 eclipse
236MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
237FIGURES = figures
238STYLESHEET = $(DOC)/*.css
239endif
240
241ifeq ($(DOC),profile-manual)
242XSLTOPTS = --xinclude
243ALLPREQ = html pdf eclipse tarball
244TARFILES = profile-manual.html profile-manual.pdf profile-manual-style.css \
245 figures/profile-title.png figures/kernelshark-all.png \
246 figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \
247 figures/kernelshark-output-display.png figures/lttngmain0.png \
248 figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \
249 figures/oprofileui-downloading.png figures/oprofileui-processes.png \
250 figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \
251 figures/perf-systemwide.png figures/perf-systemwide-libc.png \
252 figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \
253 figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \
254 figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \
255 figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \
256 figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \
257 figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \
258 figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \
259 figures/sched-wakeup-profile.png figures/sysprof-callers.png \
260 figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \
261 eclipse
262MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
263FIGURES = figures
264STYLESHEET = $(DOC)/*.css
265endif
266
267ifeq ($(DOC),kernel-dev)
268XSLTOPTS = --xinclude
269ALLPREQ = html pdf eclipse tarball
270TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png \
271 figures/kernel-architecture-overview.png \
272 eclipse
273MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
274FIGURES = figures
275STYLESHEET = $(DOC)/*.css
276endif
277
278
279##
280# These URI should be rewritten by your distribution's xml catalog to
281# match your localy installed XSL stylesheets.
282XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current
283XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
284
285all: $(ALLPREQ)
286
287pdf:
288ifeq ($(DOC),yocto-project-qs)
289 @echo " "
290 @echo "ERROR: You cannot generate a yocto-project-qs PDF file."
291 @echo " "
292
293else ifeq ($(DOC),mega-manual)
294 @echo " "
295 @echo "ERROR: You cannot generate a mega-manual PDF file."
296 @echo " "
297
298else
299
300 cd $(DOC); ../tools/poky-docbook-to-pdf $(DOC).xml ../template; cd ..
301endif
302
303html:
304ifeq ($(DOC),mega-manual)
305# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
306 @echo " "
307 @echo "******** Building "$(DOC)
308 @echo " "
309 cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
310 @echo " "
311 @echo "******** Using mega-manual.sed to process external links"
312 @echo " "
313 cd $(DOC); sed -f ../tools/mega-manual.sed < mega-manual.html > mega-output.html; cd ..
314 @echo " "
315 @echo "******** Cleaning up transient file mega-output.html"
316 @echo " "
317 cd $(DOC); rm mega-manual.html; mv mega-output.html mega-manual.html; cd ..
318else
319# See http://www.sagehill.net/docbookxsl/HtmlOutput.html
320 @echo " "
321 @echo "******** Building "$(DOC)
322 @echo " "
323 cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
324endif
325
326
327eclipse: BASE_DIR = html/$(DOC)/
328
329eclipse: eclipse-generate eclipse-resolve-links
330
331.PHONY : eclipse-generate eclipse-resolve-links
332
333eclipse-generate:
334ifeq ($(filter $(DOC), adt-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual yocto-project-qs),)
335 @echo " "
336 @echo "ERROR: You can only create eclipse documentation"
337 @echo " of the following documentation parts:"
338 @echo " - adt-manual"
339 @echo " - bsp-guide"
340 @echo " - dev-manual"
341 @echo " - kernel-dev"
342 @echo " - profile-manual"
343 @echo " - ref-manual"
344 @echo " - yocto-project-qs"
345 @echo " "
346else
347 @echo " "
348 @echo "******** Building eclipse help of "$(DOC)
349 @echo " "
350 cd $(DOC) && \
351 xsltproc $(XSLTOPTS) \
352 --stringparam base.dir '$(BASE_DIR)' \
353 -o eclipse/$(DOC).html \
354 $(DOC)-eclipse-customization.xsl $(DOC).xml && \
355 mv eclipse/toc.xml eclipse/$(DOC)-toc.xml && \
356 cp -rf $(FIGURES) eclipse/$(BASE_DIR) && \
357 cd ..;
358
359 $(call modify-eclipse)
360endif
361
362eclipse-resolve-links:
363 @echo " "
364 @echo "******** Using eclipse-help.sed to process external links"
365 @echo " "
366 $(foreach FILE, \
367 $(wildcard $(DOC)/eclipse/html/$(DOC)/*.html), \
368 $(shell sed -i -f tools/eclipse-help.sed $(FILE)))
369
370tarball: html
371 @echo " "
372 @echo "******** Creating Tarball of document files"
373 @echo " "
374 cd $(DOC); tar -cvzf $(DOC).tgz $(TARFILES); cd ..
375
376validate:
377 cd $(DOC); xmllint --postvalid --xinclude --noout $(DOC).xml; cd ..
378
379
380publish:
381 @if test -f $(DOC)/$(DOC).html; \
382 then \
383 echo " "; \
384 echo "******** Publishing "$(DOC)".html"; \
385 echo " "; \
386 scp -r $(MANUALS) $(STYLESHEET) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
387 cd $(DOC); scp -r $(FIGURES) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
388 else \
389 echo " "; \
390 echo $(DOC)".html missing. Generate the file first then try again."; \
391 echo " "; \
392 fi
393
394clean:
395 rm -rf $(MANUALS); rm $(DOC)/$(DOC).tgz;