source: pst/ps/fop.xml@ 5cd4458

10.0 10.1 11.0 11.1 11.2 8.1 8.2 8.3 8.4 9.0 9.1 basic bdubbs/svn elogind lazarus perl-modules plabs/python-mods qt5new trunk upgradedb xry111/intltool xry111/soup3 xry111/test-20220226
Last change on this file since 5cd4458 was 5cd4458, checked in by Pierre Labastie <pieere@…>, 5 years ago

Fix SWIG tests with perl-5.26 and a few tags

git-svn-id: svn://svn.linuxfromscratch.org/BLFS/trunk/BOOK@19097 af4574ff-66df-0310-9fd7-8a98e5e911e0

  • Property mode set to 100644
File size: 14.9 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY fop-download-http "https://archive.apache.org/dist/xmlgraphics/fop/source/fop-&fop-version;-src.tar.gz">
8 <!ENTITY fop-download-ftp " ">
9 <!ENTITY fop-md5sum "6d2388bd8851b4883d3258c0afc96895">
10 <!ENTITY fop-size "24 MB">
11 <!ENTITY fop-buildsize "493 MB (add 39 MB for tests)">
12 <!ENTITY fop-time "0.7 SBU (add 0.7 SBU for tests)">
13
14 <!ENTITY jai-version "1_1_3">
15 <!ENTITY jai-download "http://download.java.net/media/jai/builds/release/&jai-version;/jai-&jai-version;-lib-linux-i586.tar.gz">
16 <!ENTITY jai-md5sum "a2cbc155ef3899bcde9c74a8035764b3">
17 <!ENTITY jai-size "3.4 MB">
18
19 <!ENTITY jai64-download "http://download.java.net/media/jai/builds/release/&jai-version;/jai-&jai-version;-lib-linux-amd64.tar.gz">
20 <!ENTITY jai64-md5sum "4a906db35612f668aeef2c0606d7075b">
21 <!ENTITY jai64-size "3.4 MB">
22
23 <!ENTITY offo-download "&sourceforge-dl;/offo/2.2/offo-hyphenation.zip">
24 <!ENTITY offo-md5sum "bf9c09bf05108ef9661b8f08d91c2336">
25 <!ENTITY offo-size "862 KB">
26]>
27
28<sect1 id="fop" xreflabel="fop-&fop-version;">
29 <?dbhtml filename="fop.html"?>
30
31 <sect1info>
32 <othername>$LastChangedBy$</othername>
33 <date>$Date$</date>
34 </sect1info>
35
36 <title>fop-&fop-version;</title>
37
38 <indexterm zone="fop">
39 <primary sortas="a-fop">fop</primary>
40 </indexterm>
41
42 <sect2 role="package">
43 <title>Introduction to fop</title>
44
45 <para>
46 The <application>FOP</application> (Formatting Objects Processor)
47 package contains a print formatter driven by XSL formatting objects
48 (XSL-FO). It is a <application>Java</application> application that reads
49 a formatting object tree and renders the resulting pages to a specified
50 output. Output formats currently supported include PDF, PCL, PostScript,
51 SVG, XML (area tree representation), print, AWT, MIF and ASCII text. The
52 primary output target is PDF.
53 </para>
54
55 &lfs81_checked;
56
57 <bridgehead renderas="sect3">Package Information</bridgehead>
58 <itemizedlist spacing="compact">
59 <listitem>
60 <para>Download (HTTP): <ulink url="&fop-download-http;"/></para>
61 </listitem>
62 <listitem>
63 <para>Download (FTP): <ulink url="&fop-download-ftp;"/></para>
64 </listitem>
65 <listitem>
66 <para>Download MD5 sum: &fop-md5sum;</para>
67 </listitem>
68 <listitem>
69 <para>Download size: &fop-size;</para>
70 </listitem>
71 <listitem>
72 <para>Estimated disk space required: &fop-buildsize;</para>
73 </listitem>
74 <listitem>
75 <para>Estimated build time: &fop-time;</para>
76 </listitem>
77 </itemizedlist>
78
79 <bridgehead renderas="sect3">Additional Downloads</bridgehead>
80 <itemizedlist spacing="compact">
81 <title>Recommended packages</title>
82
83 <listitem>
84 <para>Objects for Formatting Objects (OFFO) hyphenation patterns:
85 <simplelist>
86 <member><ulink url="&offo-download;"/></member>
87 <member>&offo-md5sum;</member>
88 <member>&offo-size;</member>
89 </simplelist>
90 </para>
91 </listitem>
92
93 <listitem>
94 <para>Java Advanced Imaging (JAI) API components (architecture dependent):
95 <simplelist>
96 <member><ulink url="&jai-download;"/></member>
97 <member>&jai-md5sum;</member>
98 <member>&jai-size;</member>
99 </simplelist>
100 <literallayout>or</literallayout> <!-- Force some space -->
101 <simplelist>
102 <member><ulink url="&jai64-download;"/></member>
103 <member>&jai64-md5sum;</member>
104 <member>&jai64-size;</member>
105 </simplelist>
106 </para>
107 </listitem>
108 </itemizedlist>
109<!-- <itemizedlist spacing="compact">
110 <title>Required patch</title>
111 <listitem>
112 <para>
113 <ulink url="&patch-root;/fop-&fop-version;-listNPE-1.patch"/>
114 </para>
115 </listitem>
116 </itemizedlist>-->
117
118 <bridgehead renderas="sect3">fop Dependencies</bridgehead>
119
120 <bridgehead renderas="sect4">Required</bridgehead>
121 <para role="required">
122 <xref linkend="apache-ant"/>
123 </para>
124
125 <bridgehead renderas="sect4">Optional</bridgehead>
126 <para role="optional">
127 <xref linkend="junit"/> (to run tests),
128 <xref linkend="x-window-system"/> (to run tests),
129 <ulink url="https://maven.apache.org/">Maven</ulink>,
130 <ulink url="https://java.net/projects/jai-imageio">JAI Image I/O Tools</ulink>, and
131 <ulink url="http://jeuclid.sourceforge.net/">JEuclid</ulink>
132<!-- [pierre 2017-04-29] Note to devs: there are a lot of bundled dependencies.
133 Some were listed here, but not all. I am not sure it is possible to
134 use system ones. So, I have removed them, an kept only those which
135 are not bundled. -->
136 </para>
137
138 <para condition="html" role="usernotes">User Notes:
139 <ulink url="&blfs-wiki;/fop"/></para>
140
141 </sect2>
142
143 <sect2 role="installation">
144 <title>Installation of fop</title>
145
146 <para>
147 Ensure <envar>$JAVA_HOME</envar> is set correctly before beginning
148 the build. To build the <application>JIMI SDK</application> and/or
149 <application>XMLUnit</application> extension classes, ensure the
150 corresponding <filename class='extension'>.jar</filename> files can be
151 found via the <envar>CLASSPATH</envar> environment variable.
152 </para>
153
154 <sect3>
155 <title>Installing OFFO Hyphenation Patterns</title>
156
157 <para>
158 Copy the XML hyphenation patterns into the fop source tree by running
159 the following commands:
160 </para>
161
162<screen><userinput>unzip ../offo-hyphenation.zip &amp;&amp;
163cp offo-hyphenation/hyph/* fop/hyph &amp;&amp;
164rm -rf offo-hyphenation</userinput></screen>
165
166 </sect3>
167
168 <sect3>
169 <title>Installing Java Advanced Imaging (JAI) API components</title>
170
171 <para>
172 Install the JAI API components. As the <systemitem
173 class="username">root</systemitem> user:
174 </para>
175
176<screen role="root"><userinput>case `uname -m` in
177 i?86)
178 tar -xf ../jai-&jai-version;-lib-linux-i586.tar.gz
179 cp -v jai-&jai-version;/lib/{jai*,mlibwrapper_jai.jar} $JAVA_HOME/jre/lib/ext/
180 cp -v jai-&jai-version;/lib/libmlib_jai.so $JAVA_HOME/jre/lib/i386/
181 ;;
182
183 x86_64)
184 tar -xf ../jai-&jai-version;-lib-linux-amd64.tar.gz
185 cp -v jai-&jai-version;/lib/{jai*,mlibwrapper_jai.jar} $JAVA_HOME/jre/lib/ext/
186 cp -v jai-&jai-version;/lib/libmlib_jai.so $JAVA_HOME/jre/lib/amd64/
187 ;;
188esac</userinput></screen>
189 </sect3>
190
191 <sect3>
192 <title>Installing fop Components</title>
193
194 <para>
195 The <command>javadoc</command> command coming with OpenJDK 8 has
196 become much stricter than before regarding the conformance of the
197 Javadoc comments in source code to HTML. The FOP documentation does
198 not meet those standard, so the conformance checks have to be
199 disabled. This can be done with the following command:
200 </para>
201
202<screen><userinput>sed -i '\@&lt;/javad@i\
203&lt;arg value="-Xdoclint:none"/&gt;\
204&lt;arg value="--allow-script-in-comments"/&gt;' fop/build.xml</userinput></screen>
205
206 <para>
207 The stack size set in <filename>build.xml</filename> for building the
208 hyphenation patterns is not enough. Change it by running:
209 </para>
210
211<screen><userinput>sed -e '/hyph\.stack/s/512k/1M/' \
212 -i fop/build.xml</userinput></screen>
213 <para>
214 Then, compile <application>fop</application> by running the
215 following commands:
216 </para>
217
218<screen><userinput>cd fop &amp;&amp;
219export LC_ALL=en_US.UTF-8 &amp;&amp;
220
221ant compile &amp;&amp;
222ant jar-main &amp;&amp;
223ant jar-hyphenation &amp;&amp;
224ant javadocs &amp;&amp;
225mv build/javadocs .</userinput></screen>
226
227 <para>
228 To test the application, first modify <filename>build.xml</filename>
229 so that tests do not stop when an error is encountered:
230 </para>
231
232<screen><userinput>sed -e '/haltonfailure/s/yes/off/' \
233 -i build.xml</userinput></screen>
234
235 <para>
236 Then, run <command>ant junit</command>. The hyphenation tests will
237 fail if OFFO hyphenation has not been compiled. To see a list of other
238 test targets, use <command>ant -p</command>. You must run the tests
239 from an X-window using a GL-aware <application>Xorg</application>
240 server or some of the <application>JUnit</application> tests will hang.
241 </para>
242
243 <para>
244 Now, as the <systemitem class="username">root</systemitem> user:
245 </para>
246
247<screen role="root"><userinput>install -v -d -m755 -o root -g root /opt/fop-&fop-version; &amp;&amp;
248cp -v ../{KEYS,LICENSE,NOTICE,README} /opt/fop-&fop-version; &amp;&amp;
249cp -vR build conf examples fop* javadocs lib /opt/fop-&fop-version; &amp;&amp;
250chmod a+x /opt/fop-&fop-version;/fop &amp;&amp;
251
252ln -v -sfn fop-&fop-version; /opt/fop</userinput></screen>
253
254 </sect3>
255
256 </sect2>
257
258 <sect2 role="commands">
259 <title>Command Explanations</title>
260
261 <para>
262 <command>sed -i ... build.xml</command>: This adds two switches to the
263 <command>javadoc</command> command, preventing some errors to occur when
264 building the documentation.
265 </para>
266
267 <para>
268 <command>export LC_ALL=en_US.UTF-8</command>: the compiler fails if using
269 an ASCII locale.
270 </para>
271
272 <para>
273 <command>ant <option>target</option></command>: This reads the file
274 <filename>build.xml</filename> and builds the target: <option>compile
275 </option> compiles the java sources, <option>jar-main</option> generates
276 jar archives, <option>jar-hyphenation</option> generates the hyphenation
277 patterns for FOP, and <option>javadocs</option> builds the documentation.
278 </para>
279
280 <para>
281 <command>ln -v -sf fop-&fop-version; /opt/fop</command>: This is
282 optional and creates a convenience symlink so that
283 <envar>$FOP_HOME</envar> doesn't have to be changed each time there's a
284 package version change.
285 </para>
286
287 </sect2>
288
289 <sect2 role="configuration">
290 <title>Configuring fop</title>
291
292 <sect3 id="fop-config">
293 <title>Config Files</title>
294
295 <para>
296 <filename>~/.foprc</filename>
297 </para>
298
299 <indexterm zone="fop fop-config">
300 <primary sortas="e-AA.foprc">~/.foprc</primary>
301 </indexterm>
302
303 </sect3>
304
305 <sect3>
306 <title>Configuration Information</title>
307
308 <para>
309 Using <application>fop</application> to process some large FO's
310 (including the FO derived from the BLFS XML sources), can lead to
311 memory errors. Unless you add a parameter to the
312 <command>java</command> command used in the <command>fop</command>
313 script you may receive messages similar to the one shown below:
314 </para>
315
316 <para>
317 <computeroutput>
318 Exception in thread "main" java.lang.OutOfMemoryError: Java heap
319 space
320 </computeroutput>
321 </para>
322
323 <para>
324 To avoid errors like this, you need to pass an extra parameter to
325 the <command>java</command> command used in the <command>fop</command>
326 script. This can be accomplished by creating a
327 <filename>~/.foprc</filename> (which is sourced by the
328 <command>fop</command> script) and adding the parameter to the
329 <envar>FOP_OPTS</envar> environment variable.
330 </para>
331
332 <para>
333 The <command>fop</command> script looks for a
334 <envar>FOP_HOME</envar> environment variable to locate the
335 <application>fop</application> class libraries. You can create this
336 variable using the <filename>~/.foprc</filename> file as well. Create
337 a <filename>~/.foprc</filename> file using the following commands:
338 </para>
339
340<screen><userinput>cat &gt; ~/.foprc &lt;&lt; "EOF"
341<literal>FOP_OPTS="-Xmx<replaceable>&lt;RAM_Installed&gt;</replaceable>m"
342FOP_HOME="/opt/fop"</literal>
343EOF</userinput></screen>
344
345 <para>
346 Replace <replaceable>&lt;RAM_Installed&gt;</replaceable> with a
347 number representing the amount of RAM installed in your computer (in
348 megabytes). An example would be
349 <userinput>FOP_OPTS="-Xmx768m"</userinput>.
350 <!-- the URL is broken
351 For more information about
352 memory issues running <application>fop</application>, see
353 <ulink url="http://xml.apache.org/fop/running.html#memory"/>.
354 -->
355 </para>
356
357 <para>
358 To include the <command>fop</command> script in your path,
359 update your personal or system-wide profile with the following:
360 </para>
361
362<screen><literal>PATH=$PATH:/opt/fop</literal></screen>
363
364 <note>
365 <para>
366 Running <command>fop</command> can be somewhat verbose.
367 The default logging level can be changed from INFO to any of
368 FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE, ALL, or OFF.
369 To do this, edit
370 <filename>$JAVA_HOME/jre/lib/logging.properties</filename> and change
371 the entries for <option>.level</option> and
372 <option>java.util.logging.ConsoleHandler.level</option> to
373 the desired value.
374 </para>
375 </note>
376
377 </sect3>
378
379 </sect2>
380
381 <sect2 role="content">
382 <title>Contents</title>
383
384 <segmentedlist>
385 <segtitle>Installed Programs</segtitle>
386 <segtitle>Installed Libraries</segtitle>
387 <segtitle>Installed Directory</segtitle>
388
389 <seglistitem>
390 <seg>fop</seg>
391 <seg>fop.jar and numerous support library classes located in
392 <filename class='directory'>/opt/fop/{build,lib}</filename>; JAI
393 components include libmlib_jai.so, jai_codec.jar, jai_core.jar, and
394 mlibwrapper_jai.jar</seg>
395 <seg>/opt/fop-&fop-version;</seg>
396 </seglistitem>
397 </segmentedlist>
398
399 <variablelist>
400 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
401 <?dbfo list-presentation="list"?>
402 <?dbhtml list-presentation="table"?>
403
404 <varlistentry id="fop-prog">
405 <term><command>fop</command></term>
406 <listitem>
407 <para>is a wrapper script to the <command>java</command> command
408 which sets up the <application>fop</application>
409 environment and passes the required parameters.</para>
410 <indexterm zone="fop fop-prog">
411 <primary sortas="b-fop">fop</primary>
412 </indexterm>
413 </listitem>
414 </varlistentry>
415
416 <varlistentry id="fop.jar">
417 <term><filename class='libraryfile'>fop.jar</filename></term>
418 <listitem>
419 <para>contains all the <application>fop</application>
420 <application>Java</application> classes.</para>
421 <indexterm zone="fop fop.jar">
422 <primary sortas="c-fop.jar">fop.jar</primary>
423 </indexterm>
424 </listitem>
425 </varlistentry>
426
427 </variablelist>
428
429 </sect2>
430
431</sect1>
Note: See TracBrowser for help on using the repository browser.