INSTALLATION INSTRUCTIONS for the Independent JPEG Group's JPEG software

Copyright (C) 1991-1998, Thomas G. Lane.

This file is part of the Independent JPEG Group's software.

For conditions of distribution and use, see the accompanying README file.

This file explains how to configure and install the IJG software.  We have

tried to make this software extremely portable and flexible, so that it can be

adapted to almost any environment.  The downside of this decision is that the

installation process is complicated.  We have provided shortcuts to simplify

the task on common systems.  But in any case, you will need at least a little

familiarity with C programming and program build procedures for your system.

If you are only using this software as part of a larger program, the larger

program's installation procedure may take care of configuring the IJG code.

For example, Ghostscript's installation script will configure the IJG code.

You don't need to read this file if you just want to compile Ghostscript.

If you are on a Unix machine, you may not need to read this file at all.

Try doing

	./configure

	make

	make test

If that doesn't complain, do

	make install

(better do "make -n install" first to see if the makefile will put the files

where you want them).  Read further if you run into snags or want to customize

the code for your system.

TABLE OF CONTENTS

-----------------

Before you start

Configuring the software:

	using the automatic "configure" script

	using one of the supplied jconfig and makefile files

	by hand

Building the software

Testing the software

Installing the software

Optional stuff

Optimization

Hints for specific systems

BEFORE YOU START

================

Before installing the software you must unpack the distributed source code.

Since you are reading this file, you have probably already succeeded in this

task.  However, there is a potential for error if you needed to convert the

files to the local standard text file format (for example, if you are on

MS-DOS you may have converted LF end-of-line to CR/LF).  You must apply

such conversion to all the files EXCEPT those whose names begin with "test".

The test files contain binary data; if you change them in any way then the

self-test will give bad results.

Please check the last section of this file to see if there are hints for the

specific machine or compiler you are using.

CONFIGURING THE SOFTWARE

========================

To configure the IJG code for your system, you need to create two files:

  * jconfig.h: contains values for system-dependent #define symbols.

  * Makefile: controls the compilation process.

(On a non-Unix machine, you may create "project files" or some other

substitute for a Makefile.  jconfig.h is needed in any environment.)

We provide three different ways to generate these files:

  * On a Unix system, you can just run the "configure" script.

  * We provide sample jconfig files and makefiles for popular machines;

    if your machine matches one of the samples, just copy the right sample

    files to jconfig.h and Makefile.

  * If all else fails, read the instructions below and make your own files.

Configuring the software using the automatic "configure" script

---------------------------------------------------------------

If you are on a Unix machine, you can just type

	./configure

and let the configure script construct appropriate configuration files.

If you're using "csh" on an old version of System V, you might need to type

	sh configure

instead to prevent csh from trying to execute configure itself.

Expect configure to run for a few minutes, particularly on slower machines;

it works by compiling a series of test programs.

Configure was created with GNU Autoconf and it follows the usual conventions

for GNU configure scripts.  It makes a few assumptions that you may want to

override.  You can do this by providing optional switches to configure:

* If you want to build libjpeg as a shared library, say

	./configure --enable-shared

To get both shared and static libraries, say

	./configure --enable-shared --enable-static

Note that these switches invoke GNU libtool to take care of system-dependent

shared library building methods.  If things don't work this way, please try

running configure without either switch; that should build a static library

without using libtool.  If that works, your problem is probably with libtool

not with the IJG code.  libtool is fairly new and doesn't support all flavors

of Unix yet.  (You might be able to find a newer version of libtool than the

one included with libjpeg; see ftp.gnu.org.  Report libtool problems to

bug-libtool@gnu.org.)

* Configure will use gcc (GNU C compiler) if it's available, otherwise cc.

To force a particular compiler to be selected, use the CC option, for example

	./configure CC='cc'

The same method can be used to include any unusual compiler switches.

For example, on HP-UX you probably want to say

	./configure CC='cc -Aa'

to get HP's compiler to run in ANSI mode.

* The default CFLAGS setting is "-O" for non-gcc compilers, "-O2" for gcc.

You can override this by saying, for example,

	./configure CFLAGS='-g'

if you want to compile with debugging support.

* Configure will set up the makefile so that "make install" will install files

into /usr/local/bin, /usr/local/man, etc.  You can specify an installation

prefix other than "/usr/local" by giving configure the option "--prefix=PATH".

* If you don't have a lot of swap space, you may need to enable the IJG

software's internal virtual memory mechanism.  To do this, give the option

"--enable-maxmem=N" where N is the default maxmemory limit in megabytes.

This is discussed in more detail under "Selecting a memory manager", below.

You probably don't need to worry about this on reasonably-sized Unix machines,

unless you plan to process very large images.

Configure has some other features that are useful if you are cross-compiling

or working in a network of multiple machine types; but if you need those

features, you probably already know how to use them.

Configuring the software using one of the supplied jconfig and makefile files

-----------------------------------------------------------------------------

If you have one of these systems, you can just use the provided configuration

files:

Makefile	jconfig file	System and/or compiler

makefile.manx	jconfig.manx	Amiga, Manx Aztec C

makefile.sas	jconfig.sas	Amiga, SAS C

makeproj.mac	jconfig.mac	Apple Macintosh, Metrowerks CodeWarrior

mak*jpeg.st	jconfig.st	Atari ST/STE/TT, Pure C or Turbo C

makefile.bcc	jconfig.bcc	MS-DOS or OS/2, Borland C

makefile.dj	jconfig.dj	MS-DOS, DJGPP (Delorie's port of GNU C)

makefile.mc6	jconfig.mc6	MS-DOS, Microsoft C (16-bit only)

makefile.wat	jconfig.wat	MS-DOS, OS/2, or Windows NT, Watcom C

makefile.vc	jconfig.vc	Windows NT/95, MS Visual C++

make*.ds	jconfig.vc	Windows NT/95, MS Developer Studio

makefile.mms	jconfig.vms	Digital VMS, with MMS software

makefile.vms	jconfig.vms	Digital VMS, without MMS software

Copy the proper jconfig file to jconfig.h and the makefile to Makefile (or

whatever your system uses as the standard makefile name).  For more info see

the appropriate system-specific hints section near the end of this file.

Configuring the software by hand

--------------------------------

First, generate a jconfig.h file.  If you are moderately familiar with C,

the comments in jconfig.doc should be enough information to do this; just

copy jconfig.doc to jconfig.h and edit it appropriately.  Otherwise, you may

prefer to use the ckconfig.c program.  You will need to compile and execute

ckconfig.c by hand --- we hope you know at least enough to do that.

ckconfig.c may not compile the first try (in fact, the whole idea is for it

to fail if anything is going to).  If you get compile errors, fix them by

editing ckconfig.c according to the directions given in ckconfig.c.  Once

you get it to run, it will write a suitable jconfig.h file, and will also

print out some advice about which makefile to use.

You may also want to look at the canned jconfig files, if there is one for a

system similar to yours.

Second, select a makefile and copy it to Makefile (or whatever your system

uses as the standard makefile name).  The most generic makefiles we provide

are

	makefile.ansi:	if your C compiler supports function prototypes

	makefile.unix:	if not.

(You have function prototypes if ckconfig.c put "#define HAVE_PROTOTYPES"

in jconfig.h.)  You may want to start from one of the other makefiles if

there is one for a system similar to yours.

Look over the selected Makefile and adjust options as needed.  In particular

you may want to change the CC and CFLAGS definitions.  For instance, if you

are using GCC, set CC=gcc.  If you had to use any compiler switches to get

ckconfig.c to work, make sure the same switches are in CFLAGS.

If you are on a system that doesn't use makefiles, you'll need to set up

project files (or whatever you do use) to compile all the source files and

link them into executable files cjpeg, djpeg, jpegtran, rdjpgcom, and wrjpgcom.

See the file lists in any of the makefiles to find out which files go into

each program.  Note that the provided makefiles all make a "library" file

libjpeg first, but you don't have to do that if you don't want to; the file

lists identify which source files are actually needed for compression,

decompression, or both.  As a last resort, you can make a batch script that

just compiles everything and links it all together; makefile.vms is an example

of this (it's for VMS systems that have no make-like utility).

Here are comments about some specific configuration decisions you'll

need to make:

Command line style

------------------

These programs can use a Unix-like command line style which supports

redirection and piping, like this:

	cjpeg inputfile >outputfile

	cjpeg <inputfile >outputfile

	source program | cjpeg >outputfile

The simpler "two file" command line style is just

	cjpeg inputfile outputfile

You may prefer the two-file style, particularly if you don't have pipes.

You MUST use two-file style on any system that doesn't cope well with binary

data fed through stdin/stdout; this is true for some MS-DOS compilers, for

example.  If you're not on a Unix system, it's safest to assume you need

two-file style.  (But if your compiler provides either the Posix-standard

fdopen() library routine or a Microsoft-compatible setmode() routine, you

can safely use the Unix command line style, by defining USE_FDOPEN or

USE_SETMODE respectively.)

To use the two-file style, make jconfig.h say "#define TWO_FILE_COMMANDLINE".

Selecting a memory manager

--------------------------

The IJG code is capable of working on images that are too big to fit in main

memory; data is swapped out to temporary files as necessary.  However, the

code to do this is rather system-dependent.  We provide five different

memory managers:

* jmemansi.c	This version uses the ANSI-standard library routine tmpfile(),

		which not all non-ANSI systems have.  On some systems

		tmpfile() may put the temporary file in a non-optimal

		location; if you don't like what it does, use jmemname.c.

* jmemname.c	This version creates named temporary files.  For anything

		except a Unix machine, you'll need to configure the

		select_file_name() routine appropriately; see the comments

		near the head of jmemname.c.  If you use this version, define

		NEED_SIGNAL_CATCHER in jconfig.h to make sure the temp files

		are removed if the program is aborted.

* jmemnobs.c	(That stands for No Backing Store :-).)  This will compile on

		almost any system, but it assumes you have enough main memory

		or virtual memory to hold the biggest images you work with.

* jmemdos.c	This should be used with most 16-bit MS-DOS compilers.

		See the system-specific notes about MS-DOS for more info.

		IMPORTANT: if you use this, define USE_MSDOS_MEMMGR in

		jconfig.h, and include the assembly file jmemdosa.asm in the

		programs.  The supplied makefiles and jconfig files for

		16-bit MS-DOS compilers already do both.

* jmemmac.c	Custom version for Apple Macintosh; see the system-specific

		notes for Macintosh for more info.

To use a particular memory manager, change the SYSDEPMEM variable in your

makefile to equal the corresponding object file name (for example, jmemansi.o

or jmemansi.obj for jmemansi.c).

If you have plenty of (real or virtual) main memory, just use jmemnobs.c.

"Plenty" means about ten bytes for every pixel in the largest images

you plan to process, so a lot of systems don't meet this criterion.

If yours doesn't, try jmemansi.c first.  If that doesn't compile, you'll have

to use jmemname.c; be sure to adjust select_file_name() for local conditions.

You may also need to change unlink() to remove() in close_backing_store().

Except with jmemnobs.c or jmemmac.c, you need to adjust the DEFAULT_MAX_MEM

setting to a reasonable value for your system (either by adding a #define for

DEFAULT_MAX_MEM to jconfig.h, or by adding a -D switch to the Makefile).

This value limits the amount of data space the program will attempt to

allocate.  Code and static data space isn't counted, so the actual memory

needs for cjpeg or djpeg are typically 100 to 150Kb more than the max-memory

setting.  Larger max-memory settings reduce the amount of I/O needed to

process a large image, but too large a value can result in "insufficient

memory" failures.  On most Unix machines (and other systems with virtual

memory), just set DEFAULT_MAX_MEM to several million and forget it.  At the

other end of the spectrum, for MS-DOS machines you probably can't go much

above 300K to 400K.  (On MS-DOS the value refers to conventional memory only.

Extended/expanded memory is handled separately by jmemdos.c.)

BUILDING THE SOFTWARE

=====================

Now you should be able to compile the software.  Just say "make" (or

whatever's necessary to start the compilation).  Have a cup of coffee.

Here are some things that could go wrong:

If your compiler complains about undefined structures, you should be able to

shut it up by putting "#define INCOMPLETE_TYPES_BROKEN" in jconfig.h.

If you have trouble with missing system include files or inclusion of the

wrong ones, read jinclude.h.  This shouldn't happen if you used configure

or ckconfig.c to set up jconfig.h.

There are a fair number of routines that do not use all of their parameters;

some compilers will issue warnings about this, which you can ignore.  There

are also a few configuration checks that may give "unreachable code" warnings.

Any other warning deserves investigation.

If you don't have a getenv() library routine, define NO_GETENV.

Also see the system-specific hints, below.

TESTING THE SOFTWARE

====================

As a quick test of functionality we've included a small sample image in

several forms:

	testorig.jpg	Starting point for the djpeg tests.

	testimg.ppm	The output of djpeg testorig.jpg

	testimg.bmp	The output of djpeg -bmp -colors 256 testorig.jpg

	testimg.jpg	The output of cjpeg testimg.ppm

	testprog.jpg	Progressive-mode equivalent of testorig.jpg.

	testimgp.jpg	The output of cjpeg -progressive -optimize testimg.ppm

(The first- and second-generation .jpg files aren't identical since JPEG is

lossy.)  If you can generate duplicates of the testimg* files then you

probably have working programs.

With most of the makefiles, "make test" will perform the necessary

comparisons.

If you're using a makefile that doesn't provide the test option, run djpeg

and cjpeg by hand and compare the output files to testimg* with whatever

binary file comparison tool you have.  The files should be bit-for-bit

identical.

If the programs complain "MAX_ALLOC_CHUNK is wrong, please fix", then you

need to reduce MAX_ALLOC_CHUNK to a value that fits in type size_t.

Try adding "#define MAX_ALLOC_CHUNK 65520L" to jconfig.h.  A less likely

configuration error is "ALIGN_TYPE is wrong, please fix": defining ALIGN_TYPE

as long should take care of that one.

If the cjpeg test run fails with "Missing Huffman code table entry", it's a

good bet that you needed to define RIGHT_SHIFT_IS_UNSIGNED.  Go back to the

configuration step and run ckconfig.c.  (This is a good plan for any other

test failure, too.)

If you are using Unix (one-file) command line style on a non-Unix system,

it's a good idea to check that binary I/O through stdin/stdout actually

works.  You should get the same results from "djpeg <testorig.jpg >out.ppm"

as from "djpeg -outfile out.ppm testorig.jpg".  Note that the makefiles all

use the latter style and therefore do not exercise stdin/stdout!  If this

check fails, try recompiling with USE_SETMODE or USE_FDOPEN defined.

If it still doesn't work, better use two-file style.

If you chose a memory manager other than jmemnobs.c, you should test that

temporary-file usage works.  Try "djpeg -bmp -colors 256 -max 0 testorig.jpg"

and make sure its output matches testimg.bmp.  If you have any really large

images handy, try compressing them with -optimize and/or decompressing with

-colors 256 to make sure your DEFAULT_MAX_MEM setting is not too large.

NOTE: this is far from an exhaustive test of the JPEG software; some modules,

such as 1-pass color quantization, are not exercised at all.  It's just a

quick test to give you some confidence that you haven't missed something

major.

INSTALLING THE SOFTWARE

=======================

Once you're done with the above steps, you can install the software by

copying the executable files (cjpeg, djpeg, jpegtran, rdjpgcom, and wrjpgcom)

to wherever you normally install programs.  On Unix systems, you'll also want

to put the man pages (cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1)

in the man-page directory.  The pre-fab makefiles don't support this step

since there's such a wide variety of installation procedures on different

systems.

If you generated a Makefile with the "configure" script, you can just say

	make install

to install the programs and their man pages into the standard places.

(You'll probably need to be root to do this.)  We recommend first saying

	make -n install

to see where configure thought the files should go.  You may need to edit

the Makefile, particularly if your system's conventions for man page

filenames don't match what configure expects.

If you want to install the IJG library itself, for use in compiling other

programs besides ours, then you need to put the four include files

	jpeglib.h jerror.h jconfig.h jmorecfg.h

into your include-file directory, and put the library file libjpeg.a

(extension may vary depending on system) wherever library files go.

If you generated a Makefile with "configure", it will do what it thinks

is the right thing if you say

	make install-lib

OPTIONAL STUFF

==============

Progress monitor:

If you like, you can #define PROGRESS_REPORT (in jconfig.h) to enable display

of percent-done progress reports.  The routine provided in cdjpeg.c merely

prints percentages to stderr, but you can customize it to do something

fancier.

Utah RLE file format support:

We distribute the software with support for RLE image files (Utah Raster

Toolkit format) disabled, because the RLE support won't compile without the

Utah library.  If you have URT version 3.1 or later, you can enable RLE

support as follows:

	1.  #define RLE_SUPPORTED in jconfig.h.

	2.  Add a -I option to CFLAGS in the Makefile for the directory

	    containing the URT .h files (typically the "include"

	    subdirectory of the URT distribution).

	3.  Add -L... -lrle to LDLIBS in the Makefile, where ... specifies

	    the directory containing the URT "librle.a" file (typically the

	    "lib" subdirectory of the URT distribution).

Support for 12-bit-deep pixel data:

The JPEG standard allows either 8-bit or 12-bit data precision.  (For color,

this means 8 or 12 bits per channel, of course.)  If you need to work with

deeper than 8-bit data, you can compile the IJG code for 12-bit operation.

To do so:

  1. In jmorecfg.h, define BITS_IN_JSAMPLE as 12 rather than 8.

  2. In jconfig.h, undefine BMP_SUPPORTED, RLE_SUPPORTED, and TARGA_SUPPORTED,

     because the code for those formats doesn't handle 12-bit data and won't

     even compile.  (The PPM code does work, as explained below.  The GIF

     code works too; it scales 8-bit GIF data to and from 12-bit depth

     automatically.)

  3. Compile.  Don't expect "make test" to pass, since the supplied test

     files are for 8-bit data.

Currently, 12-bit support does not work on 16-bit-int machines.

Note that a 12-bit version will not read 8-bit JPEG files, nor vice versa;

so you'll want to keep around a regular 8-bit compilation as well.

(Run-time selection of data depth, to allow a single copy that does both,

is possible but would probably slow things down considerably; it's very low

on our to-do list.)

The PPM reader (rdppm.c) can read 12-bit data from either text-format or

binary-format PPM and PGM files.  Binary-format PPM/PGM files which have a

maxval greater than 255 are assumed to use 2 bytes per sample, LSB first

(little-endian order).  As of early 1995, 2-byte binary format is not

officially supported by the PBMPLUS library, but it is expected that a

future release of PBMPLUS will support it.  Note that the PPM reader will

read files of any maxval regardless of the BITS_IN_JSAMPLE setting; incoming

data is automatically rescaled to either maxval=255 or maxval=4095 as

appropriate for the cjpeg bit depth.

The PPM writer (wrppm.c) will normally write 2-byte binary PPM or PGM

format, maxval 4095, when compiled with BITS_IN_JSAMPLE=12.  Since this

format is not yet widely supported, you can disable it by compiling wrppm.c

with PPM_NORAWWORD defined; then the data is scaled down to 8 bits to make a

standard 1-byte/sample PPM or PGM file.  (Yes, this means still another copy

of djpeg to keep around.  But hopefully you won't need it for very long.

Poskanzer's supposed to get that new PBMPLUS release out Real Soon Now.)

Of course, if you are working with 12-bit data, you probably have it stored

in some other, nonstandard format.  In that case you'll probably want to

write your own I/O modules to read and write your format.

Note that a 12-bit version of cjpeg always runs in "-optimize" mode, in

order to generate valid Huffman tables.  This is necessary because our

default Huffman tables only cover 8-bit data.

Removing code:

If you need to make a smaller version of the JPEG software, some optional

functions can be removed at compile time.  See the xxx_SUPPORTED #defines in

jconfig.h and jmorecfg.h.  If at all possible, we recommend that you leave in

decoder support for all valid JPEG files, to ensure that you can read anyone's

output.  Taking out support for image file formats that you don't use is the

most painless way to make the programs smaller.  Another possibility is to

remove some of the DCT methods: in particular, the "IFAST" method may not be

enough faster than the others to be worth keeping on your machine.  (If you

do remove ISLOW or IFAST, be sure to redefine JDCT_DEFAULT or JDCT_FASTEST

to a supported method, by adding a #define in jconfig.h.)

OPTIMIZATION

============

Unless you own a Cray, you'll probably be interested in making the JPEG

software go as fast as possible.  This section covers some machine-dependent

optimizations you may want to try.  We suggest that before trying any of

this, you first get the basic installation to pass the self-test step.

Repeat the self-test after any optimization to make sure that you haven't

broken anything.

The integer DCT routines perform a lot of multiplications.  These

multiplications must yield 32-bit results, but none of their input values

are more than 16 bits wide.  On many machines, notably the 680x0 and 80x86

CPUs, a 16x16=>32 bit multiply instruction is faster than a full 32x32=>32

bit multiply.  Unfortunately there is no portable way to specify such a

multiplication in C, but some compilers can generate one when you use the

right combination of casts.  See the MULTIPLYxxx macro definitions in

jdct.h.  If your compiler makes "int" be 32 bits and "short" be 16 bits,

defining SHORTxSHORT_32 is fairly likely to work.  When experimenting with

alternate definitions, be sure to test not only whether the code still works

(use the self-test), but also whether it is actually faster --- on some

compilers, alternate definitions may compute the right answer, yet be slower

than the default.  Timing cjpeg on a large PGM (grayscale) input file is the

best way to check this, as the DCT will be the largest fraction of the runtime

in that mode.  (Note: some of the distributed compiler-specific jconfig files

already contain #define switches to select appropriate MULTIPLYxxx

definitions.)

If your machine has sufficiently fast floating point hardware, you may find

that the float DCT method is faster than the integer DCT methods, even

after tweaking the integer multiply macros.  In that case you may want to

make the float DCT be the default method.  (The only objection to this is

that float DCT results may vary slightly across machines.)  To do that, add

"#define JDCT_DEFAULT JDCT_FLOAT" to jconfig.h.  Even if you don't change

the default, you should redefine JDCT_FASTEST, which is the method selected

by djpeg's -fast switch.  Don't forget to update the documentation files

(usage.doc and/or cjpeg.1, djpeg.1) to agree with what you've done.

If access to "short" arrays is slow on your machine, it may be a win to

define type JCOEF as int rather than short.  This will cost a good deal of

memory though, particularly in some multi-pass modes, so don't do it unless

you have memory to burn and short is REALLY slow.