Initial Commit
This commit is contained in:
Riley Schneider
433
database/perl/vendor/lib/Imager/Install.pod
vendored
Normal file
433
database/perl/vendor/lib/Imager/Install.pod
vendored
Normal file
@@ -0,0 +1,433 @@
|
||||
=for stopwords freetype MinGW dfont Redhat SDK IFD GDI TTF preprocessor Redhat-like
|
||||
|
||||
=head1 NAME
|
||||
|
||||
Imager::Install - installation notes for Imager
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
perl Makefile.PL
|
||||
make
|
||||
make test
|
||||
make install
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
Assuming you have all of your required libraries in the places Imager
|
||||
looks, you should be able to use the standard mantra:
|
||||
|
||||
perl Makefile.PL
|
||||
make
|
||||
make test
|
||||
make install
|
||||
|
||||
to install Imager.
|
||||
|
||||
If you've installed libraries in places Imager doesn't look, you can
|
||||
supply extra locations either with command-line options:
|
||||
|
||||
perl Makefile.PL --libpath=/home/tony/local/lib --incpath=/home/tony/local/include
|
||||
|
||||
or with environment variables:
|
||||
|
||||
export IM_LIBPATH=/home/tony/local/lib IM_INCPATH=/home/tony/local/include
|
||||
perl Makefile.PL
|
||||
|
||||
Imager's F<Makefile.PL> produces an epilogue indicating which
|
||||
libraries have and haven't been found, for example:
|
||||
|
||||
Libraries found:
|
||||
FT2
|
||||
GIF
|
||||
JPEG
|
||||
PNG
|
||||
T1
|
||||
TIFF
|
||||
Libraries *not* found:
|
||||
Win32
|
||||
|
||||
If a library you expect to be found isn't on this list, use the
|
||||
C<--verbose> or C<-v> option to produce way too much information from
|
||||
Imager's search for the libraries:
|
||||
|
||||
perl Makefile.PL -v
|
||||
|
||||
If you can't resolve this, then run
|
||||
|
||||
perl errep.perl
|
||||
|
||||
and include the (large) generated F<report.txt> in your email to:
|
||||
|
||||
bug-Imager@rt.cpan.org
|
||||
|
||||
There are other options used to configure how Imager is built:
|
||||
|
||||
=over
|
||||
|
||||
=item C<--nolog>
|
||||
|
||||
build Imager without logging support. This will speed up Imager a
|
||||
little. You can also remove logging by setting the C<IMAGER_NOLOG>
|
||||
environment variable to a true value.
|
||||
|
||||
=item C<--coverage>
|
||||
|
||||
used to build Imager for C<gcov> coverage testing. This is intended
|
||||
for development and also requires options supplied to C<make>.
|
||||
|
||||
=item C<--assert>
|
||||
|
||||
build Imager with assertions enabled.
|
||||
|
||||
=item C<--tracecontext>
|
||||
|
||||
build Imager to trace context object management to C<stderr> for
|
||||
debugging.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Build time environment variables
|
||||
X<build time environment variables>
|
||||
|
||||
=over
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IMAGER_NOLOG> >>C<IMAGER_NOLOG> - build Imager with logging disabled.
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IMAGER_DEBUG_MALLOC> >>C<IMAGER_DEBUG_MALLOC> - build Imager with it's
|
||||
debug malloc wrappers. This is I<not> compatible with threaded code.
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IM_INCPATH> >>C<IM_INCPATH> - equivalent to C<--incpath>.
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IM_LIBPATH> >>C<IM_LIBPATH> - equivalent to C<--libpath>.
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IM_VERBOSE> >>C<IM_VERBOSE> - equivalent to C<--verbose>
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IM_CFLAGS> >>C<IM_CFLAGS> - extra C compiler flags.
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IM_LFLAGS> >>C<IM_LFLAGS> - extra linker flags.
|
||||
|
||||
=item *
|
||||
|
||||
X<< C<IM_DFLAGS> >>C<IM_DFLAGS> - extra preprocessor flags.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXTERNAL LIBRARIES
|
||||
|
||||
Some of the file format and font modules included with Imager use
|
||||
external libraries, which should be installed before you try to
|
||||
install Imager itself.
|
||||
|
||||
If you don't have the libraries installed then Imager itself will
|
||||
install successfully, but the file format or font support module won't
|
||||
be.
|
||||
|
||||
Preferably the latest version of each library should be used, simple
|
||||
because it has the latest security fixes.
|
||||
|
||||
=head2 PNG - C<libpng>
|
||||
|
||||
X<< C<libpng> >>L<Imager::File::PNG> uses L<< C<libpng>
|
||||
|http://www.libpng.org/pub/png/libpng.html >> for PNG image file
|
||||
support.
|
||||
|
||||
Debian package: C<libpng-dev>
|
||||
|
||||
Redhat package: C<libpng-devel>
|
||||
|
||||
Cygwin: C<libpng-devel>
|
||||
|
||||
=head2 TIFF - C<libtiff>
|
||||
|
||||
X<< C<libtiff> >>L<Imager::File::TIFF> uses
|
||||
L<< C<libtiff> |http://www.remotesensing.org/libtiff/ >> for GIF image file
|
||||
support.
|
||||
|
||||
Version 3.6.0 or later is required to avoid an exploit with infinite
|
||||
IFD loops, though it's possible some distributions have applied the
|
||||
fix to older versions as a security fix.
|
||||
|
||||
Version 3.9.0 is rejected during the probe process due to a serious
|
||||
bug, fixed in 3.9.1.
|
||||
|
||||
Debian package: C<libtiff4-dev>
|
||||
|
||||
Redhat package: C<libtiff-devel>
|
||||
|
||||
Cygwin: C<libtiff-devel>
|
||||
|
||||
=head2 GIF - C<libgif>
|
||||
|
||||
X<< C<libgif> >>L<Imager::File::GIF> uses
|
||||
L<< C<libgif> |http://sourceforge.net/projects/giflib/ >> for GIF image file
|
||||
support.
|
||||
|
||||
C<libgif> releases 4.2.0 and 5.0.0 are specifically not supported, due
|
||||
to bugs in those versions.
|
||||
|
||||
Release 4.1.4 or later should be used.
|
||||
|
||||
C<giflib> 3 is no longer supported.
|
||||
|
||||
C<libungif> is no longer supported as an alternative.
|
||||
|
||||
Debian package: C<libgif-dev>
|
||||
|
||||
Redhat package: C<giflib-devel>
|
||||
|
||||
Cygwin: C<libgif-devel>
|
||||
|
||||
=head2 JPEG - C<libjpeg>
|
||||
|
||||
L<Imager::File::JPEG> uses L<< C<libjpeg> |http://www.ijg.org/ >> for JPEG
|
||||
image file support.
|
||||
|
||||
You may also use
|
||||
L<< C<libjpeg-turbo> |http://sourceforge.net/projects/libjpeg-turbo/ >>.
|
||||
|
||||
To install older releases of C<libjpeg> from source, you'll need to
|
||||
run:
|
||||
|
||||
make install-lib
|
||||
|
||||
to install the libraries. C<make install> only installs the program
|
||||
binaries.
|
||||
|
||||
Redhat package: C<libjpeg-devel>
|
||||
|
||||
Debian package: C<libjpeg-dev>
|
||||
|
||||
Cygwin: C<libjpeg-devel>
|
||||
|
||||
=head2 Freetype 2.x - C<libfreetype>
|
||||
|
||||
L<Imager::Font::FT2> uses L<< Freetype 2
|
||||
(C<libfreetype>)|http://www.freetype.org/ >> for font support, supporting
|
||||
too many font formats to mention here.
|
||||
|
||||
This is the recommended library to use for font support.
|
||||
|
||||
Debian package: C<libfreetype6-dev>
|
||||
|
||||
Redhat package: C<freetype-devel>
|
||||
|
||||
Cygwin: C<libfreetype-devel>
|
||||
|
||||
=head2 Win32 GDI fonts
|
||||
|
||||
L<Imager::Font::W32> uses L<Win32
|
||||
GDI|http://msdn.microsoft.com/en-us/library/dd145203%28v=vs.85%29.aspx>
|
||||
to render text using installed Windows fonts.
|
||||
|
||||
This requires Win32 SDK headers and libraries, and is only expected to
|
||||
work on native Win32 or Cygwin.
|
||||
|
||||
For this to work under Cygwin, install the C<w32api-headers> and
|
||||
C<w32api-runtime> packages.
|
||||
|
||||
=head2 C<t1lib>
|
||||
|
||||
L<Imager::Font::T1> uses L<< C<t1lib> |http://www.t1lib.org/ >> for
|
||||
font support, supporting Postscript Type 1 fonts only.
|
||||
|
||||
=for stopwords
|
||||
abandonware
|
||||
|
||||
T1Lib is abandonware, the latest released version has several bugs
|
||||
that reliably crash on 64-bit systems.
|
||||
|
||||
Expect C<Imager::Font::T1> to be unbundled from the Imager
|
||||
distribution at some point.
|
||||
|
||||
Debian package: C<libt1-dev>
|
||||
|
||||
Redhat package: C<t1lib-devel>
|
||||
|
||||
=head2 Freetype 1.x - C<libttf>
|
||||
|
||||
Imager uses L<< Freetype 1 (C<libttf>)|http://www.freetype.org/ >> if
|
||||
available for font support, supporting TTF fonts only.
|
||||
|
||||
Freetype 1.x is essentially unsupported and shouldn't be used for new
|
||||
code.
|
||||
|
||||
Expect Freetype 1 support to be removed from Imager at some point.
|
||||
|
||||
=head1 PLATFORM SPECIFICS
|
||||
|
||||
=head2 Linux
|
||||
|
||||
Several distributions include an Imager package, but they are
|
||||
typically several releases behind due to the nature of release cycles.
|
||||
|
||||
Imager typically supports the external libraries as packaged with any
|
||||
supported release of Linux.
|
||||
|
||||
=head3 Debian
|
||||
|
||||
To install the libraries used by Imager under Debian (or Ubuntu), run
|
||||
as root (or with sudo):
|
||||
|
||||
apt-get install libgif-dev libjpeg8-dev libtiff4-dev libpng12-dev libfreetype6-dev
|
||||
|
||||
You may also need to install development tools:
|
||||
|
||||
apt-get install build-essential
|
||||
|
||||
=head3 Redhat
|
||||
|
||||
To install the libraries used by Imager under Redhat and related Linux
|
||||
distributions, run as root (or sudo):
|
||||
|
||||
yum install giflib-devel libjpeg-devel libtiff-devel libpng-devel freetype-devel
|
||||
|
||||
To install the development tools needed:
|
||||
|
||||
yum install gcc
|
||||
|
||||
(which appears to be enough on a base Redhat-like install) or the more
|
||||
commonly recommended recipe:
|
||||
|
||||
yum groupinstall "Development Tools"
|
||||
|
||||
which is massive overkill.
|
||||
|
||||
=head2 Mac OS X
|
||||
|
||||
=head3 Building libraries
|
||||
|
||||
The default perl build in Snow Leopard and Lion is a fat binary, and
|
||||
default builds of C<giflib>, C<libpng> and C<libjpeg> (and maybe other
|
||||
libraries) will produce link failures.
|
||||
|
||||
To avoid this you need to supply a C<CFLAGS> parameter to the
|
||||
library's configure script, but since the C<-arch> flag conflicts with
|
||||
the options used to build the dependency files, you need to supply
|
||||
another flag to disable dependency tracking.
|
||||
|
||||
Snow Leopard fat binaries include C<i386>, C<x86_64> and C<PPC>
|
||||
objects, hence you would run configure like:
|
||||
|
||||
./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'
|
||||
|
||||
Lion doesn't support C<PPC>, so there you run configure like:
|
||||
|
||||
./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'
|
||||
|
||||
For C<libgif> you might also want to supply the C<--without-x> option:
|
||||
|
||||
./configure --disable-dependency-tracking --without-x CFLAGS='-arch x86_64 -arch i386'
|
||||
|
||||
If you copy library files into place manually, you may need to run
|
||||
C<ranlib> on them in their new location:
|
||||
|
||||
ranlib /usr/local/lib/libgif.a
|
||||
|
||||
=head3 Macintosh C<dfont> and suitcase font support
|
||||
|
||||
Through Freetype 2.1, Imager can use Macintosh C<DFON> (C<.dfont>)
|
||||
fonts and suitcase font files.
|
||||
|
||||
If you want to be able to use more than just the first face in the
|
||||
font file though, you will need to configure C<freetype2> with the
|
||||
--with-old-mac-fonts option:
|
||||
|
||||
./configure --with-old-mac-fonts
|
||||
|
||||
You can use the index option to get to the other font faces in the
|
||||
file:
|
||||
|
||||
# get the second face from $file
|
||||
my $font = Imager::Font->new(file=>$file, index=>1)
|
||||
or die Imager->errstr;
|
||||
|
||||
If you're using a suitcase font, you will also need to force the use
|
||||
of Freetype 2 with the type argument:
|
||||
|
||||
my $font = Imager::Font->new(file=>$suitcase, type=>'ft2', index=>$index)
|
||||
or die Imager->errstr;
|
||||
|
||||
=head2 Microsoft Windows
|
||||
|
||||
The simplest way to install the libraries used by Imager is to install
|
||||
L<Strawberry perl|http://strawberryperl.com/>.
|
||||
|
||||
You can then use either the bundled Imager, or install from CPAN.
|
||||
|
||||
If you get errors from your make tool, make sure you're using the same
|
||||
make that was used to build your perl - C<nmake> for Visual C/C++ and
|
||||
C<dmake> for MinGW, run:
|
||||
|
||||
perl -V:make
|
||||
|
||||
to see which make was used to build your perl.
|
||||
|
||||
=head2 Cygwin
|
||||
|
||||
To build Imager with as much library support as possible on Cygwin,
|
||||
install the following packages:
|
||||
|
||||
libjpeg-devel libpng-devel libgif-devel libtiff-devel
|
||||
libfreetype-devel t1lib-devel w32api-headers w32api-runtime
|
||||
|
||||
If you see an error under cygwin during testing along the lines of:
|
||||
|
||||
C:\cygwin\bin\perl.exe: *** unable to remap C:\cygwin\...some dll to the
|
||||
same address as parent (0x...) != 0x....
|
||||
|
||||
you will need to install the cygwin C<rebase> package and run:
|
||||
|
||||
$ rebaseall -v
|
||||
|
||||
or possibly, just:
|
||||
|
||||
$ perlrebase
|
||||
|
||||
will fix the problem. 64-bit Cygwin significantly reduces occurrences
|
||||
of this problem.
|
||||
|
||||
=head1 Other issues
|
||||
|
||||
=head2 Freetype 1.x vs Freetype 2.x
|
||||
|
||||
Freetype 1.x is no longer recommended, is no longer supported
|
||||
upstream, and receives only limited updates in Imager.
|
||||
|
||||
These two libraries have some conflicting include file names, but as
|
||||
long as you don't put the Freetype 2.x F<freetype.h> directory in the
|
||||
include path it should all work.
|
||||
|
||||
Put the directory containing F<ft2build.h> in the include path, but
|
||||
not the directory containing the freetype 2.x F<freetype.h>.
|
||||
|
||||
If you see compilation errors from font.c you've probably made the
|
||||
mistake of putting the Freetype 2.x F<freetype.h> directory into the
|
||||
include path.
|
||||
|
||||
To see which directories should be in the include path, try:
|
||||
|
||||
freetype-config --cflags
|
||||
|
||||
Ideally, C<freetype-config> should be in the PATH when building Imager
|
||||
with freetype 2.x support, in which case L<Imager::Font::FT2> can
|
||||
configure itself.
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson
|
||||
|
||||
=cut
|
||||
Reference in New Issue
Block a user