home *** CD-ROM | disk | FTP | other *** search
/ PC World 2002 February / PCWorld_2002-02_cd.bin / Software / Vyzkuste / pdflib / pdflib-4.0.1.sit / pdflib-4.0.1 / doc / readme_unix.txt < prev    next >
Encoding:
Text File  |  2001-07-04  |  9.4 KB  |  242 lines  |  [TEXT/ttxt]
  1. Building PDFlib on Unix systems
  2. ===============================
  3.  
  4. Building PDFlib
  5. ---------------
  6.  
  7. To start the build process on Unix, type
  8.  
  9. unix> ./configure
  10. unix> make
  11. unix> make test
  12.  
  13. Several options can used with the configure script in order to
  14. override some default configuration options, or to assist configure
  15. in finding some software locations on your machine. Type
  16.  
  17. unix> ./configure --help
  18.  
  19. before the make command in order to see a list of available configure
  20. options.
  21.  
  22. IMPORTANT: make sure to use only absolute path names for all custom
  23. directories. Also, wildcards should not be used. This requirement is
  24. necessary because otherwise the paths won't work as include paths with
  25. compiler calls.
  26.  
  27. If you want to use PDFlib on another machine, do not simply copy
  28. the PDFlib source tree over. Instead, copy the distribution fileset
  29. and re-run the configure script. Otherwise compiler, shared library
  30. and installation settings could erroneously be taken from the first
  31. machine instead of from the actual one.
  32.  
  33. Note that in very rare cases it may be necessary to rename the generated
  34. library file in order to avoid name clashes when installing it. This
  35. can be achieved with configure's --with-pdflibname option. Currently this
  36. problem is known to exist on Digital Unix 4.
  37.  
  38.  
  39. Testing and installing the library
  40. ----------------------------------
  41.  
  42. Optionally, to run sample PDFlib applications in several programming
  43. environments (including the scripting languages which have been
  44. detected by configure), type:
  45.  
  46. unix> make test
  47.  
  48. In order to install the library and the support files for all detected
  49. scripting languages, type
  50.  
  51. # make install
  52.  
  53. Note that installing will usually require root privileges.
  54.  
  55. If you want to install only selected parts (e.g., only the PDFlib
  56. C library or the Perl support), type "make install" in the
  57. respective subdirectory (e.g, bind/perl), or (equivalently) type
  58. "make pdflib_perl_install".
  59.  
  60.  
  61. configure troubleshooting
  62. -------------------------
  63.  
  64. The configure script helps to keep PDFlib portable across a wide variety
  65. of systems, and to keep track of many different configurations and
  66. the availability of features. Generally the script does a good job.
  67. Given the huge number of different systems, configure may occasionally
  68. fail in one of several ways:
  69.  
  70. - failing to detect installed software
  71.  
  72. - failing to complete all tests due to errors during script execution
  73.  
  74. In the first case, you can help configure by finding out the necessary
  75. paths etc. yourself, and supplying any required --with-... option on
  76. the configure command line.
  77.  
  78. In the second case, you either also can try to supply --with-... options
  79. in order to prevent the failing test from being called, or abandon
  80. the feature if you don't need it by supplying the value "no" to the
  81. respective configure option, e.g., --with-tcl=no.
  82.  
  83. If you can determine the cause of a failing configure script, we will
  84. be happy to hear from you. Please supply your system details, the
  85. feature/option in question, and a workaround or improvement if possible.
  86.  
  87. The configure script may  fail under Cygwin when trying to probe for languages
  88. if path names contain space characters.
  89. It's safer to disable language probing using --with-perl=no etc.
  90.  
  91.  
  92. Forcing a certain compiler or compiler flags
  93. --------------------------------------------
  94.  
  95. You can set several environment variables before running the configure
  96. script. These variables will be used in the generated Makefiles. The more
  97. important ones are:
  98.  
  99. CC       The C compiler to use
  100. CXX      The C++ compiler to use
  101. CFLAGS   C compiler flags
  102. LDFLAGS     linker flags, such as additional libraries
  103.  
  104. For example, the following works well on Solaris (in a csh environment):
  105.  
  106. setenv CC /opt/SUNWspro/bin/cc
  107. setenv CXX /opt/SUNWspro/bin/CC
  108. setenv CFLAGS '-fast -xO3 -xtarget=generic'
  109. ./configure
  110.  
  111.  
  112. Shared library support
  113. ----------------------
  114.  
  115. Language bindings other than C/C++ require shared library support for
  116. PDFlib to work. By default, the PDFlib core library will be built as both
  117. a static and a shared library if possible.
  118.  
  119. C or C++ language clients must deploy libtool for using PDFlib, or install
  120. the generated PDFlib library using "make install".
  121.  
  122. PDFlib relies on GNU libtool for shared library support. libtool
  123. shadows the object files and libraries with a layer of .lo and .la
  124. files. The actual library files are placed in a subdirectory called
  125. ".libs". The PDFlib Makefiles and libtool will take care of correctly
  126. building, testing, and installing these libraries. If anything goes
  127. wrong on your system, read the manual section on shared libraries,
  128. take a look at the contents of the .libs subdirectory, and observe
  129. what the supplied Makefiles do for compiling, linking, testing, and
  130. installing.
  131.  
  132.  
  133. Auxiliary libraries
  134. -------------------
  135.  
  136. Starting with version 4.0, PDFlib includes portions of the libtiff, zlib,
  137. and libpng auxiliary libraries as part of the distribution package. These
  138. libraries have been modified for use with PDFlib in several ways:
  139.  
  140. - all function names are prefixed with a PDFlib-private tag
  141. - code which is not required for PDFlib has been removed
  142. - a number of portability changes have been applied
  143.  
  144. Our build process directly links these libraries into the PDFlib binary,
  145. regardless of whether a shared or static PDFlib is generated. We no longer
  146. use external versions of these libraries for various reasons:
  147.  
  148. - an integrated build process generates a full-blown PDFlib with all features
  149. - the user doesn't have to struggle with building other libraries
  150. - most importantly, not all language bindings can be made to work
  151.   reliably when multiple shared libraries are involved
  152.  
  153. Due to the prefixed function names an application can link against both
  154. a full-blown PDFlib (including all auxiliary libraries) and standard
  155. versions of these libs.
  156.  
  157. People who insist on using the standard versions of the auxiliary libs
  158. can do so if they observe the following:
  159.  
  160. - The --with-tifflib, --with-zlib, --with-pnglib options of the configure
  161.   script must be used to replace PDFlib's internal version of a library.
  162.  
  163. - If one of libpng and libz is replaced, the other one must be replaced, too.
  164.   This is required because of the PDFlib-specific function name prefix
  165.   which is used in the internal versions, and because libpng requires
  166.   libz in turn. Internal and external versions of these libs just won't
  167.   match.
  168.  
  169. - Libraries which shall be replaced must be installed in some "standard"
  170.   system location, or in some private directory which is specified in
  171.   an appropriate -L option in the LDFLAGS environment variable, for example:
  172.  
  173.   LDFLAGS=/home/tm/libs/libtiff configure --with-tifflib
  174.  
  175.   The specified directory must contain a usable static library, and the
  176.   option will be included in the list of options which are required for
  177.   linking an application against PDFlib (as reported by pdflib-config --libs).
  178.  
  179. - Replacing any one library will disable all language bindings except
  180.   C and C++.
  181.   
  182.  
  183. Querying PDFlib configuration info
  184. ----------------------------------
  185.  
  186. In order to find out details about PDFlib's version, configuration,
  187. and use, the pdflib-config shell script can be used. It is built during
  188. the configure run, and returns all information you'll need for PDFlib
  189. deployment. Running the script without any options lists the supported
  190. command line options.
  191.  
  192.  
  193. Problems viewing the PDFlib purchase order form
  194. -----------------------------------------------
  195.  
  196. If you experience the error message "Unable to extract the embedded
  197. font..." while viewing the form under Unix or Linux, you are running into
  198. a bug in Acrobat Reader which affects non-english locale settings.
  199. Workarounds: use a different PDF viewer (e.g., xpdf or Ghostscript), or set
  200. the LANG variable to either "C" or empty before launching Acrobat:
  201.  
  202. unix> LANG=C acroread PDFlib-purchase-order.pdf
  203.  
  204.  
  205. Library version numbers
  206. -----------------------
  207.  
  208. Libtool-generated libraries such as PDFlib number their interfaces
  209. with integer interface numbers (no subversions!). In addition to the
  210. interface number, a revision number can be used. A particular library
  211. supports a range of interface numbers, where the range can have a length
  212. of one or more. In particular, libtool defines the following:
  213.  
  214. CURRENT   The most recent interface number that this library implements.
  215. REVISION  The implementation number of the CURRENT interface.
  216. AGE       The length of the range of supported interfaces (i.e., CURRENT
  217.           numbers).
  218.  
  219. The following table relates PDFlib version numbers to the C:R:A library
  220. versioning scheme used by libtool. Note that these numbers will not show
  221. up in the PDFlib shared library file name directly, but in some modified form
  222. which is system-dependent:
  223.  
  224. PDFlib    C:R:A   comments
  225. -------------------------------------------------------------------------------
  226. 3.00      0:0:0   first release based on libtool
  227. 3.01      0:1:0   maintenance release (bug: should have increased C since
  228.                   undocumented functions were removed)
  229. 3.02      1:0:0   cleans up the non-incrementing glitch in 3.01
  230. 3.03      1:1:1   maintenance release (bug: should not have increased A)
  231. 4.0.0b    2:0:2   new API functions (inherits the 3.03 bug)
  232. 4.0.0     2:0:1   cleanup for major release: repairs the 3.03 "age" bug
  233. 4.0.1     2:1:1   maintenance release
  234.  
  235. When the PDFlib core is built as a static library version numbers will not
  236. be visible. However, since language bindings other than C and C++ are always
  237. built as shared libraries, they will have version numbers visible on most
  238. systems.
  239.  
  240. Many thanks to Evgeny Stambulchik for leading me on the right track
  241. with respect to libtool and library versioning schemes!
  242.