GraphicsMagick for Debian
=========================

GraphicsMagick is a fork of the well-know ImageMagick project for image
processing. It was originally based on ImageMagick version 5.5.2, but
improvements have since been exchanged back and forth between both projects.
Still, incompatibilities have accumulated over the years, but their scope and
visibility depends on whether you're an end user of the command line tools,
or a developer requiring one of the library interfaces.

GraphicsMagick and ImageMagick mainly differ in their development process.
ImageMagick focuses on new features and rapid development cycles,
GraphicsMagick puts emphasis on stability and correctness. Therefore, I
recommend to try with GraphicsMagick first, and stick with it if you find it
suits all your needs. Have a go at ImageMagick if you require a special feature
or improvement, but be prepared to deal with potential breakage between
different versions. From my experience, this is especially true for the C/C++
libraries that frequently broke binary compatibility between releases.
GraphicsMagick libraries should not suffer from this problem. GraphicsMagick
and ImageMagick packages can be installed and used in parallel. On the command
line, you're probably already used to ImageMagick names like 'convert' or
'mogrify'. The GraphicsMagick counterparts are called from a single command
'gm' with the desired action as its first option, eg. 'gm convert' or 'gm
mogrify'. Other than that, options and arguments should be roughly identical
between ImageMagick and GraphicsMagick, apart from new features that
GraphicsMagick doesn't support yet. If you want to switch from ImageMagick to
GraphicsMagick but don't want to teach the 'gm' prefix to all your shell
scripts (or your fingers that are used to just typing 'convert'), you should
install Debian package graphicsmagick-imagemagick-compat. This will give
you the new implementation using the old names, but you'll lose the
ability to co-install both GraphicsMagick and ImageMagick.

The second wrapper package, graphicsmagick-libmagick-dev-compat, should
probably not be installed permanently. It adds compatibility wrappers for the
C, C++, and Perl bindings, and its usefulness will differ from package to
package. Therefore, it will be typically used for testing on a developer's
system, or in a Build-Depends line of a Debian package, but rarely as a
long-term, system-wide default. Basically, if a package can be made to
work with GraphicsMagick only using this wrapper, it tells you that
switching is a no-brainer. Otherwise, more porting work needs to be done.
In the simple cases:
- Perl scripts only need to replace Image::Magick with Graphics::Magick.
- C applications need to add /usr/include/GraphicsMagick to their include
  path and link with -lGraphicsMagick and -lGraphicsMagickWand rather than
  -lMagick and -lWand. This is most conveniently done through the
  pkg-config packages named GraphicsMagick and GraphicsMagickWand. There are
  also custom config scripts GraphicsMagick-config and
  GraphicsMagickWand-config parallel to Magick-config, but those are
  deprecated in favour of pkg-config.
- C++ applications also need to add /usr/include/GraphicsMagick to their
  include path. On the link line, -lMagick++ has to be replaced with
  -lGraphicsMagick++. This can be automated with pkg-config package
  GraphicsMagick++ or the deprecated GraphicsMagick++-config script.

If you maintain a Debian package that depends on libmagick++, libmagick, or
perlmagick, I urge you to investigate whether switching to the GraphicsMagick
libraries is possible. This is because binary incompatibilties between
different versions of libmagick have been a constant source of trouble in the
past. In contrast, the GraphicsMagick development process seems to be more
suitable for Debian's needs.

 -- Daniel Kobras <kobras@debian.org>  Thu,  5 Jan 2006 20:48:16 +0100
