SETUP

SETUP instructions for the Independent JPEG Group's JPEG software
=================================================================

This file explains how to configure and compile the JPEG 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 not very automatic; you will need at least a little
familiarity with C programming and program build procedures for your system.

This file contains general instructions, then sections of specific hints for
certain systems.  You may save yourself considerable time if you scan the
whole file before starting to do anything.

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 one potential trap if you are on a non-Unix system:
you may need to convert these files to the local standard text file format
(for example, if you are on MS-DOS you probably have to convert LF end-of-line
to CR/LF).  If so, apply the 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.


STEP 1: PREPARE A MAKEFILE
==========================

First, select a makefile and copy it to "Makefile" (or whatever your version
of make uses as the default makefile name; for example, "makefile.mak" for
old versions of Borland C).  We include several standard makefiles in the
distribution:

	makefile.ansi: for Unix systems with ANSI-compatible C compilers.
	makefile.unix: for Unix systems with non-ANSI C compilers.
	makefile.mc5:  for Microsoft C 5.x under MS-DOS.
	makefile.mc6:  for Microsoft C 6.x under MS-DOS.
	makefile.bcc:  for Borland C (Turbo C) under MS-DOS.
	makefile.pwc:  for Mix Software's Power C under MS-DOS.
	makefile.manx: for Manx Aztec C on Amigas.
	makefile.sas:  for SAS C on Amigas.
	makefile.mms:  for VAX/VMS systems with MMS.
	makefile.vms:  for VAX/VMS systems without MMS.

If you don't see a makefile for your system, we recommend starting from either
makefile.ansi or makefile.unix, depending on whether your compiler accepts
ANSI C or not.  Actually you should start with makefile.ansi whenever your
compiler supports ANSI-style function definitions; you don't need full ANSI
compatibility.  The difference between the two makefiles is that makefile.unix
preprocesses the source code to convert function definitions to old-style C.
(Our thanks to Peter Deutsch of Aladdin Enterprises for the ansi2knr program.)

If you don't know whether your compiler supports ANSI-style function
definitions, then take a look at ckconfig.c.  It is a test program that will
help you figure out this fact, as well as some other facts you'll need in
later steps.  You must compile and execute ckconfig.c by hand; the makefiles
don't provide any support for this.  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, select a makefile according to
the advice it prints out, and make any other changes it recommends.

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 and djpeg.  See the file lists in any of
the makefiles to find out which files go into each program.  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).


STEP 2: EDIT JCONFIG.H
======================

Look over jconfig.h and adjust #defines to reflect the properties of your
system and C compiler.  (If you prefer, you can usually leave jconfig.h
unmodified and add -Dsymbol switches to the Makefile's CFLAGS definition.)

If you have an ANSI-compliant C compiler, no changes should be necessary
except perhaps for RIGHT_SHIFT_IS_UNSIGNED and TWO_FILE_COMMANDLINE.  For
older compilers other changes may be needed, depending on what ANSI features
are supported.

If you don't know enough about C programming to understand the questions in
jconfig.h, then use ckconfig.c to figure out what to change.  (See description
of ckconfig.c in step 1.)

A note about TWO_FILE_COMMANDLINE: defining this selects the command line
syntax in which the input and output files are both named on the command line.
If it's not defined, the output image goes to standard output, and the input
can optionally come from standard input.  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 most MS-DOS compilers, for example.  If you're not on a Unix
system, it's probably safest to assume you need two-file style.


STEP 3: SELECT SYSTEM-DEPENDENT FILES
=====================================

The only system-dependent file in the current version is jmemsys.c.  This file
controls use of temporary files for big images that won't fit in main memory.
You'll notice there is no file by that name in the distribution; you must
select one of the provided versions and copy, rename, or link it to jmemsys.c.
Here are the provided versions:

	jmemansi.c	This is a reasonably portable version that should
			work on most ANSI and near-ANSI C compilers.  It uses
			the ANSI-standard library routine tmpfile(), which not
			all pre-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 constructs the temp file name by itself.
			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 or in the Makefile 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 need to work with.

	jmemdos.c	This should be used in most MS-DOS installations; see
			the system-specific notes about MS-DOS for more info.
			IMPORTANT: if you use this, also copy jmemdos.h to
			jmemsys.h, replacing the standard version.  ALSO,
			include the assembly file jmemdosa.asm in the programs.
			(This last is already done if you used one of the
			supplied MS-DOS-specific makefiles.)

If you have plenty of (real or virtual) main memory, just use jmemnobs.c.
"Plenty" means at least 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, you need to adjust the #define DEFAULT_MAX_MEM to a
reasonable value for your system (either by editing jmemsys.c, 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.


STEP 4: MAKE
============

Now you should be able to "make" the software.

If you have trouble with missing system include files or inclusion of the
wrong ones, look at jinclude.h (or use ckconfig.c, if you are not a C expert).

If your compiler complains about big_sarray_control and big_barray_control
being undefined structures, you should be able to shut it up by adding
-DINCOMPLETE_TYPES_BROKEN to CFLAGS (or add #define INCOMPLETE_TYPES_BROKEN
to 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.  Any
other warning deserves investigation.


STEP 5: TEST
============

As a quick test of functionality we've included a small sample image in
several forms:
	testorig.jpg	A reduced section of the well-known Lenna picture.
	testimg.ppm	The output of djpeg testorig.jpg
	testimg.gif	The output of djpeg -G testorig.jpg
	testimg.jpg	The output of cjpeg testimg.ppm
(The two .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 this option, run
djpeg and cjpeg to generate testout.ppm, testout.gif, and testout.jpg, then
compare these to testimg.* with whatever binary file comparison tool you have.
The files should be bit-for-bit identical.

If your choice of jmemsys.c was anything other than jmemnobs.c, you should
also test that temporary-file usage works.  Try "djpeg -G -m 0 testorig.jpg"
and make sure its output matches testimg.gif.  If you have any really large
images handy, try compressing them with -o and/or decompressing with -G
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 fast 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.

If the test passes, you can copy the executable files cjpeg and djpeg to
wherever you normally install programs.  Read the file USAGE to learn more
about using the programs.


OPTIONAL STUFF
==============

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.0, you can enable RLE support as
follows:
	1.  #define RLE_SUPPORTED in jconfig.h or in the Makefile.
	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).

If you want to incorporate the JPEG code as subroutines in a larger program,
we recommend that you make libjpeg.a.  (See file README for more info.)

CAUTION: When you use the JPEG code as subroutines, we recommend that you make
any required configuration changes by modifying jconfig.h, not by adding -D
switches to the Makefile.  Otherwise you must be sure to provide the same -D
switches when compiling any program that includes the JPEG .h files.

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.  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.
Restricting your encoder, or removing optional functions like block smoothing,
won't hurt compatibility.  Taking out support for image file formats that you
don't use is the most painless way to make the programs smaller.


NOTES FOR SPECIFIC SYSTEMS
==========================

We welcome reports on changes needed for systems not mentioned here.
Submit 'em to jpeg-info@uunet.uu.net.  Also, ckconfig.c is fairly new and not
yet thoroughly tested; if it's wrong about how to configure the JPEG software
for your system, please let us know.


Amiga:

Makefiles are provided for Manx Aztec C and SAS C.  I have also heard from
people who have compiled with the free DICE compiler, using makefile.ansi as a
starting point (set "CC= dcc" and "CFLAGS= -c -DAMIGA -DTWO_FILE_COMMANDLINE
-DNEED_SIGNAL_CATCHER" in the makefile).  For all compilers, we recommend you
use jmemname.c as the system-dependent memory manager.  Assuming you have
-DAMIGA in the makefile, jmemname.c will put temporary files in JPEGTMP:.
Change jmemname.c if you don't like this.


Cray:

Should you be so fortunate as to be running JPEG on a Cray YMP, there is a
compiler bug in Cray's Standard C versions prior to 3.1.  You'll need to
insert a line reading "#pragma novector" just before the loop	
    for (i = 1; i <= (int) htbl->bits[l]; i++)
      huffsize[p++] = (char) l;
in fix_huff_tbl (in V2, line 42 of jchuff.c and line 38 of jdhuff.c).  The
usual symptom of not adding this line is a core-dump.  See Cray's SPR 48222.


HP/Apollo DOMAIN:

At least in version 10.3.5, the C compiler is ANSI but the system include
files are not.  Use makefile.ansi and add -DNONANSI_INCLUDES to CFLAGS.


HP-UX:

If you have HP-UX 7.05 or later with the "software development" C compiler,
then you can use makefile.ansi.  Add "-Aa" to the CFLAGS line in the makefile
to make the compiler work in ANSI mode.  If you have a pre-7.05 system, or if
you are using the non-ANSI C compiler delivered with a minimum HP-UX 8.0
system, then you must use makefile.unix (and do NOT add -Aa).  Also, adding
"-lmalloc" to LDLIBS is recommended if you have libmalloc.a (it seems not to
be present in minimum 8.0).

On HP 9000 series 800 machines, the HP C compiler is buggy in revisions prior
to A.08.07.  If you get complaints about "not a typedef name", you'll have to
convert the code to K&R style (i.e., use makefile.unix).


Macintosh Think C:

You'll have to prepare project files for cjpeg and djpeg; we don't include
those in the distribution since they are not text files.  The COBJECTS and
DOBJECTS lists in makefile.unix show which files should be included in each
project.  Also add the ANSI and Unix C libraries in a separate segment.  You
may need to divide the JPEG files into more than one segment; you can do this
pretty much as you please.

If you have Think C version 5.0 you need not modify jconfig.h; instead you
should turn on both the ANSI Settings and Language Extensions option buttons
(so that both __STDC__ and THINK_C are predefined).  With version 4.0 you must
edit jconfig.h.  (You can #define HAVE_STDC to do the right thing for all
options except const; you must also #define const.)

jcmain and jdmain are set up to provide the usual command-line interface
by means of Think's ccommand() library routine.  Anybody want to write a
more Mac-like interface for us?


MS-DOS, generic comments:

The JPEG code is designed to be compiled with 80x86 "small" or "medium" memory
models (i.e., data pointers are 16 bits unless explicitly declared "far"; code
pointers can be either size).  You should be able to use small model to
compile cjpeg or djpeg by itself, but you will probably have to go to medium
model if you include the JPEG code in a larger application.  This shouldn't
hurt performance much.  You *will* take a noticeable performance hit if you
compile in a large-data memory model, and you should avoid "huge" model if at
all possible.  Be sure that NEED_FAR_POINTERS is defined by jconfig.h or by
the Makefile if you use a small-data model; be sure it is NOT defined if you
use a large-data memory model.  (As distributed, jconfig.h defines
NEED_FAR_POINTERS if MSDOS is defined.)

The DOS-specific memory manager, jmemdos.c, should be used if possible.
(Be sure to install jmemdos.h and jmemdosa.asm along with it.)  If you
can't use jmemdos.c for some reason --- for example, because you don't have
a Microsoft-compatible assembler to assemble jmemdosa.asm --- you'll have
to fall back to jmemansi.c or jmemname.c.  IMPORTANT: if you use either of
those files, you will have to compile in a large-data memory model in order
to get the right stdio library.  Too bad.

None of the above advice applies if you are using a 386 flat-memory-space
environment, such as DJGPP or Watcom C.  For these compilers, do NOT define
NEED_FAR_POINTERS, and do NOT use jmemdos.c.  Use jmemnobs.c if the
environment supplies adequate virtual memory, otherwise use jmemansi.c or
jmemname.c.


MS-DOS, DJGPP:

The file egetopt.c conflicts with some library routines in DJGPP 1.05.
Remove #include "egetopt.c" from jcmain.c and jdmain.c, and in each of
those files change the egetopt(...) call to getopt(...).  This will be
fixed more cleanly in some future version.  Use makefile.ansi, and put
"-DTWO_FILE_COMMANDLINE" (but *not* -DMSDOS) in CFLAGS.


MS-DOS, Microsoft C:

Some versions of MS C fail with an "out of macro expansion space" error
because they can't cope with the macro TRACEMS8 (defined in jpegdata.h).
If this happens to you, the easiest solution is to change TRACEMS8 to
expand to nothing.  You'll lose the ability to dump out JPEG coefficient
tables with djpeg -d -d, but at least you can compile.

makefile.mc6 (MS C 6.x makefile) has not been tested since jmemdosa.asm
was added; we'd appreciate hearing whether it works or not.


Sun:

Don't forget to add -DBSD to CFLAGS.  If you are using GCC on SunOS 4.0.1 or
earlier, you will need to add -DNONANSI_INCLUDES to CFLAGS (your compiler may
be ANSI, but your system include files aren't).  I've gotten conflicting
reports on whether this is still necessary on SunOS 4.1 or later.