236 lines
11 KiB
Plaintext
236 lines
11 KiB
Plaintext
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
|
|
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.tc: for Borland's 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.
|
|
|
|
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 config.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 config.c by hand; the makefiles
|
|
don't provide any support for this. config.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 config.c according to the directions
|
|
given in config.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 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 (makcjpeg.lst and
|
|
makdjpeg.lst are handy summaries).
|
|
|
|
|
|
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 config.c to figure out what to change. (See description
|
|
of config.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: 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 config.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 4: TEST
|
|
============
|
|
|
|
As a quick test of functionality we've included three small sample files:
|
|
testorig.jpg A reduced section of the well-known Lenna picture.
|
|
testimg.ppm The output of djpeg 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 testimg.ppm and testimg.jpg then you probably have a
|
|
working port.
|
|
|
|
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 and testout.jpg, then compare these to
|
|
testimg.* with whatever file comparison tool you have. The files should be
|
|
bit-for-bit identical.
|
|
|
|
NOTE: this is far from an exhaustive test of the JPEG software; some modules,
|
|
such as color quantization and GIF I/O, 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. Then use the jconfig.h and jpegdata.h
|
|
files as your interface to the JPEG functions, and link libjpeg.a with your
|
|
program. Your surrounding program will have to provide functionality similar
|
|
to what's in jcmain.c or jdmain.c, and you may want to replace jerror.c and
|
|
possibly other modules depending on your needs. See the "architecture" file
|
|
for more info. If it seems to you that the system structure doesn't
|
|
accommodate what you want to do, please contact the authors.
|
|
|
|
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, config.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.
|
|
|
|
|
|
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. 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 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).
|
|
|
|
IBM RS/6000 AIX:
|
|
|
|
The CFLAGS switch to make the compiler define __STDC__ is "-qlanglvl=ansi".
|
|
|
|
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 should be able to just turn on __STDC__
|
|
through the compiler switch that enables that. With version 4.0 you must
|
|
manually edit jconfig.h. (You can #define __STDC__, but also #define const.)
|
|
|
|
Microsoft C for MS-DOS:
|
|
|
|
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.
|
|
|
|
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.
|