Commit 7f3bf119c for imagemagick.org
commit 7f3bf119c05dd14791e85b731527f48c0341045b
Author: Cristy <urban-warrior@imagemagick.org>
Date: Wed Nov 18 17:50:07 2026 -0500
improve clarity of PerlMagick documentation
diff --git a/PerlMagick/README.txt b/PerlMagick/README.txt
index 0260869f3..64b696280 100644
--- a/PerlMagick/README.txt
+++ b/PerlMagick/README.txt
@@ -1,141 +1,205 @@
-Introduction
+PerlMagick
+==========
- PerlMagick, is an objected-oriented Perl interface to ImageMagick.
- Use the module to read, manipulate, or write an image or image sequence
- from within a Perl script. This makes it suitable for Web CGI scripts. You
- must have ImageMagick 7.0.0 or above installed on your system for this
- module to work properly.
+INTRODUCTION
+------------
- See
+PerlMagick is an object-oriented Perl interface to ImageMagick. Use it to
+read, manipulate, or write an image or image sequence from within a Perl
+script. This makes it well suited to web CGI scripts as well as batch and
+command-line tools.
- https://imagemagick.org/perl-magick/
+Requirements:
- for additional information about PerlMagick. If you have problems, go to
+ * ImageMagick 7.0.0 or above, installed on your system.
+ * A working Perl installation with a C compiler and the standard build
+ tools (make, ExtUtils::MakeMaker) if you are building from source.
+ * Development files (headers and libraries) for ImageMagick.
- https://github.com/ImageMagick/ImageMagick/discussions
+Resources:
- for help. For instructions about installing ImageMagick, see
+ * PerlMagick documentation: https://imagemagick.org/perl-magick/
+ * Help and discussion: https://github.com/ImageMagick/ImageMagick/discussions
+ * ImageMagick installation: https://imagemagick.org/
- https://imagemagick.org/
+INSTALLATION (UNIX, LINUX, macOS)
+---------------------------------
-Installation
+1. Unpack the ImageMagick distribution (adjust the file name to match the
+ version you downloaded):
- Get the PerlMagick distribution and type the following:
+ gunzip ImageMagick-7.1.2-0.tar.gz
+ tar xvf ImageMagick-7.1.2-0.tar
- gunzip ImageMagick-7.1.2-0.tar.gz
- tar xvf ImageMagick-7.1.2
+2. Build and install ImageMagick itself by following the instructions in
+ INSTALL-unix.txt.
- Follow the ImageMagick installation instructions in INSTALL-unix.txt
- then type
+3. Change to the PerlMagick directory:
- cd PerlMagick
+ cd PerlMagick
- Next, edit Makefile.PL and change LIBS and INC to include the appropriate
- path information to the required libMagick library. You will also need
- library search paths (-L) to JPEG, PNG, TIFF, etc. libraries if they were
- included with your installed version of ImageMagick. If an extension
- library is built as a shared library but not installed in the system's
- default library search path, you may need to add run-path information
- (often -R or -rpath) corresponding to the equivalent library search
- path option so that the library can be located at run-time.
+4. Edit Makefile.PL and set LIBS and INC so they point to the libMagick
+ library and headers. You will also need library search paths (-L) for the
+ JPEG, PNG, TIFF, and other libraries if they were included with your
+ installed version of ImageMagick.
- To create and install the dynamically-loaded version of PerlMagick
- (the preferred way), execute
-
- perl Makefile.PL
- make
- make install
+ If an extension library is built as a shared library but is not installed
+ in the system's default library search path, you may also need to add
+ run-path information (often -R or -rpath) that matches the library search
+ path, so the library can be located at run time.
- To create and install a new 'perl' executable (replacing your existing
- PERL interpreter!) with PerlMagick statically linked (but other libraries
- linked statically or dynamically according to system linker default),
- execute
+5. Build and install the dynamically loaded version of PerlMagick (the
+ preferred method):
- perl Makefile.PL
- make perl
- make -f Makefile.aperl inst_perl
-
- or to create and install a new PERL interpreter with a different name
- than 'perl' (e.g. 'PerlMagick') and with PerlMagick statically linked
+ perl Makefile.PL
+ make
+ make install
- perl Makefile.PL MAP_TARGET=PerlMagick
- make PerlMagick
- make -f Makefile.aperl inst_perl
+ On Unix you typically need root privileges for "make install". There are
+ ways around this, such as installing into a local directory (for example,
+ perl Makefile.PL PREFIX=$HOME/perl). Consult the Perl manual pages for
+ details.
- See the ExtUtils::MakeMaker(3) manual page for more information on
- building PERL extensions (like PerlMagick).
+You are now ready to use PerlMagick in your Perl scripts.
- For Windows systems, type
- perl Makefile.nt
- nmake install
+STATICALLY LINKED BUILDS (OPTIONAL)
+-----------------------------------
- For Unix, you typically need to be root to install the software.
- There are ways around this. Consult the Perl manual pages for more
- information. You are now ready to utilize the PerlMagick routines from
- within your Perl scripts.
+Most users should use the dynamically loaded build above. If you need
+PerlMagick linked statically into a Perl executable, you have two options.
-Installation - Win32 Strawberry perl
+Replace your existing "perl" executable (use with caution: this overwrites
+your current Perl interpreter):
- On Win32 Strawberry perl the prefered way of installing PerlMagick is the
- following:
+ perl Makefile.PL
+ make perl
+ make -f Makefile.aperl inst_perl
- 1) Download and install ImageMagick Windows binaries from
- https://imagemagick.org/download/#windows
+Or create a new interpreter with a different name (for example, "PerlMagick"),
+leaving your existing Perl untouched:
- 2) You HAVE TO choose dynamic (DLL) ImageMagick binaries. Note: it is not
- possible to mix 32/64bit binaries of perl and ImageMagick
+ perl Makefile.PL MAP_TARGET=PerlMagick
+ make PerlMagick
+ make -f Makefile.aperl inst_perl
- 3) During installation select that you want to install ImageMagick's
- development files (libraries+headers)
+In both cases PerlMagick is linked statically, while other libraries are
+linked statically or dynamically according to your system linker's defaults.
+See the ExtUtils::MakeMaker(3) manual page for more information on building
+Perl extensions such as PerlMagick.
- 4) You also need to have ImageMagick's directory in your PATH. We are
- using the 'magick' tool to determine your actual configuration.
- 5) You might need Visual C++ Redistributable Package installed on your
- system. See instructions on ImageMagick's Binary Release webpage.
+INSTALLATION (WINDOWS)
+----------------------
- 6) If you have all prerequisites 1)...5) you can simply install
- ImageMagick by running: cpan -i Image::Magick
+With a standard Perl and Visual C++ toolchain:
+ perl Makefile.nt
+ nmake install
-Testing PerlMagick
+With Strawberry Perl (recommended on Windows):
- Before PerlMagick is installed, you may want to execute
-
- make test
+1. Download and install the ImageMagick Windows binaries from
+ https://imagemagick.org/download/#windows
- to verify that PERL can load the PerlMagick extension ok. Chances are
- some of the tests will fail if you do not have the proper delegates
- installed for formats like JPEG, TIFF, etc.
+2. Choose the dynamic (DLL) ImageMagick binaries. Note that you cannot mix
+ 32-bit and 64-bit builds: your Perl and ImageMagick must match.
- Use the 'prove' utility to execute a test from the build folder:
+3. During installation, select the option to install ImageMagick's
+ development files (libraries and headers).
- prove --blib blib -I `pwd` -bv ./t/read.t
+4. Make sure ImageMagick's directory is in your PATH. The "magick" tool is
+ used to determine your configuration.
- To see a number of PerlMagick demonstration scripts, type
-
- cd demo
- make
+5. You may need the Visual C++ Redistributable Package. See the instructions
+ on ImageMagick's binary release web page.
+6. Once steps 1 through 5 are complete, install PerlMagick by running:
-Example Perl Magick Script
+ cpan -i Image::Magick
- Here is an example script to get you started:
- #!/usr/bin/perl
- use Image::Magick;
+TESTING
+-------
- $q = Image::Magick->new;
- $x = $q->Read("model.gif", "logo.gif", "rose.gif");
- warn "$x" if $x;
+Before installing PerlMagick, you may want to run
- $x = $q->Crop(geom=>'100x100+100+100');
- warn "$x" if $x;
+ make test
- $x = $q->Write("x.gif");
- warn "$x" if $x;
+to verify that Perl can load the PerlMagick extension. Some tests may fail if
+you do not have the proper delegate libraries installed for formats such as
+JPEG, TIFF, and PNG. Such failures usually indicate missing format support,
+not a broken build.
- The script reads three images, crops them, and writes a single image
- as a GIF animation sequence.
+To run a single test from the build folder, use the "prove" utility:
+
+ prove --blib blib -I `pwd` -bv ./t/read.t
+
+After installation, you can confirm that the module loads and check its
+version with:
+
+ perl -MImage::Magick -e 'print "$Image::Magick::VERSION\n"'
+
+To see a number of PerlMagick demonstration scripts, run:
+
+ cd demo
+ make
+
+
+EXAMPLE SCRIPT
+--------------
+
+The following script reads three images, crops each of them, and writes the
+result as a single GIF animation sequence:
+
+ #!/usr/bin/perl
+ use strict;
+ use warnings;
+ use Image::Magick;
+
+ my $image = Image::Magick->new;
+
+ # Read three images into one image sequence.
+ my $status = $image->Read("model.gif", "logo.gif", "rose.gif");
+ warn "$status" if $status;
+
+ # Crop every image in the sequence to 100x100 pixels, starting at
+ # an offset of (100,100).
+ $status = $image->Crop(geometry => '100x100+100+100');
+ warn "$status" if $status;
+
+ # Write the sequence as a single animated GIF.
+ $status = $image->Write("x.gif");
+ warn "$status" if $status;
+
+Notes:
+
+ * PerlMagick methods return an empty value on success and an error
+ message on failure, which is why each call is checked and passed to
+ "warn".
+ * Methods operate on every image in the sequence, so the Crop call above
+ affects all three images.
+ * Writing a multi-image sequence to a format that supports animation (such
+ as GIF) produces one animated file. For formats that do not, each image
+ is typically written to its own file.
+
+
+TROUBLESHOOTING
+---------------
+
+ * "Can't locate Image/Magick.pm": PerlMagick is not installed, or it was
+ installed to a directory that is not in Perl's @INC path.
+ * Build errors about missing headers or libraries: check the LIBS and INC
+ settings in Makefile.PL, and confirm that the ImageMagick development
+ files are installed.
+ * "error while loading shared libraries": the ImageMagick (or delegate)
+ shared libraries are not in the system's library search path. Add
+ their location to the run-path settings described in Installation,
+ or to your system's library path configuration.
+ * Failures reading or writing certain formats: the required delegate
+ library (JPEG, PNG, TIFF, and so on) was not available when
+ ImageMagick was built.
+
+If problems persist, ask for help at
+https://github.com/ImageMagick/ImageMagick/discussions