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<libpng12-dev>
 149
 150 Redhat package: C<libpng-devel>
 151
 152 =head2 TIFF - C<libtiff>
 153
 154 X<< C<libtiff> >>L<Imager::File::TIFF> uses
 155 L<< C<libtiff> |http://www.remotesensing.org/libtiff/ >> for GIF image file
 156 support.
 157
 158 Version 3.6.0 or later is required to avoid an exploit with infinite
 159 IFD loops, though it's possible some distributions have applied the
 160 fix to older versions as a security fix.
 161
 162 Version 3.9.0 is rejected during the probe process due to a serious
 163 bug, fixed in 3.9.1.
 164
 165 Debian package: C<libtiff4-dev>
 166
 167 Redhat package: C<libtiff-devel>
 168
 169 =head2 GIF - C<libgif>
 170
 171 X<< C<libgif> >>L<Imager::File::GIF> uses
 172 L<< C<libgif> |http://sourceforge.net/projects/giflib/ >> for GIF image file
 173 support.
 174
 175 C<libgif> releases 4.2.0 and 5.0.0 are specifically not supported, due
 176 to bugs in those versions.
 177
 178 Release 4.1.4 or later should be used.
 179
 180 C<giflib> 3 is no longer supported.
 181
 182 C<libungif> is no longer supported as an alternative.
 183
 184 Debian package: C<libgif-dev>
 185
 186 Redhat package: C<giflib-devel>
 187
 188 =head2 JPEG - C<libjpeg>
 189
 190 L<Imager::File::JPEG> uses L<< C<libjpeg> |http://www.ijg.org/ >> for JPEG
 191 image file support.
 192
 193 You may also use
 194 L<< C<libjpeg-turbo> |http://sourceforge.net/projects/libjpeg-turbo/ >>.
 195
 196 To install older releases of C<libjpeg> from source, you'll need to
 197 run:
 198
 199   make install-lib
 200
 201 to install the libraries.  C<make install> only installs the program
 202 binaries.
 203
 204 Redhat package: C<libjpeg-devel>
 205
 206 Debian package: C<libjpeg8-dev>
 207
 208 =head2 Freetype 2.x - C<libfreetype>
 209
 210 L<Imager::Font::FT2> uses L<< Freetype 2
 211 (C<libfreetype>)|http://www.freetype.org/ >> for font support, supporting
 212 too many font formats to mention here.
 213
 214 This is the recommended library to use for font support.
 215
 216 Debian package: C<libfreetype6-dev>
 217
 218 Redhat package: C<freetype-devel>
 219
 220 =head2 Win32 GDI fonts
 221
 222 L<Imager::Font::W32> uses L<Win32
 223 GDI|http://msdn.microsoft.com/en-us/library/dd145203%28v=vs.85%29.aspx>
 224 to render text using installed Windows fonts.
 225
 226 This requires Win32 SDK headers and libraries, and is only expected to
 227 work on native Win32 or Cygwin.
 228
 229 For this to work under Cygwin, install the C<w32api-headers> and
 230 C<w32api-runtime> packages.
 231
 232 =head2 C<t1lib>
 233
 234 L<Imager::Font::T1> uses L<< C<t1lib> |http://www.t1lib.org/ >> for
 235 font support, supporting Postscript Type 1 fonts only.
 236
 237 Debian package: C<libt1-dev>
 238
 239 Redhat package: C<t1lib-devel>
 240
 241 =head2 Freetype 1.x - C<libttf>
 242
 243 Imager uses L<< Freetype 1 (C<libttf>)|http://www.freetype.org/ >> if
 244 available for font support, supporting TTF fonts only.
 245
 246 Freetype 1.x is essentially unsupported and shouldn't be used for new
 247 code.
 248
 249 =head1 PLATFORM SPECIFICS
 250
 251 =head2 Linux
 252
 253 Several distributions include an Imager package, but they are
 254 typically several releases behind due to the nature of release cycles.
 255
 256 Imager typically supports the external libraries as packaged with any
 257 supported release of Linux.
 258
 259 =head3 Debian
 260
 261 To install the libraries used by Imager under Debian (or Ubuntu), run
 262 as root (or with sudo):
 263
 264   apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
 265
 266 You may also need to install development tools:
 267
 268   apt-get install build-essential
 269
 270 =head3 Redhat
 271
 272 To install the libraries used by Imager under Redhat and related Linux
 273 distributions, run as root (or sudo):
 274
 275   yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
 276
 277 To install the development tools needed:
 278
 279   yum install gcc
 280
 281 (which appears to be enough on a base Redhat-like install) or the more
 282 commonly recommended recipe:
 283
 284   yum groupinstall "Development Tools"
 285
 286 which is massive overkill.
 287
 288 =head2 Mac OS X
 289
 290 =head3 Building libraries
 291
 292 The default perl build in Snow Leopard and Lion is a fat binary, and
 293 default builds of C<giflib>, C<libpng> and C<libjpeg> (and maybe other
 294 libraries) will produce link failures.
 295
 296 To avoid this you need to supply a C<CFLAGS> parameter to the
 297 library's configure script, but since the C<-arch> flag conflicts with
 298 the options used to build the dependency files, you need to supply
 299 another flag to disable dependency tracking.
 300
 301 Snow Leopard fat binaries include C<i386>, C<x86_64> and C<PPC>
 302 objects, hence you would run configure like:
 303
 304   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
 305
 306 Lion doesn't support C<PPC>, so there you run configure like:
 307
 308   ./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
 309
 310 For C<libgif> you might also want to supply the C<--without-x> option:
 311
 312   ./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
 313
 314 If you copy library files into place manually, you may need to run
 315 C<ranlib> on them in their new location:
 316
 317   ranlib /usr/local/lib/libgif.a
 318
 319 =head3 Macintosh C<dfont> and suitcase font support
 320
 321 Through Freetype 2.1, Imager can use Macintosh C<DFON> (C<.dfont>)
 322 fonts and suitcase font files.
 323
 324 If you want to be able to use more than just the first face in the
 325 font file though, you will need to configure C<freetype2> with the
 326 --with-old-mac-fonts option:
 327
 328   ./configure --with-old-mac-fonts
 329
 330 You can use the index option to get to the other font faces in the
 331 file:
 332
 333   # get the second face from $file
 334   my $font = Imager::Font->new(file=>$file, index=>1)
 335     or die Imager->errstr;
 336
 337 If you're using a suitcase font, you will also need to force the use
 338 of Freetype 2 with the type argument:
 339
 340   my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
 341     or die Imager->errstr;
 342
 343 =head2 Microsoft Windows
 344
 345 The simplest way to install the libraries used by Imager is to install
 346 L<Strawberry perl|http://strawberryperl.com/>.
 347
 348 You can then use either the bundled Imager, or install from CPAN.
 349
 350 If you get errors from your make tool, make sure you're using the same
 351 make that was used to build your perl - C<nmake> for Visual C/C++ and
 352 C<dmake> for MinGW, run:
 353
 354   perl -V:make
 355
 356 to see which make was used to build your perl.
 357
 358 =head2 Cygwin
 359
 360 To build Imager with as much library support as possible on Cygwin,
 361 install the following packages:
 362
 363   libjpeg-devel libpng-devel libgif-devel libtiff-devel
 364   libfreetype-devel t1lib-devel w32api-headers w32api-runtime
 365
 366 If you see an error under cygwin during testing along the lines of:
 367
 368   C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
 369     same address as parent (0x...) != 0x....
 370
 371 you will need to install the cygwin C<rebase> package and run:
 372
 373   $ rebaseall -v
 374
 375 or possibly, just:
 376
 377   $ perlrebase
 378
 379 will fix the problem.
 380
 381 =head1 Other issues
 382
 383 =head2 Freetype 1.x vs Freetype 2.x
 384
 385 Freetype 1.x is no longer recommended, is no longer supported
 386 upstream, and receives only limited updates in Imager.
 387
 388 These two libraries have some conflicting include file names, but as
 389 long as you don't put the Freetype 2.x F<freetype.h> directory in the
 390 include path it should all work.
 391
 392 Put the directory containing F<ft2build.h> in the include path, but
 393 not the directory containing the freetype 2.x F<freetype.h>.
 394
 395 If you see compilation errors from font.c you've probably made the
 396 mistake of putting the Freetype 2.x F<freetype.h> directory into the
 397 include path.
 398
 399 To see which directories should be in the include path, try:
 400
 401   freetype-config --cflags
 402
 403 Ideally, C<freetype-config> should be in the PATH when building Imager
 404 with freetype 2.x support, in which case L<Imager::Font::FT2> can
 405 configure itself.
 406
 407 =head1 AUTHOR
 408
 409 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
 410
 411 =cut