This repository has been archived by the owner on May 4, 2022. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.html
731 lines (576 loc) · 34.5 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>PoDoFo Readme</title>
</head>
<body>
<h1>PoDoFo</h1>
<ol>
<li><a href="#what_is_podofo">What is PoDoFo?</a></li>
<li><a href="#where_can_i_get_it">Where can I can get it?</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#installation">Installation</a>
<ol>
<li><a href="#stlport_support">STLPort support</a>
<li><a href="#boost_support">Boost support</a>
<li><a href="#installation_with_cmake">Installation with CMake</a>
<ol>
<li><a href="#cmake_builds_on_linux_unix">CMake builds on Linux/UNIX</a></li>
<li><a href="#cmake_builds_on_mac_os_x">CMake builds on Mac OS X</a></li>
<li><a href="#homebrew_builds_on_macos">Homebrew builds on Mac OS X</a></li>
<li><a href="#cmake_builds_on_windows">CMake builds on Windows</a></li>
</ol>
</li>
</ol>
</li>
<li><a href="#using_podofo_in_your_application">Using PoDoFo in Your Application</a></li>
<li><a href="#preprocessor">Preprocessor defines used in PoDoFo</a></li>
<li><a href="#structure">Structure of the library</a></li>
<li><a href="#contact">Contact</a></li>
<li><a href="#licensing">Licensing</a></li>
</ol>
<h2><a name="what_is_podofo" />What is PoDoFo?</h2>
<p>PoDoFo is a library to work with the PDF file format and includes also a few
tools. The name comes from the first two letters of PDF (<b>Po</b>rtable <b>Do</b>cument
<b>Fo</b>rmat).</p>
<p>The PoDoFo library is a free portable C++ library which includes classes to
parse a PDF file and modify its contents into memory. The changes can be
written back to disk easily. PoDoFo is designed to avoid loading large PDF
objects into memory until they are required and can write large streams
immediately to disk, so it is possible to manipulate quite large files with it.
PoDoFo uses and relies on exceptions, so it must be built with them enabled.</p>
<p>Besides PDF parsing and writing PoDoFo includes also very simple classes to
create your own PDF files. All classes are documented so it is easy to start
writing your own application using PoDoFo.</p>
<p>PoDoFo is primarily useful for applications that wish to do lower level
manipulation of PDF, such as extracting content or merging files. It's also
useful if your application has specific requirements for it's PDF output that
more general output-oriented libraries like Cairo cannot satisfy.
Canvas/drawing support is currently very limited in PoDoFo, so for pure output
tasks a library like Cairo will be more suitable. PoDoFo cannot render PDF,
so you should look at a library like Poppler for that.</p>
<p>See:</p>
<ul>
<li><a href="http://cairographics.org/">http://cairographics.org/</a></li>
<li><a href="http://poppler.freedesktop.org/">http://poppler.freedesktop.org/</a></li>
</ul>
<p>The PoDoFo tools are simple tools build around the PoDoFo library. These tools
are first of all examples on how to use the PoDoFo library in your own
projects. But secondly they offer also features for working with PDF files.
More tools will come with future release and the existing tools will gain more
features. The following tools are currently available:</p>
<ul>
<li><b>podofoencrypt</b> -
Encrypts any PDF and allows to set PDF permissions..</li>
<li><b>podofoimgextract</b> -
Extracts all images from a given PDF file.</li>
<li><b>podofoimpose</b> -
A powerful
PDF <a href="http://en.wikipedia.org/wiki/Imposition">imposition</a>
tool. It places pages from one or more source PDFs onto pages of a new PDF,
applying scaling and positioning. If you have lua5.1 development
libraries installed, it will be built with support for Lua plan files,
which allow for mighty PDF transformations.</li>
<li><b>podofomerge</b> -
Merges two PDF files into onw.</li>
<li><b>podofopdfinfo</b> -
Provides some basic info about a PDF - metadata, page details, etc.</li>
<li><b>podofotxt2pdf</b> -
Converts a text file to a PDF</li>
<li><b>podofotxtextract</b> -
A tool that extracts all text from a PDF file. Works only for simple PDFs
at the moment.</li>
<li><b>podofouncompress</b> -
Removes all compression filters from a PDF file. This is useful for debugging
existing PDF files. You might also find PoDoFoBrowser, distributed separately,
to be useful if you're using this tool a lot.</li>
</ul>
<p>Additionally there is the external tool PoDoFoBrowser which is not included in
this package, but can be downloaded from the PoDoFo webpage. PoDoFoBrowser is a
Qt application for browsing and modifying the objects in a PDF file, examining
the structure of PDF files, and manipulating PDF streams. It is very useful if
you want to look on the internal structure of PDF files.</p>
<p>As of version 0.7 PoDoFo is available for Unix, Mac
OS X and Windows platforms.</p>
<h2><a name="where_can_i_get_it" />Where can I can get it?</h2>
<p>PoDoFo is available on the internet: <a href="http://podofo.sf.net">podofo.sf.net</a></p>
<h2><a name="requirements" />Requirements</h2>
<p>To build PoDoFo lib you need a working toolchain and a c++ compiler as well as
the following libraries:</p>
<ul>
<li>zlib</li>
<li>freetype2</li>
<li>fontconfig (Unix & Mac OS X only)</li>
<li>libjpeg (optional)</li>
<li>libtiff (optional)</li>
<li>libidn (optional)</li>
<li>libCrypto++ (optional)</li>
</ul>
<p>See <a href="#installation_with_cmake">Installation with CMake</a> for a
list of tested platforms and compilers. In general, any reasonably well behaved
C++ compiler should work.</p>
<p>A list of known -dev / -devel packages required for various Linux distros is maintained
in the <a href="#required_linux_packages">required Linux packages</a> appendix.</p>
<p>See also <a href="#using_podofo">Using PoDoFo</a>.</p>
<h2><a name="installation">Installation</a></h2>
<p>Rather than using binary packages, you should usually build PoDoFo yourself.
This ensures that it will be built with the same compiler and settings as your
program. Because most platforms have no consistent C++ ABI or runtime
libraries, this is important to ensure that you get a compatible STL, correct
memory management between podofo and your app, etc.</p>
<p>PoDoFo is built and installed using CMake. The autotools build, Visual Studio
project and XCode project were dropped as maintaining three unrelated and
incompatible build systems that are exclusive to three different platforms
consumes a lot of resources which can be spend better on improving PoDoFo
itself. Even if you've never used CMake before, you'll find it pretty easy.</p>
<p>Unix users should generate Unix Makefiles with CMake, though it's also possible
to produce a KDevelop project. See <a href="#cmake_builds_on_linux_unix">CMake builds on Linux/UNIX</a></p>
<p>If your application or library uses Visual Studio, CMake can be used to
build a Visual Studio project you can use. Alternately, if you are using
MinGW for your existing code, CMake can make you a MinGW makefile to
build a mingw compatible version of PoDoFo. You must build PoDoFo with
the same compiler as your application. See <a href="#cmake_builds_on_windows">CMake builds on Windows</a></p>
<p>Mac OS X users will need to use CMake to generate a conventional UNIX build
with Makefiles, or may generate an XCode project with CMake. See the <a href="#cmake_builds_on_mac_os_x">Mac OS X
section</a> below, and the <a href="#installation_with_cmake">generic instructions for cmake builds</a></p>
<h3><a name="stlport_support" />STLPort support</h3>
<p>Don't know what STLPort is? Ignore it and skip this section. Packagers should
not enable STLPort.</p>
<p>If your project uses STLPort rather than your platform/toolset's native STL,
you must configure PoDoFo to use STLPort as well. Use the -DUSE_STLPORT=1
argument to configure. Do not enable STLPort for podofo unless you use it in
your project; you will get an incompatible C++ STL leading to link errors,
runtime crashes, or other problems.</p>
<p>It is unnecessary and unwise to build PoDoFo against STLPort on any current
major platform unless you have a specific reason to do so.</p>
<h3><a name="boost_support" />Boost support</h3>
<p>PoDoFo can make limited use of the Boost libraries if they are available.
There is no need to use them, but some things may work more smoothly, and more
use is expected in the future. If PoDoFo is built to use Boost, your
application must also have Boost's headers (boost graph libraries) on its search path. Set
-DWANT_BOOST:BOOL=1 to enable Boost support.</p>
<p>Packagers should not currently build PoDoFo with boost support.</p>
<h3><a name="installation_with_cmake" />Installation with CMake</h3>
<P>PoDoFo has support for builds using CMake on all supported
platforms. The CMake build has been tested on:</p>
<ul>
<li>Visual C++ 9 Express Edition [Win32] ("Visual Studio 9 2008" target)</li>
<li>Visual C++ 8 Express Edition [Win32] ("Visual Studio 8 2005" target) (needs additional setup)</li>
<li>Visual C++ 8 Express +NMake [Win32] ("NMake Makefiles" target) (needs additional setup)</li>
<li>MinGW with GCC 3.4.2 [Win32] ("MinGW Makefiles" target)</li>
<li>gcc 3.3.5 [Linux: Debian 3.1] ("Unix Makefiles" target)</li>
<li>gcc 4.0, 4.1, 4.2 [Linux: Debian 4.0] ("Unix Makefiles" target)</li>
<li>gcc 4.0 [Mac OS X 10.4.10] ("Unix Makefiles" target)</li>
</ul>
<p>PoDoFo is also known to build with Visual C++ 6 using CMake, though it is
not regularly tested by the team so you might need to do some work to use
a recent svn build.</p>
<p>You can use the CMake variable <code>CMAKE_BUILD_TYPE</code> to control the type of
build. The main values supported are <code>DEBUG</code> and <code>RELEASE</code>. The default is
DEBUG. Set the build type with the CMake argument:<br/>
<code>-DCMAKE_BUILD_TYPE=DEBUG</code><br/>
or<br/>
<code>-DCMAKE_BUILD_TYPE=RELEASE</code><br/>
as appropriate.</p>
<p>You can control where the files are installed with `make install' with
<code>-DCMAKE_INSTALL_PREFIX=/path/to/install/dir</code></p>
<p>All instructons below use out-of-tree builds (recommended). To clean up an
out-of-tree build, just delete the build directory, as no files are touched
within the source directory.</p>
<p>On all Makefile-style builds, set the <code>VERBOSE</code> flag to 1 on the make command
line to see all compiler commands etc, eg: <code>make VERBOSE=1</code></p>
<h4><a name="cmake_builds_on_linux_unix"/>CMake builds on Linux/UNIX</h4>
<p>Linux and UNIX users should be able to build PoDoFo by cd'ing into the PoDoFo
checkout or unpacked tarball directory (here assumed to be named "podofo-src")
then running the build commands shown below. The CMake command below will
install into $HOME/podofo to avoid needing root priveleges for installation,
but you can change the destination to wherever you want or remove the install
prefix setting to use the default.</p>
<p>To build and install:</p>
<pre>
mkdir ../podofo-build
cd ../podofo-build
cmake -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX="$HOME/podofo" ../podofo-src
make
make install
</pre>
<p>To see detailed compiler output, use:</p>
<pre>
make VERBOSE=1
</pre>
<p>If you're working on a 64 bit linux that has a /usr/lib64 directory, add
<code>-DWANT_LIB64:BOOL=TRUE</code> to the CMake command line.</p>
<p>If you need to specify additional paths to search for libraries, set the
<code>CMAKE_INCLUDE_PATH</code> and <code>CMAKE_LIBRARY_PATH</code> environment variables or set them on
the command line:</p>
<pre>
cmake -G "Unix Makefiles" ../podofo-src \
-DCMAKE_INCLUDE_PATH=/usr/sfw/include \
-DCMAKE_LIBRARY_PATH=/usr/sfw/lib
</pre>
<p>If you wish to generate only a static library or only a shared library, set the
<code>PODOFO_BUILD_SHARED</code> and/or <code>PODOFO_BUILD_STATIC</code> flags:</p>
<pre>
cmake -G "Unix Makefiles" ../podofo-src \
-DCMAKE_INCLUDE_PATH=/usr/sfw/include \
-DCMAKE_LIBRARY_PATH=/usr/sfw/lib \
-DPODOFO_BUILD_SHARED:BOOL=TRUE \
-DPODOFO_BUILD_STATIC:BOOL=FALSE
</pre>
<p>By default, with CMake 2.6.x all supported library types will be built where
possible. Only the shared library will be built by default using 2.4.x because
of a CMake limitation; you can build a static library instead with
<code>-DPODOFO_BUILD_STATIC:BOOL=TRUE</code>, or upgrade to CMake 2.6.x .</p>
<p>Note that the instructions above run an out-of-tree build. CMake does support
in-tree builds, but the use of out-of-tree builds is very strongly recommended.</p>
<p>If your system has gcc 4, PoDoFo will tell gcc to make symbols hidden by
default using the <code>-fvisibility=hidden</code> flag to gcc. Only symbols explicitly
exported by PoDoFo will be exported. You can explicitly enable or disable this
behaviour with the boolean flag:
<code>-DPODOFO_USE_VISIBILITY=1</code> (or 0 for off).
Enabling default hidden visibility reduces the PoDoFo binary size dramatically
and improves link times. It also helps prevent accidental use of symbols that
are not part of PoDoFo's public API. PoDoFo developers will also find this
useful, as it will cause some mistakes to be reported as link errors that would
otherwise go undetected and break the win32 builds.</p>
<h4><a name="cmake_builds_on_mac_os_x"/>CMake builds on Mac OS X</h4>
<p>Mac OS X users can build PoDoFo using CMake either by generating conventional
UNIX Makefiles (the "Unix Makefiles" CMake target) or generating an XCode
project (the "Xcode" target). In either case the following applies.</p>
<p>You will need freetype and fontconfig. It's possible to omit the use of
libjpeg (see the platform-independent documentation) but by default libjpeg
will also be required. If you have these libraries already (say, from fink
or DarwinPorts) you can skip the following section and update the
<code>CMAKE_INCLUDE_PATH</code> and <code>CMAKE_LIBRARY_PATH</code> arguments appropriately.</p>
<h5>Dependencies</h5>
<p>I'll assume you're installing podofo and any required libraries into $HOME/libs
. Adjust to taste, but keep it consistent.</p>
<p>The easiest way to get any required libraries is to use <a href="http://macports.org/">MacPorts</a>
to install the libjpeg, fontconfig, and freetype libraries. Once you've installed MacPorts, just run:</p>
<pre>
/opt/local/bin/port install fontconfig freetype jpeg tiff lua
</pre>
<p>MacPorts will automatically build the libraries and their dependencies, installing them in /opt/local.</p>
<p>If you want to distribute the libraries with your application, all you'll need to do is use install_name_tool to set appropriate relative paths for their linkage and include them in your application bundle - just like you do with any other libraries.</p>
<h5>PoDoFo its self</h5>
<p>You should be able to configure and install podofo on Mac OS X using:</p>
<pre>
cmake -G "Unix Makefiles" \
-DWANT_FONTCONFIG:BOOL=TRUE \
-DCMAKE_INSTALL_PREFIX=/opt/podofo \
-DCMAKE_INCLUDE_PATH=/opt/local/include \
-DCMAKE_LIBRARY_PATH=/opt/local/lib \
../podofo
make
sudo mkdir /opt/podofo
sudo chown $USER /opt/podofo
make install
</pre>
<p>change "Unix Makefiles" to "Xcode" if you want to build an XCode project instead, then
instead of running `make' and `make install' just open the project file and work as normal</p>
<h4><a name="homebrew_builds_on_macos" />Homebrew builds on Mac OS X</h4>
<p>For Homebrew (package manager for Mac OS X) it is quite simple to install podofo. Freetype2 and zlib should be installed on Mac OS X by default.
<pre>
brew install fontconfig
brew install libjpeg
brew install libtiff
cd ((directory of podofo))
cmake -G "Unix Makefiles"
make
make install
</pre>
</p>
<h4><a name="cmake_builds_on_windows" />CMake builds on Windows</h4>
<h5><a name="windows_dependencies"/>Windows Dependencies</h5>
<p>PoDoFo requires a couple of other open source libraries to work. At minimum it needs zlib and libjpeg. Additional functionality is enabled if libtiff and/or openssl are available.</p>
<h6><a name="windows_dependency_zlib">zlib</h6>
<p>Both MinGW and Visual Studio users should use the standard precompiled zlib dll from <a href="http://zlib.org">zlib.org</a>. There is no need to compile your own.</p>
<p>Remember that you must ship <code>zlib1.dll</code> with your application. During testing it must be in the same directory as the PoDoFo-using executable or the directory containing it must be on your system PATH.</p>
<h6><a name="windows_dependency_libjpeg"/>libjpeg</h6>
<p>MinGW users can download the latest libjpeg installer from <a href="http://gnuwin32.sf.net">GnuWin32</a></p>.
<p>For Visual Studio you will need to build libjpeg with your version of Visual Studio. Download the libjpeg sources from <a href="http://www.ijg.org/">http://www.ijg.org/</a> and unpack them into a working directory. I'll assume you've used <code>C:\Developer\jpeg</code>. Once the sources are unpacked, start a visual studio command prompt and cd into <code>c:\developer\jpeg</code> then run <code>copy jconfig.vc jconfig.h</code> then <code>nmake /f makefile.vc /a</code></p>.
<p>If you use a DLL build of libjpeg remember that you must ship the DLL with your application. During testing the libjpeg dll must be in the same directory as the PoDoFo-using executable or the directory containing it must be on your system PATH. These requirements do not apply to the (recommended) static library libjpeg.</p>
<h5><a name="windows_podofo"/>Building PoDoFo on Windows</h5>
<p>Building PoDoFo on Windows can be done using MinGW (a minimalist gcc-based
compliler environment for Windows) or Visual Studio. Other methods may work but
have not been tested.</p>
<p>CMake 2.6.x is required for Windows. You can download it from
<a href="http://www.cmake.org/HTML/Download.html">cmake.org</a></p>.
<p>Because the C++ ABIs of most of the win32 compilers are incompatible, you
must build PoDoFo with the same compiler and version that you will use to build
the programs linked to PoDoFo. Failure to follow this restriction will result
in link errors at best, and bizarre runtime failures at worst.</p>
<p>On Windows, if you are linking against a shared (DLL) build of PoDoFo you
MUST define the preprocessor macro <code>USING_SHARED_PODOFO</code> when
including any podofo headers. Failure to do so will result in link time and/or
runtime errors. Similarly, defining it when linking with a static PoDoFo can
cause problems.</p>
<p>On Windows, PoDoFo may be built as either a shared or static library.
Building both is not supported. By default only the shared library will be
built. If you want a static library, just disable generation of the shared
library with the extra argument to cmake:</p>
<pre>
-DPODOFO_BUILD_SHARED=FALSE
</pre>
<p>PoDoFo will generally work correctly if you download pre-built libraries,
such as those published by the GnuWin32 project, even if they were built with a
different compiler. The primary exception is freetype, which should if at all
possible be built using your compiler. Freetype provides a VC++ project file
and is very easy to build. Make sure to build both the debug multi-threaded and
release multi-threaded versions.</p>
<p>For release you should generally build your own copy of these libraries
unless there is a well known and high quality pre-built version, like there is
for zlib. If you have built your own libjpeg you can improve PoDoFo's use of
it a bit by passing <code>-DJPEG_COMPATIBLE_RUNTIME</code> to CMake to tell
PoDoFo it's safe not to use its' workarounds for incompatible runtimes.</p>
<h5><a name="handling_library_naming_on_win32" />Handling library naming on win32</h5>
<p>Especially on Windows it is also common for custom built libraries to have
different names to those you might download as pre-built copies. CMake won't be
able to find them if they're called something else unless you tell it. Use
these variables to tell CMake what names to look for a library under:</p>
<ul>
<li>FREETYPE_LIBRARY_NAMES_DEBUG, FREETYPE_LIBRARY_NAMES_RELEASE and FREETYPE_LIBRARY_NAMES</li>
<li>TIFF_LIBRARY_NAMES_DEBUG, TIFF_LIBRARY_NAMES_RELEASE and TIFF_LIBRARY_NAMES</li>
<li>LIBJPEG_LIBRARY_NAMES_DEBUG, LIBJPEG_LIBRARY_NAMES_RELEASE and LIBJPEG_LIBRARY_NAMES</li>
<li>ZLIB_LIBRARY_NAMES_DEBUG, ZLIB_LIBRARY_NAMES_RELEASE, ZLIB_LIBRARY_NAMES</li>
</ul>
<p>For example, a cmake command line might include -DFREETYPE_LIBRARY_NAMES_DEBUG=freetype239MT_D -DFREETYPE_LIBRARY_NAMES_RELEASE=freetype239MT . If you only have the release library, just use -DFREETYPE_LIBRARY_NAMES . Telling CMake which are debug and release libraries helps it ensure you link to the right libraries depending on build type, but that does no good if you don't have a debug library.</p>
<h5><a name="cmake_builds_on_windows_with_mingw" />CMake builds on Windows with MinGW</h5>
<p>To build PoDoFo with MinGW, you'll naturally need MinGW. The author recommends installing Qt 4 from Trolltech,
which has a well packaged version of MinGW and is also useful for some PoDoFo tools like PoDoFoBrowser.</p>
<p>Once MinGW is set up, make sure that the MinGW "bin" directory is on your PATH, and be sure to set
<code>CMAKE_INCLUDE_PATH</code> and <code>CMAKE_LIBRARY_PATH</code> such that
CMake can find the headers and .lib files for the libraries PoDoFo requires.
The GnuWin32 library packages from <a
href="http://gnuwin32.sf.net">http://gnuwin32.sf.net/</a> are known to
work with PoDoFo, so installing zlib, freetype, and libjpeg from there should do the trick.</p>
<p>To configure and build PoDoFo with a default GnuWin32 install and with MinGW already on your PATH:</p>
<pre>
md ..\podofo-debug
cd ..\podofo-debug
cmake -G "MinGW Makefiles" ..\podofo-src -DCMAKE_INCLUDE_PATH=c:\progra~1\gnuwin32\include -DCMAKE_LIBRARY_PATH=c:\progra~1\gnuwin32\lib -DPODOFO_BUILD_SHARED:BOOL=FALSE
mingw32-make
</pre>
<p>It is extremely strongly recommended that you build PoDoFo only as a static
library if you are using MinGW by setting the
<code>-DPODOFO_BUILD_SHARED:BOOL=FALSE</code> flag to cmake. libstdc++ on MinGW
at the time of writing was not a shared library, causing serious issues with
memory allocation and deallocation when C++ objects like
<code>std::string</code> are passed by value across DLL boundaries or are
otherwise deleted in a different DLL to where they were allocated. Of course,
this will cause you problems if you intend to use PoDoFo across DLL boundaries,
but until libstd++ is made shared on MinGW there's not much to be done. VC++
does not suffer from this issue.</p>
<h5><a name="cmake_builds_on_windows_with_visual_studio" />CMake builds on Windows with Visual Studio</h5>
<p>A Visual Studio build requires that Microsoft Visual Studio be installed.
Visual Studio 9 2008 Express Edition is known to work, and is a free download
from Microsoft. You should get zlib from zlib.org. If you want JPEG support,
build your own libjpeg from sources or use the version from GnuWin32 (which
will work OK, if a bit slower, despite being built with gcc). It is preferable
to build your own copies of freetype, libjpeg and libtiff with your own
compiler and bundle those copies.</p>
<p>You'll also need CMake 2.6.</p>
<p>If you're using Visual Studio you really should build your own freetype.
With recent VC++ versions the GnuWin32 version of freetype is unlikely to work
reliably. Download the sources from <a href="http://download.savannah.gnu.org/releases/freetype/">http://download.savannah.gnu.org/releases/freetype/</a>
- you want something like ft245.zip . Unpack them and open
builds\win32\visualc\freetype.sln in VC++, upgrading it if required. Build it
in both debug multithreaded and release multithreaded modes. You should now see some
.lib files in a subdirectory of the objs\win32\ directory. The following instructions will assume
they're named <code>freetype239MT.lib</code> and
<code>freetype239MT_D.lib</code> and are found in <code>objs\win32\vc2008</code>, so adjust if yours are different.</p>
<p>If you built a debug freetype, you will also need to copy vc90.pdb (assuming you're using VC++ 9, otherwise the name will vary) from objs\debug_mt\vc90.pdb to objs\win32\vc2008\ so that VC++ can find Freetype's debug info.</p>
<p>The visual studio build of PoDoFo has two stages - first, CMake is used to generate a
Visual Studio solution, then the solution is built in VC++. I prefer to create
a short <code>build.cmd</code> file for the CMake command since on Windows it
tends to get rather long. Here's an example that assumes the
<code>build.cmd</code> file is in an empty directory with
<code>..\podofo-src</code> being the relative path to the PoDoFo sources.</p>
<pre>
del cmakecache.txt
set FTDIR=C:\developer\freetype-2.3.5
set FTLIBDIR=C:\developer\freetype-2.3.5\objs\win32\vc2008
set JPEGDIR=C:\Developer\jpeg
set ZLIBDIR=C:\developer\zlib123-dll
cmake -G "Visual Studio 9 2008" ..\podofo-src -DCMAKE_INCLUDE_PATH="%FTDIR%\include;%JPEGDIR%\include;%JPEGDIR%;%ZLIBDIR%\include" -DCMAKE_LIBRARY_PATH="%FTLIBDIR%;%FTDIR%\lib;%JPEGDIR%\lib;%JPEGDIR%;%ZLIBDIR%\lib" -DPODOFO_BUILD_SHARED:BOOL=FALSE -DFREETYPE_LIBRARY_NAMES_DEBUG=freetype239MT_D -DFREETYPE_LIBRARY_NAMES_RELEASE=freetype239MT
</pre>
<p>Run the saved <code>build.cmd</code> from a cmd.exe window. If all goes well, you can open and build the generated <code>podofo.sln</code> in Visual Studio and build it.</p>
<p>Note that CMake should automatically find your Visual Studio install, so you
shouldn't need any special settings unless you have an unusual setup or more
than copy of the same version of Visual Studio installed.</p>
<p>You can download the free Visual C++ Express Edition 9 from <a href="http://www.microsoft.com/express/">Microsoft</a>.</p>
<b>PROBLEMS?</b>
<p>If you have problems, try deleting your build directory then re-running
the commands above after running:</p>
<pre>
set PATH=%SystemRoot%;%SystemRoot%\SYSTEM32
</pre>
<p>in the <code>cmd.exe</code> window you are using. If you do this you'll have
to copy <code>jpeg62.dll</code>, <code>freetype6.dll</code>, and
<code>zlib.dll</code> (names may vary; make sure they're the ones that match
the LIB files you linked to) to the same folder as the .exe you are trying to
run. This should resolve any issues caused by incompatible DLLs with the same
names being present earlier on your PATH - a rather common issue if you have
lots of open source software installed. Do this if you get unexplained crashes
or errors about missing/mismatched ordinals.</p>
<h5><a name="cmake_builds_on_windows_with_nmake" />CMake builds on Windows with NMake</h5>
<p>PoDoFo can also be built with NMake. The build procedure is essentially the same
as described for MinGW or Visual Studio, but you must use the target name
"NMake Makefiles" and run "nmake" after CMake completes. Remember to run everything from
within a Visual Studio environment shell or to run vcvarsall.bat before running CMake.</p>
<p>With Visual C++ Express Edition 8, you must also separately run setenv.cmd from the Win32 SDK.
This is not required for Express Edition 9.</p>
<h2><a name="using_podofo_in_your_application" />Using PoDoFo in Your Application</a></h2>
<p>A simple example that uses PoDoFo can be found in <code>examples/helloworld</code> . You
will also find the tests and tools shipped with PoDoFo informative when
learning to use the library. Reading the documentation on <code>PdfMemDocument</code>,
<code>PdfStreamedDocument</code>, <code>PdfObject</code> and <code>PdfVariant</code> may also be useful.</p>
<h3><a name="unstable_api" />UNSTABLE API (IMPORTANT)</a></h3>
<p>It is very important to understand that PoDoFo's 0.x's API is not stable from
release to release. As such, rather than relying on a particular version of
PoDoFo being shipped by the OS/distro that you are targeting, consider building
and linking to your own private copy of PoDoFo. (Win32 developers will do this
anyway). For example, between PoDoFo 0.5.0 and early PoDoFo 0.6.0svn, <code>PdfDocument</code>
changed from being a concrete class to an abstract parent of <code>PdfMemDocument</code> and
<code>PdfStreamedDocument</code>, thus breaking code that instantiates <code>PdfDocument</code> .</p>
<p>A good way to handle maintaining your own private copy if you use Subversion
for your project is to use the svn:externals mechanism to automatically
reference a specific revision of PoDoFo from podofo svn, or a particular tag .
This permits you to control when you update to a new version and lets you make
sure your code is updated for any API changes, without forcing users to go and
find a specific version of PoDoFo. Alternately, you can just check the tree
into your own revision control system and do periodic code drops. Have a look
at PoDoFoBrowser for an example of the svn:externals approach.</p>
<p>If you statically link to podofo, that'll prevent any unexpected problems with
linker paths. Another option on most platforms is to use rpath linking to
ensure that a specific copy of the podofo library is preferred by the linker.
CMake takes care of this automatically if you're using it for your project.</p>
<p>When PoDoFo reaches 1.x versions it is expected that API changes will be
less frequent. At this point, though, they're an unavoidable part of
improving and completing the library.</p>
<p>If you are using CMake in your project and you choose to bundle a copy of
the PoDoFo sources, with svn:externals or otherwise, you can quite easily build
a private copy of PoDoFo as part of your app's normal build process. Have a look
at FindLIBPODOFO.cmake from PoDoFoBrowser to see how to do that, or just copy
that file.</p>
<h3><a name="compiling_and_linking_against_podofo"/>Compiling and Linking Against PoDoFo</h3>
<p>PoDoFo's headers are designed to avoid exposing its library dependencies, so
you do not need the headers for Freetype etc on the include path. However, you
MUST link your application to podofo's required libraries on most platforms, eg
on UNIX:</p>
<pre>
-lpodofo -lfreetype -lfontconfig -ljpeg -lz
</pre>
<p>is generally appropriate. Win32 users must also ensure that they link to
<code>gdi32</code> and <code>ws_win32</code>.</p>
<h3>Handling Exceptions</h3>
<p>When working with PoDoFo it is important to remember that the library makes use
of exceptions. Your code must be built with exception support and must be
exception safe in areas that call PoDoFo. gcc users may not build with
-fno-exceptions. If you have non-exception-safe code or code (such as pure C
code) that cannot propagate exceptions your podofo-using code must catch all
exceptions before they propagate to such unsafe sections. PoDoFo will throw a
PdfError& for PoDoFo-specific exceptions. It may also propagate STL/runtime
generated exceptions like std::bad_alloc, though it'll never throw them
directly. PoDoFo cannot be built without exceptions.</p>
<p>More general information about exception handling is in the <a href="FAQ.html">FAQ</a>.</p>
<h2><a name="preprocessor">Preprocessor defines used in PoDoFo</h2>
<p>Several preprocessor defines are used inside PoDoFo. This section tries to
document all of them. These defines are set automatically by the CMake build
system, so usually you do not have to worry about them.</p>
<table>
<tr>
<td><b>Define</b></td>
<td><b>Meaning</b></td>
</tr>
<tr>
<td><code>DEBUG</code></td>
<td>Indicates a debug build of PoDoFo.</td>
</tr>
<tr>
<td><code>PODOFO_EXTRA_CHECKS</code></td>
<td>Should we do lots of extra (expensive) sanity checking? You should not
define this on production builds because of the runtime cost and because it
might cause the library to abort() if it notices something nasty.
It may also change the size of some objects, and is thus not binary
compatible.
</td>
</tr>
<tr>
<td><code>PODOFO_IS_LITTLE_ENDIAN</code></td>
<td>This define is set on all little endian
system and required on these systems for PoDoFo to work properly.</td>
</tr>
<tr>
<td><code>PODOFO_IS_BIG_ENDIAN</code></td>
<td>This define is set on all big endian
system and required on these systems for PoDoFo to work properly.</td>
</tr>
<tr>
<td><code>PODOFO_MULTI_THREAD</code></td>
<td>Will compile PoDoFo with threading support, e.g. mutex that lock
global variables.</td>
</tr>
<tr>
<td><code>PODOFO_VERBOSE_DEBUG</code></td>
<td>This will cause PoDoFo to write even more debug output to the commandline.</td>
</tr>
<tr>
<td><code>HAVE_BOOST</code></td>
<td>If defined PoDoFo is compiled with Boost support.</td>
</tr>
<tr>
<td><code>PODOFO_HAVE_JPEG_LIB</code></td>
<td>If defined PoDoFo will use libJpeg to read and decode JPEG images.</td>
</tr>
<tr>
<td><code>PODOFO_HAVE_TIFF_LIB</code></td>
<td>If defined PoDoFo will use libTiff to read and decode TIFF images.</td>
</tr>
<tr>
<td><code>PODOFO_HAVE_LUA</code></td>
<td>If defined PoDoFoImpose will be built with Lua support for plan files.</td>
</tr>
</table>
<h2><a name="structure" />Structure of the library</h2>
<p>PoDoFo is structured into two libraries <b>podofo-base</b>
and <b>podofo-doc</b>, where most users want to use <b>podofo-doc</b> which
includes all the PoDoFo features and dependends on the <b>podofo-base</b>
library.
</p>
<p>
If you only need basic PDF editing features and are not afraid of working with
the object in a PDF file directly (see PdfObject), <b>podofo-base</b> is the
right choice for you. It has only a few dependencies (zlib and libjpeg for
compression). Contrary, <b>podofo-doc</b> provides you with a much richer and
easier to use interface, but has some more dependencies to handle fonts and
images. The image below shows the dependencies of each of the two
libraries.
</p>
<p align="center">
<img src="doc/podofo_architecture.png" alt="Architecture" />
</p>
<h2><a name="contact" />Contact</a></h2>
<p>If you have questions on PoDoFo or bug reports, feature requests you can email
our mailinglist <podofo-users@lists.sf.net>. Sign up details are available
on <a href="http://podofo.sourceforge.net/support.html#mail">the podofo support page</a>.</p>
<h2><a name="licensing" />Licensing</h2>
<p>The library is licensed under the LGPL (i.e. you may even use the shared
library in closed sourced applications). The tests and tools which are
included in PoDoFo are licensed under the GPL. See the files COPYING and
COPYING.LIB for details. More detailed explanations are in the FAQ on the
website, but the licenses have the final say.</p>
<h2>Appendices</h2>
<h3><a name="required_linux_packages">Required Linux Packages</a></h3>
<p>Linux distros love to name their packages in various weird ways. Here are commands to install the required -dev or -devel packages for PoDoFo for various distros. Please send additions for reasonably recent distros to the PoDoFo mailing list.</p>
<ul>
<li>Ubuntu (also generally applies to recent Debian)
<ul>
<li>8.10 and most others: sudo aptitude install build-essential g++ cmake libz-dev libtiff-dev libjpeg-dev libfreetype6-dev libfontconfig-dev</li>
</ul>
</li>
</ul>
</body>
</html>