lib/Imager/Install.pod

   1 =for stopwords freetype MinGW dfont Redhat SDK IFD GDI TTF preprocessor Redhat-like
   2
   3 =head1 NAME
   4
   5 Imager::Install - installation notes for Imager
   6
   7 =head1 SYNOPSIS
   8
   9   perl Makefile.PL
  10   make
  11   make test
  12   make install
  13
  14 =head1 DESCRIPTION
  15
  16 Assuming you have all of your required libraries in the places Imager
  17 looks, you should be able to use the standard mantra:
  18
  19   perl Makefile.PL
  20   make
  21   make test
  22   make install
  23
  24 to install Imager.
  25
  26 If you've installed libraries in places Imager doesn't look, you can
  27 supply extra locations either with command-line options:
  28
  29   perl Makefile.PL --libpath=/home/tony/local/lib --incpath=/home/tony/local/include
  30
  31 or with environment variables:
  32
  33   export IM_LIBPATH=/home/tony/local/lib IM_INCPATH=/home/tony/local/include
  34   perl Makefile.PL
  35
  36 Imager's F<Makefile.PL> produces an epilogue indicating which
  37 libraries have and haven't been found, for example:
  38
  39   Libraries found:
  40     FT2
  41     GIF
  42     JPEG
  43     PNG
  44     T1
  45     TIFF
  46   Libraries *not* found:
  47     Win32
  48
  49 If a library you expect to be found isn't on this list, use the
  50 C<--verbose> or C<-v> option to produce way too much information from
  51 Imager's search for the libraries:
  52
  53   perl Makefile.PL -v
  54
  55 If you can't resolve this, then run
  56
  57   perl errep.perl
  58
  59 and include the (large) generated F<report.txt> in your email to:
  60
  61   bug-Imager@rt.cpan.org
  62
  63 There are other options used to configure how Imager is built:
  64
  65 =over
  66
  67 =item C<--nolog>
  68
  69 build Imager without logging support.  This will speed up Imager a
  70 little.  You can also remove logging by setting the C<IMAGER_NOLOG>
  71 environment variable to a true value.
  72
  73 =item C<--coverage>
  74
  75 used to build Imager for C<gcov> coverage testing.  This is intended
  76 for development and also requires options supplied to C<make>.
  77
  78 =item C<--assert>
  79
  80 build Imager with assertions enabled.
  81
  82 =item C<--tracecontext>
  83
  84 build Imager to trace context object management to C<stderr> for
  85 debugging.
  86
  87 =back
  88
  89 =head2 Build time environment variables
  90 X<build time environment variables>
  91
  92 =over
  93
  94 =item *
  95
  96 X<< C<IMAGER_NOLOG> >>C<IMAGER_NOLOG> - build Imager with logging disabled.
  97
  98 =item *
  99
 100 X<< C<IMAGER_DEBUG_MALLOC> >>C<IMAGER_DEBUG_MALLOC> - build Imager with it's
 101 debug malloc wrappers.  This is I<not> compatible with threaded code.
 102
 103 =item *
 104
 105 X<< C<IM_INCPATH> >>C<IM_INCPATH> - equivalent to C<--incpath>.
 106
 107 =item *
 108
 109 X<< C<IM_LIBPATH> >>C<IM_LIBPATH> - equivalent to C<--libpath>.
 110
 111 =item *
 112
 113 X<< C<IM_VERBOSE> >>C<IM_VERBOSE> - equivalent to C<--verbose>
 114
 115 =item *
 116
 117 X<< C<IM_CFLAGS> >>C<IM_CFLAGS> - extra C compiler flags.
 118
 119 =item *
 120
 121 X<< C<IM_LFLAGS> >>C<IM_LFLAGS> - extra linker flags.
 122
 123 =item *
 124
 125 X<< C<IM_DFLAGS> >>C<IM_DFLAGS> - extra preprocessor flags.
 126
 127 =back
 128
 129 =head1 EXTERNAL LIBRARIES
 130
 131 Some of the file format and font modules included with Imager use
 132 external libraries, which should be installed before you try to
 133 install Imager itself.
 134
 135 If you don't have the libraries installed then Imager itself will
 136 install successfully, but the file format or font support module won't
 137 be.
 138
 139 Preferably the latest version of each library should be used, simple
 140 because it has the latest security fixes.
 141
 142 =head2 PNG - C<libpng>
 143
 144 X<< C<libpng> >>L<Imager::File::PNG> uses L<< C<libpng>
 145 |http://www.libpng.org/pub/png/libpng.html >> for PNG image file
 146 support.
 147
 148 Debian package: C<libpng-dev>
 149
 150 Redhat package: C<libpng-devel>
 151
 152 Cygwin: C<libpng-devel>
 153
 154 =head2 TIFF - C<libtiff>
 155
 156 X<< C<libtiff> >>L<Imager::File::TIFF> uses
 157 L<< C<libtiff> |http://www.remotesensing.org/libtiff/ >> for GIF image file
 158 support.
 159
 160 Version 3.6.0 or later is required to avoid an exploit with infinite
 161 IFD loops, though it's possible some distributions have applied the
 162 fix to older versions as a security fix.
 163
 164 Version 3.9.0 is rejected during the probe process due to a serious
 165 bug, fixed in 3.9.1.
 166
 167 Debian package: C<libtiff4-dev>
 168
 169 Redhat package: C<libtiff-devel>
 170
 171 Cygwin: C<libtiff-devel>
 172
 173 =head2 GIF - C<libgif>
 174
 175 X<< C<libgif> >>L<Imager::File::GIF> uses
 176 L<< C<libgif> |http://sourceforge.net/projects/giflib/ >> for GIF image file
 177 support.
 178
 179 C<libgif> releases 4.2.0 and 5.0.0 are specifically not supported, due
 180 to bugs in those versions.
 181
 182 Release 4.1.4 or later should be used.
 183
 184 C<giflib> 3 is no longer supported.
 185
 186 C<libungif> is no longer supported as an alternative.
 187
 188 Debian package: C<libgif-dev>
 189
 190 Redhat package: C<giflib-devel>
 191
 192 Cygwin: C<libgif-devel>
 193
 194 =head2 JPEG - C<libjpeg>
 195
 196 L<Imager::File::JPEG> uses L<< C<libjpeg> |http://www.ijg.org/ >> for JPEG
 197 image file support.
 198
 199 You may also use
 200 L<< C<libjpeg-turbo> |http://sourceforge.net/projects/libjpeg-turbo/ >>.
 201
 202 To install older releases of C<libjpeg> from source, you'll need to
 203 run:
 204
 205   make install-lib
 206
 207 to install the libraries.  C<make install> only installs the program
 208 binaries.
 209
 210 Redhat package: C<libjpeg-devel>
 211
 212 Debian package: C<libjpeg-dev>
 213
 214 Cygwin: C<libjpeg-devel>
 215
 216 =head2 Freetype 2.x - C<libfreetype>
 217
 218 L<Imager::Font::FT2> uses L<< Freetype 2
 219 (C<libfreetype>)|http://www.freetype.org/ >> for font support, supporting
 220 too many font formats to mention here.
 221
 222 This is the recommended library to use for font support.
 223
 224 Debian package: C<libfreetype6-dev>
 225
 226 Redhat package: C<freetype-devel>
 227
 228 Cygwin: C<libfreetype-devel>
 229
 230 =head2 Win32 GDI fonts
 231
 232 L<Imager::Font::W32> uses L<Win32
 233 GDI|http://msdn.microsoft.com/en-us/library/dd145203%28v=vs.85%29.aspx>
 234 to render text using installed Windows fonts.
 235
 236 This requires Win32 SDK headers and libraries, and is only expected to
 237 work on native Win32 or Cygwin.
 238
 239 For this to work under Cygwin, install the C<w32api-headers> and
 240 C<w32api-runtime> packages.
 241
 242 =head2 C<t1lib>
 243
 244 L<Imager::Font::T1> uses L<< C<t1lib> |http://www.t1lib.org/ >> for
 245 font support, supporting Postscript Type 1 fonts only.
 246
 247 T1Lib is abandonware, the latest released version has several bugs
 248 that reliably crash on 64-bit systems.
 249
 250 Expect C<Imager::Font::T1> to be unbundled from the Imager
 251 distribution at some point.
 252
 253 Debian package: C<libt1-dev>
 254
 255 Redhat package: C<t1lib-devel>
 256
 257 =head2 Freetype 1.x - C<libttf>
 258
 259 Imager uses L<< Freetype 1 (C<libttf>)|http://www.freetype.org/ >> if
 260 available for font support, supporting TTF fonts only.
 261
 262 Freetype 1.x is essentially unsupported and shouldn't be used for new
 263 code.
 264
 265 Expect Freetype 1 support to be removed from Imager at some point.
 266
 267 =head1 PLATFORM SPECIFICS
 268
 269 =head2 Linux
 270
 271 Several distributions include an Imager package, but they are
 272 typically several releases behind due to the nature of release cycles.
 273
 274 Imager typically supports the external libraries as packaged with any
 275 supported release of Linux.
 276
 277 =head3 Debian
 278
 279 To install the libraries used by Imager under Debian (or Ubuntu), run
 280 as root (or with sudo):
 281
 282   apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
 283
 284 You may also need to install development tools:
 285
 286   apt-get install build-essential
 287
 288 =head3 Redhat
 289
 290 To install the libraries used by Imager under Redhat and related Linux
 291 distributions, run as root (or sudo):
 292
 293   yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
 294
 295 To install the development tools needed:
 296
 297   yum install gcc
 298
 299 (which appears to be enough on a base Redhat-like install) or the more
 300 commonly recommended recipe:
 301
 302   yum groupinstall "Development Tools"
 303
 304 which is massive overkill.
 305
 306 =head2 Mac OS X
 307
 308 =head3 Building libraries
 309
 310 The default perl build in Snow Leopard and Lion is a fat binary, and
 311 default builds of C<giflib>, C<libpng> and C<libjpeg> (and maybe other
 312 libraries) will produce link failures.
 313
 314 To avoid this you need to supply a C<CFLAGS> parameter to the
 315 library's configure script, but since the C<-arch> flag conflicts with
 316 the options used to build the dependency files, you need to supply
 317 another flag to disable dependency tracking.
 318
 319 Snow Leopard fat binaries include C<i386>, C<x86_64> and C<PPC>
 320 objects, hence you would run configure like:
 321
 322   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
 323
 324 Lion doesn't support C<PPC>, so there you run configure like:
 325
 326   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
 327
 328 For C<libgif> you might also want to supply the C<--without-x> option:
 329
 330   ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
 331
 332 If you copy library files into place manually, you may need to run
 333 C<ranlib> on them in their new location:
 334
 335   ranlib /usr/local/lib/libgif.a
 336
 337 =head3 Macintosh C<dfont> and suitcase font support
 338
 339 Through Freetype 2.1, Imager can use Macintosh C<DFON> (C<.dfont>)
 340 fonts and suitcase font files.
 341
 342 If you want to be able to use more than just the first face in the
 343 font file though, you will need to configure C<freetype2> with the
 344 --with-old-mac-fonts option:
 345
 346   ./configure --with-old-mac-fonts
 347
 348 You can use the index option to get to the other font faces in the
 349 file:
 350
 351   # get the second face from $file
 352   my $font = Imager::Font->new(file=>$file, index=>1)
 353     or die Imager->errstr;
 354
 355 If you're using a suitcase font, you will also need to force the use
 356 of Freetype 2 with the type argument:
 357
 358   my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
 359     or die Imager->errstr;
 360
 361 =head2 Microsoft Windows
 362
 363 The simplest way to install the libraries used by Imager is to install
 364 L<Strawberry perl|http://strawberryperl.com/>.
 365
 366 You can then use either the bundled Imager, or install from CPAN.
 367
 368 If you get errors from your make tool, make sure you're using the same
 369 make that was used to build your perl - C<nmake> for Visual C/C++ and
 370 C<dmake> for MinGW, run:
 371
 372   perl -V:make
 373
 374 to see which make was used to build your perl.
 375
 376 =head2 Cygwin
 377
 378 To build Imager with as much library support as possible on Cygwin,
 379 install the following packages:
 380
 381   libjpeg-devel libpng-devel libgif-devel libtiff-devel
 382   libfreetype-devel t1lib-devel w32api-headers w32api-runtime
 383
 384 If you see an error under cygwin during testing along the lines of:
 385
 386   C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
 387     same address as parent (0x...) != 0x....
 388
 389 you will need to install the cygwin C<rebase> package and run:
 390
 391   $ rebaseall -v
 392
 393 or possibly, just:
 394
 395   $ perlrebase
 396
 397 will fix the problem.  64-bit Cygwin significantly reduces occurrences
 398 of this problem.
 399
 400 =head1 Other issues
 401
 402 =head2 Freetype 1.x vs Freetype 2.x
 403
 404 Freetype 1.x is no longer recommended, is no longer supported
 405 upstream, and receives only limited updates in Imager.
 406
 407 These two libraries have some conflicting include file names, but as
 408 long as you don't put the Freetype 2.x F<freetype.h> directory in the
 409 include path it should all work.
 410
 411 Put the directory containing F<ft2build.h> in the include path, but
 412 not the directory containing the freetype 2.x F<freetype.h>.
 413
 414 If you see compilation errors from font.c you've probably made the
 415 mistake of putting the Freetype 2.x F<freetype.h> directory into the
 416 include path.
 417
 418 To see which directories should be in the include path, try:
 419
 420   freetype-config --cflags
 421
 422 Ideally, C<freetype-config> should be in the PATH when building Imager
 423 with freetype 2.x support, in which case L<Imager::Font::FT2> can
 424 configure itself.
 425
 426 =head1 AUTHOR
 427
 428 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
 429
 430 =cut