/ 
Imager-1.024_006
River stage three • 111 direct dependents • 127 total dependents
/ Imager::Install

NAME

Imager::Install - installation notes for Imager

SYNOPSIS

perl Makefile.PL
make
make test
make install

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 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 --verbose or -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 report.txt in your report at:

https://github.com/tonycoz/imager/issues

There are other options used to configure how Imager is built:

--nolog

build Imager without logging support. This will speed up Imager a little. You can also remove logging by setting the IMAGER_NOLOG environment variable to a true value.

--coverage

used to build Imager for gcov coverage testing. This is intended for development and also requires options supplied to make.

--assert

build Imager with assertions enabled.

--tracecontext

build Imager to trace context object management to stderr for debugging.

--enable=feature,feature ...
--disable=feature,feature ...

Enable or disable attempting to build bundled modules. This only has an effect on modules are also available on CPAN that are bundled with Imager for historical reasons.

You can use --enable=none to prevent attempting to install any of the bundled modules.

You can use either of --enable or --disable but not both.

--Accflags=flags =item --Aldflags=flags =item --Alddlflags=flags =item --Aoptimize=flags

Provide extra compile and link-time flags without having to extract the originals from %Config. These are overridden by the flags parsed by ExtUtils::MakeMaker from the command-line, eg.

perl Makefile.PL --Aoptimize=-march=native OPTIMIZE=-O2

will be rejected by Makefile.PL.

Build time environment variables

  • IM_ENABLE - if set, a comma separated list of bundled modules to try to build. This can be set to none to build none of them. There is no environment variable corresponding to --disable.

  • IMAGER_NOLOG - build Imager with logging disabled.

  • IMAGER_DEBUG_MALLOC - build Imager with it's debug malloc wrappers. This is not compatible with threaded code.

  • IM_INCPATH - equivalent to --incpath.

  • IM_LIBPATH - equivalent to --libpath.

  • IM_VERBOSE - equivalent to --verbose

  • IM_CFLAGS - extra C compiler flags.

  • IM_LFLAGS - extra linker flags.

  • IM_DFLAGS - extra preprocessor flags.

OTHER PROBES

16-bit floating point

Used only when requesting the data for an image, this is best supported on ARM CPUs, but sufficiently recent x86_64 can also support it if enabled with a compiler option.

I needed to add -march=skylake to ccflags to successfully probe for 16-bit floats on my Intel i7-10700F.

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.

PNG - libpng

Imager::File::PNG uses libpng for PNG image file support.

Debian package: libpng-dev

Redhat package: libpng-devel

Cygwin: libpng-devel

TIFF - libtiff

Imager::File::TIFF uses 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: libtiff4-dev

Redhat package: libtiff-devel

Cygwin: libtiff-devel

GIF - libgif

Imager::File::GIF uses libgif for GIF image file support.

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.

giflib 3 is no longer supported.

libungif is no longer supported as an alternative.

Debian package: libgif-dev

Redhat package: giflib-devel

Cygwin: libgif-devel

JPEG - libjpeg

Imager::File::JPEG uses libjpeg for JPEG image file support.

You may also use libjpeg-turbo or mozjpeg by setting the installed library's pkgconfig/ directory in `PKG_CONFIG_PATH`, eg:

PKG_CONFIG_PATH=/home/tony/local/mozjpeg-3.0git/lib/pkgconfig/ perl Makefile.PL
PKG_CONFIG_PATH=/home/tony/local/jpeg-turbo-2.0.4git/lib/pkgconfig/ perl Makefile.PL

To install older releases of libjpeg from source, you'll need to run:

make install-lib

to install the libraries. make install only installs the program binaries.

Redhat package: libjpeg-devel

Debian package: libjpeg-dev

Cygwin: libjpeg-devel

Freetype 2.x - libfreetype

Imager::Font::FT2 uses Freetype 2 (libfreetype) for font support, supporting too many font formats to mention here.

This is the recommended library to use for font support.

Debian package: libfreetype6-dev

Redhat package: freetype-devel

Cygwin: libfreetype-devel

Win32 GDI fonts

Imager::Font::W32 uses Win32 GDI 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 w32api-headers and w32api-runtime packages.

t1lib

Imager::Font::T1 uses t1lib for font support, supporting Postscript Type 1 fonts only.

T1Lib is abandonware, the latest released version has several bugs that reliably crash on 64-bit systems.

Expect Imager::Font::T1 to be unbundled from the Imager distribution at some point.

Debian package: libt1-dev

Redhat package: t1lib-devel

Freetype 1.x - libttf

Imager uses Freetype 1 (libttf) 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.

PLATFORM SPECIFICS

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.

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

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.

Mac OS X

Building libraries

The default perl build in Snow Leopard and Lion is a fat binary, and default builds of giflib, libpng and libjpeg (and maybe other libraries) will produce link failures.

To avoid this you need to supply a CFLAGS parameter to the library's configure script, but since the -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 i386, x86_64 and PPC objects, hence you would run configure like:

./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386 -arch ppc'

Lion doesn't support PPC, so there you run configure like:

./configure --disable-dependency-tracking CFLAGS='-arch x86_64 -arch i386'

For libgif you might also want to supply the --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 ranlib on them in their new location:

ranlib /usr/local/lib/libgif.a

Macintosh dfont and suitcase font support

Through Freetype 2.1, Imager can use Macintosh DFON (.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 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;

Microsoft Windows

The simplest way to install the libraries used by Imager is to install Strawberry perl.

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 - nmake for Visual C/C++ and dmake for MinGW, run:

perl -V:make

to see which make was used to build your perl.

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 rebase package and run:

$ rebaseall -v

or possibly, just:

$ perlrebase

will fix the problem. 64-bit Cygwin significantly reduces occurrences of this problem.

Other issues

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 freetype.h directory in the include path it should all work.

Put the directory containing ft2build.h in the include path, but not the directory containing the freetype 2.x freetype.h.

If you see compilation errors from font.c you've probably made the mistake of putting the Freetype 2.x freetype.h directory into the include path.

To see which directories should be in the include path, try:

freetype-config --cflags

Ideally, freetype-config should be in the PATH when building Imager with freetype 2.x support, in which case Imager::Font::FT2 can configure itself.

OPTIMIZED BUILDS

Your typical system perl is built with fairly generic options to allow it to run on any supported system, if you don't want to build a new system perl, you can provide options to Imager's Makefile.PL to provide a more optimized build of Imager. This likely won't make much difference yet, but the optimization support options are there now.

If you have fairly homogeneous hardware across the board, you can supply a higher tier -march option to use the features of more modern processors:

perl Makefile.PL OPTIMIZE=-O2\ -g\ -march=skylake

You can avoid supplying the original options using --Aoptimize:

perl Makefile.PL --Aoptimize=-march=skylake

If you have a more recent (or just better) compiler available you can specify that using the normal ExtUtils::MakeMaker mechanism:

perl Makefile.PL CC=/opt/gcc-12.0.1/bin/gcc

With gcc or clang you can request link time optimization (LTO):

perl Makefile.PL --Aoptimize=-flto --Alddlflags=-flto

Note that if you change compilers for LTO you will need to specify the equivalent linker:

perl Makefile.PL --Aoptimize=-flto --Alddlflags=-flto CC=clang-14 LD=clang-14

AUTHOR

Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson