VIPS 7.10 source, documentation and tools
=========================================

VIPS is an image processing library. It's good for large images and for
colour. This package includes:

	VIPS core library (iofuncs)
	Standard VIPS image processing operators
	C interface
	C++ interface
	Command line interface
	Tools (Postscript output filters, a few lame shell scripts)
	Documentation (as LaTeX source, Unix man pages, and formatted
	Postscript and HTML)

There are graphical user interfaces, pre-built binaries and pre-built
documentation archives available as separate downloads from the VIPS website:

	http://www.vips.ecs.soton.ac.uk

To install, unpack the VIPS distribution somewhere, and run the wrapper
script. For example:

	cd ~
	tar xfz vips-7.10.x.tar.gz
	./vips-7.10.x/bin/vips-7.10 im_invert fred.jpg jim.tif

You can run the binary directly (and gain some speed) if you add the VIPS
library area to your library path, the bin area to your executable path, and
(optionally) the man area to your man path. Setting VIPSHOME to the install
prefix will help too.

Building VIPS from source
=========================

In the VIPS directory, you should just be able to do:

	user% ./configure
	user% make

then as root: 

	root% make install

By default this will install files to /usr/local/bin, /usr/local/share/vips,
/usr/local/include, /usr/local/lib and /usr/local/man. 

If you have problems, read on.

Building VIPS on win32
----------------------

Probably the easiest route is to use mingw/msys. This provides a GNU-style
build environment for win32. You should be able to use the configure/make/make
install route above. With some (slight) extra work, you can make DLLs too.

	http://www.mingw.org/

you need many more libraries, see the dependencies section. Tor Lillqvist 
lists a lot of them here:

	http://www.gimp.org/~tml/gimp/win32/downloads.html

you can also download from the gnuwin32 project:

	http://gnuwin32.sourceforge.net/

you need perl ... I used the activestate one:

	http://www.activestate.com/

You need to tell pkg-config about /lib/pkgconfig

	export PKG_CONFIG_PATH=/lib/pkgconfig

then configure with

	CFLAGS="-mms-bitfields -Wall -O2" ./configure

Alternatively, vips-7.10.x/win32 contains sample build systems using the
Microsoft toolchain. See the README in there for details.

Dependencies
============

VIPS has to have glib-2.x. The build system needs perl, pkg-config and gnu
make.

Optional dependencies
---------------------

Optional support libraries ... also try ./configure --help to see flags for
controlling these libs. By default, if suitable versions are found, VIPS will
build support for them automatically.

VIPS looks for stuff in /usr. If you have installed you own versions of these
libraries to /usr/local, vips will not see them. Use switches to VIPS
configure like:

	./configure --prefix=/home/john/vips \
		--with-tiff-includes=/home/john/vips/include \
		--with-tiff-libraries=/home/john/vips/lib 

to get VIPS to see your builds.

libjpeg
	The IJG JPEG library. We use 6b, but 6a works too.

libtiff
	The TIFF library. It needs to be built with support for JPEG and
	ZIP compression. 3.4b037 and later are known to be OK. 
	You'll need libz for this too. We use 1.1.3, others should work. 

libz
	If your TIFF library includes ZIP compression, you'll need this too.

videodev.h
	If VIPS finds linux/videodev.h, you get support for Linux video 
	grabbing.

libfftw/libdfftw
	If VIPS finds this library, it uses it for fourier transforms.

 	If the library is not found, VIPS falls back to it's own internal FFT
	routines which are slower and less accurate.

liblcms
	If present, im_icc_import(), _export() and _transform() are available
	for transforming images with ICC profiles.

large files
	VIPS uses the standard autoconf tests to work out how to support large
	files (>2GB) on your system. Any reasonably recent *nix should be OK.

libpng
	if present, VIPS can load and save png files. Version 1.2+ preferred.

libMagick
	if available, VIPS adds support for loading all libMagick supported
	image file types (about 80 different formats). No saving though.

pango
freetype2
fontconfig
	if available, VIPS adds support for text rendering. You need the
	package pangoft2 in "pkg-config --list-all"

Configure hints for support libraries
-------------------------------------

Most sensible systems will include pre-built versions of all the above
libraries. On old *nix boxes (eg. SGI, Sun), you may have to build them
yourself. On windows, you can download pre-built binary versions of most of
these. On Mac OS X, I suggest you use fink to download and build these libs
for you.

Some problems I've had. Newer versions of these packages have probably fixed 
most of these.

Sun:
	Building libz
	-------------

	./configure --shared
	./configure 

	- you have to configure and build twice to get static and dynamic 
	  libraries

	Building libjpeg
	----------------

	CC='cc -erroff' ./configure --prefix=/usr/local --enable-shared \
		--enable-static

	- you have to disable warnings with erroff (Sun cc) or it does not 
	  detect shared libraries correctly

	Building libtiff
	----------------

	Get a recent one, 3.4b037 and later seem OK.

	./configure --with-CC=cc --with-JPEG=yes --with-ZIP=yes \
		--with-DIRS_LIBINC=/usr/local/include \
		--with-DIR_JPEGLIB=/usr/local/lib  \
		--with-DIR_GZLIB=/usr/local/lib

SGI:

	./configure --with-CC=cc --with-ENVOPTS="-KPIC -32" \
		--with-JPEG=yes --with-ZIP=yes --with-LIBGL=no \
		--with-DIR_JPEGLIB=/usr/lib --with-DIR_GZLIB=/usr/lib

	- the SGI-supplied libjpeg and libz are fine, their libtiff is not up 
	  to scratch, so you must build your own
	- you may have problems with nroff not being found, you can use awf
	  instead: just make a symlink to /bin/awf called nroff, and put it
	  somewhere on your path
	- PIC is not enabled correctly for SGI when building the shared
	  library, you have to turn -KPIC on by hand in ENVOPTS

Configuring VIPS
----------------

When it checks for support libraries, VIPS searches your system areas first.
If you have built your own versions (eg. you've made a new libtiff in
/usr/local/), you'll need to use switches to configure to point it to the
right place. For example:

	./configure \
		--with-tiff-includes=/usr/local/include \
		--with-tiff-libraries=/usr/local/lib 

If you're unlucky, you may need to fiddle with your LD_LIBRARY_PATH, 
SHLIB_PATH, or ld.so.conf to make sure you get the right library at run 
time too. 

Sun:
	CC=cc CXX=CC ./configure 

	- this is for a native build with the v5 Sun C compilers

SGI:
	CC=cc SGI_ABI=-32 CFLAGS="-O -32" ./configure 

	- for an old-API build ... sometimes useful for video stuff ...
	  remember, you'll need to build everything else -32 as well

MacOS X:
	CC="gcc -I/sw/include -L/sw/lib" CXX="g++ -I/sw/include -L/sw/lib" ./configure

Other useful configure lines:

	CFLAGS="-g -Wall" CXXFLAGS="-g -Wall" ./configure \
		--prefix=/home/john/vips --without-threads --with-dmalloc

	- debugging (-Wall is gcc only), and install to my home area for
	  testing ... no threads (they make debugging very confusing)

	CFLAGS="-O -DNDEBUG" ./configure 

	- full production build

	CFLAGS="-DIM_NO_VIPS7_COMPAT" ./configure 

	- only define sensible macro names ... by default VIPS #defines macros
	  called things like "right()", causing confusion on some platforms

on constable, build with

CFLAGS="-g -Wall" CXXFLAGS="-g -Wall" ./configure --prefix=/home/john/vips 

on win32 build with

CFLAGS="-Wall -O2" ./configure 

Disclaimer
----------

Disclaimer: No guarantees of performance accompany this software, nor is any
responsibility assumed on the part of the authors. Please read the licence
agreement.

