X-Git-Url: http://git.imager.perl.org/imager.git/blobdiff_plain/66b6db8764f59dc67ab7da8661264c672aa6b7fb..0a095db91e6e06223eb2f060243f515a64b12eb9:/README diff --git a/README b/README index aa911d13..edfe4d00 100644 --- a/README +++ b/README @@ -1,6 +1,6 @@ ================================================================ Copyright (c) 1999-2004 Arnar M. Hrafnkelsson. All rights reserved. -Copyright (c) 2004-2012 Anthony Cook. +Copyright (c) 2004-2013 Anthony Cook. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. @@ -30,381 +30,24 @@ LICENSE(S) TO USE SUCH LIBRARIES SHOULD YOU NEED ANY. 2. Compiling and testing ======================== -Some care has been taken to make the installation as smooth as -possible. This is rather hard due to the difference between operating -systems and site setups. To get started just type +For details on the this process, including library and platform +specific details, see Imager::Install, either by using: -$ perl Makefile.PL + perldoc lib/Imager/Install.pod -It should blurb out a list of which libraries were found and which -not. If you add a library to the machine after installing Imager it -does not automatically become available in Imager. It only uses the -libraries that are found. If the list of found libraries is not what -you expected, then the Makefile.PL is either not searching in the -right directories or your box does not have the libraries you think it -does. For a list of where to get the libraries have a look at -3. External dependencies. To widen the search path for libraries and -include files set the IM_INCPATH and IM_LIBPATH variables. The -environment variables that matter when Makefile.PL is run are +or at: -IM_INCPATH colon separated list of paths to extra include files -IM_LIBPATH colon separated list of paths to extra library files + http://imager.perl.org/docs/Imager/Install.html -IM_VERBOSE turns on verbose mode for the library scanning and such -IM_MANUAL to manually select which libraries are used and which not -IM_NOLOG if true logging will not be compiled into the module -IM_DEBUG_MALLOC if true malloc debugging will be compiled into the module - do not use IM_DEBUG_MALLOC in production - this slows - everything down +The basic installation process is similar to most other CPAN modules: -IM_CFLAGS Extra flags to pass to the compiler -IM_LFLAGS Extra flags to pass to the linker -IM_DFLAGS Extra flags to pass to the preprocessor + perl Makefile.PL + make + make test + make install - - -When finding the libraries has been sorted out it's time for - -$ make - -and if that works then do - -$ make test - -If either fails do take a peek at the file errep.perl. It's creates a -file report.txt. This is some information which will help me discover -where the problem is so I can try to fix it in future releases. If -you find running it ok (just remember - no warranty!) please send the -report.txt via email to tonyc@cpan.org. - -Troubleshooting tips: - -A common problem is that libgif/libungif are sometimes linked to the X -libraries and then running the tests fails. In that case something -like: - -$ IM_LFLAGS="-L/usr/X11R6/lib -lX11" perl Makefile.PL - -Which simply sets the environment variables for the extra libraries -to include the X libraries (which we do not use at all, but must -included since libgif has been linked with it). - -Otherwise you could just build giflib without any X11 dependencies: - - # must be a clean tree - cd giflib-4.1.4 - ./configure --without-x ... - -Also note that libgif has a few bugs: You can run something like - -$ perl -Iblib/lib -Iblib/arch t/t105gif.t - -This way you can see what comments the test script prints out. -t/t105gif.t checks for an bug in libgif and prints out a patch -if that bug is present, note that this bug only affects the more -"advanced" features of libgif. - -If for some reason you have libungif-devel package installed but -not libungif on RedHat then you will probably get lots of errors -like undefined symbol: FreeSavedImages when running make test. -Install libungif package to fix it. - -Stock libungif 4.1.4 or later seems to fix all of the bugs, if you -have a problem that version of linungif (or later), let us know and -we'll look into it. - -Imager needs to have a libtiff version of at least 3.5.5, but you -should use a later version since some noticable bugs have been fixed. - -For now you can either configure Imager manually (by setting the -IM_MANUAL environment variable to 1, in sh: - -$ IM_MANUAL=1 perl Makefile.PL - -and simply say no to tiff support when asked if you want it, the same thing -can be used to circumvent problems in gifs to get Imager going. - -If it worked just continue with the installation as normally -(with make install). - -Freetype 1.x vs Freetype 2.x ----------------------------- - -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. - - -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; - - -======================== -3. External dependencies -======================== - -Some hints about getting the Imager module to find the libraries it -needs for specific features. - -Most Linux distributions pre-package these. For each library I've -listed the Debian and Redhat package names. - -For Debian or Debian based system, such as Ubuntu, you would run: - - aptitude install package-name - -or: - - apt-get install package-name - -at a root shell (or via sudo). - -eg. - - apt-get install libjpeg62-dev - -For a Redhat based system such as CentOS or Fedora you would run: - - yum install package-name - -at a root shell. - -eg. - - yum install libjpeg-devel - -I strongly recommend using your distribution's packages if possible, -this will mean any security updates to those packages will be applied -when you install security updates. - -3.1 libjpeg ------------ - - http://www.ijg.org/files/ - ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz - -Provides read and write access to JPEG images. - -Make sure you run: - - make install-lib - -to install the development headers and libraries before attempting to -build Imager. - -Debian: libjpeg62-dev -Redhat: libjpeg-devel - -3.2 libpng ----------- - - http://www.libpng.org/pub/png/libpng.html - -Provides read and write access to PNG images. - -You also need zlib to use png: http://www.gzip.org/zlib/ We have -encountered problems with libpng 1.0.1, which were fixed in 1.0.5 -Note: you should probably be using zlib 1.1.4, since 1.1.3 has a -potential security problem. - -Debian: libpng12-dev -Redhat: libpng-devel - -3.3 giflib ----------- - - http://sourceforge.net/projects/giflib/ - -Provides read and write access to GIF images. - -giflib/libungif has come a long way since the buggy versions available -when Imager's gif support code was written. Preferably you should get -at least version 4.1.4. If you have a recent Linux distribution you -should be safe with whatever giflib it provides, but if you're -building from source, please try to use the latest version. - -With the expiration of the LZW patent there's no reason to use -libungif. - -libgif 4.1.4 has no problems known to me at this point. - -Debian: libgif-dev -Redhat: giflib-devel - -3.4 libtiff ------------ - - http://www.remotesensing.org/libtiff/ - -Provides read and write access to TIFF images. - -Note: libtiff 3.9.0 shouldn't be used due to a bug in -TIFFWriteDirectory(). - -Debian: libtiff4-dev -Redhat: libtiff-devel - -3.5 T1Lib ---------- - - http://www.t1lib.org/ - ftp://sunsite.unc.edu/pub/Linux/libs/graphics/ - -Support for text drawing with Type 1 Postscript fonts. - -Debian: libt1-dev -Redhat: t1lib-devel - -3.6 Freetype 2.x (libfreetype) ------------------------------- - - http://www.freetype.org/ - -Support for text drawing with a large number of font formats, -including Truetype, Type 1, Opentype and some bitmap formats. - -Debian: libfreetype6-dev -Redhat: freetype-devel - -3.7 Freetype 1.x (libttf) -------------------------- - - http://www.freetype.org/ - -Support for text drawing with Truetype fonts. - -This library has been superceded by Freetype 2, and some Linux -distributions are phasing it out. - -Debian: libttf-dev -Redhat: freetype1-devel - -3.8 Binaries ------------- - -Precompiled versions of some of the libraries might be found at: - -AIX: - - http://www.bullfreeware.com/ - -Solaris: - - http://www.sunfreeware.com/ - -======================== -4. Logging and debugging -======================== - -Logging is compiled in by default - if you should want to get of it -from the binaries you can do so by setting the env IMAGER_NOLOG -to something. If you want to enable malloc debugging to check for leaks -then set IMAGER_DEBUG_MALLOC to something. Needless to say it is -pretty pointless to have malloc debug enabled with no logging since you -can never see the malloc information that way. - - -================= -5. Win32 Support -================= - -Imager can be installed on Win32 systems. This was ported and tested -with Microsoft Visual C++ 6.0 with build 623 of ActivePerl. You can -use all of the features of Imager. You can also use Win32 GDI fonts -directly by supplying the 'face' parameter to Imager::Font->new(...). - -I've tested with MSVC++ 6.0, cygwin (perl 5.6.1) and gcc (MinGW). - -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 - -If you get errors from your make tool, make sure you're using the same -make that was used to build your perl - generally GNU make for cygwin, -nmake for Visual C/C++ and dmake for MinGW. - -Imager and all of the libraries it requires are supplied with -Strawberry Perl. - -============ -6. Mac OS X -============ - -Building Imager under OS X is generally straightforward. There are -some exceptions though: - -a) you may find to need to ranlib library files in place after you've - installed them, for example: - - ranlib /usr/local/lib/libgif.a - -b) the version of GCC enabled by default on OS X 10.4 generates - incorrect code for some functions. To work around this run: - - gcc_select 3 - - before building Imager and: - - gcc_select 4 - - after building Imager. - - This problem exhibits itself as test failures in t/t20fill.t - - Imager 0.56 includes a workaround for this problem, but I wasn't - able to test it. - -c) if you want to build GCC 4.0 from scratch and use that you will - need to adjust the command-line supplied during the link stage, so - that there is some other option before the -bundle option. - - For example: - - perl Makefile.PL LDDLFLAGS="`perl -MConfig -e 'print "-g $Config{lddlflags}"'`" - ======================= -7. General information +3. General information ======================= The Imager module homepage is currently at: @@ -416,7 +59,7 @@ You can report bugs by pointing your browser at: https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager ======================== -8. Thanks +4. Thanks ======================== Thanks go to: