view release on metacpan or  search on metacpan

src/Source/LibJPEG/install.txt  view on Meta::CPAN

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:

* Configure will build both static and shared libraries, if possible.
If you want to build libjpeg only as a static library, say
	./configure --disable-shared
If you want to build libjpeg only as a shared library, say
	./configure --disable-static
Configure uses GNU libtool to take care of system-dependent shared library
building methods.

* 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 "-g" for non-gcc compilers, "-g -O2" for gcc.
You can override this by saying, for example,
	./configure CFLAGS='-O2'
if you want to compile without 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*.vc6	jconfig.vc	Windows NT/95, MS Visual C++ 6
make*.v10	jconfig.vc	Windows NT/95, MS Visual C++ 2010 (v10)
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.txt should be enough information to do this; just
copy jconfig.txt 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 the
default compression parameters are 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.

src/Source/LibJPEG/install.txt  view on Meta::CPAN

	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 9-bit to 12-bit deep pixel data:

The IJG code currently allows 8, 9, 10, 11, or 12 bits sample data precision.
(For color, this means 8 to 12 bits per channel, of course.)  If you need to
work with deeper than 8-bit data, you can compile the IJG code for 9-bit to
12-bit operation.
To do so:
  1. In jmorecfg.h, define BITS_IN_JSAMPLE as 9, 10, 11, or 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 deeper than 8-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, 9-bit to 12-bit support does not work on 16-bit-int machines.

Run-time selection and conversion of data precision are currently not
supported and may be added later.
Exception:  The transcoding part (jpegtran) supports all settings in a
single instance, since it operates on the level of DCT coefficients and
not sample values.

The PPM reader (rdppm.c) can read deeper than 8-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,
MSB first (big-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 maxval=MAXJSAMPLE as appropriate for the
cjpeg bit depth.

The PPM writer (wrppm.c) will normally write 2-byte binary PPM or PGM
format, maxval=MAXJSAMPLE, when compiled with BITS_IN_JSAMPLE>8.  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 9-bit to 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:
The standard Huffman tables are only valid for 8-bit data precision.  If
you selected more than 8-bit data precision, cjpeg uses arithmetic coding
by default.  The Huffman encoder normally uses entropy optimization to
compute usable tables for higher precision.  Otherwise, you'll have to
supply different default Huffman tables.

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.txt 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.

If your compiler can compile function calls in-line, make sure the INLINE
macro in jmorecfg.h is defined as the keyword that marks a function
inline-able.  Some compilers have a switch that tells the compiler to inline
any function it thinks is profitable (e.g., -finline-functions for gcc).
Enabling such a switch is likely to make the compiled code bigger but faster.

In general, it's worth trying the maximum optimization level of your compiler,
and experimenting with any optional optimizations such as loop unrolling.
(Unfortunately, far too many compilers have optimizer bugs ... be prepared to
back off if the code fails self-test.)  If you do any experimentation along
these lines, please report the optimal settings to jpeg-info@jpegclub.org so
we can mention them in future releases.  Be sure to specify your machine and
compiler version.


HINTS FOR SPECIFIC SYSTEMS
==========================

We welcome reports on changes needed for systems not mentioned here.  Submit
'em to jpeg-info@jpegclub.org.  Also, if configure or ckconfig.c is wrong
about how to configure the JPEG software for your system, please let us know.


Acorn RISC OS:

(Thanks to Simon Middleton for these hints on compiling with Desktop C.)
After renaming the files according to Acorn conventions, take a copy of
makefile.ansi, change all occurrences of 'libjpeg.a' to 'libjpeg.o' and
change these definitions as indicated:

CFLAGS= -throwback -IC: -Wn
LDLIBS=C:o.Stubs
SYSDEPMEM=jmemansi.o
LN=Link
AR=LibFile -c -o

Also add a new line '.c.o:; $(cc) $< $(cflags) -c -o $@'.  Remove the
lines '$(RM) libjpeg.o' and '$(AR2) libjpeg.o' and the 'jconfig.h'
dependency section.

Copy jconfig.txt to jconfig.h.  Edit jconfig.h to define TWO_FILE_COMMANDLINE
and CHAR_IS_UNSIGNED.

Run the makefile using !AMU not !Make.  If you want to use the 'clean' and
'test' makefile entries then you will have to fiddle with the syntax a bit
and rename the test files.


Amiga:

SAS C 6.50 reportedly is too buggy to compile the IJG code properly.
A patch to update to 6.51 is available from SAS or AmiNet FTP sites.

The supplied config files are set up to use jmemname.c as the memory
manager, with temporary files being created on the device named by
"JPEGTMP:".


Atari ST/STE/TT:

Copy the project files makcjpeg.st, makdjpeg.st, maktjpeg.st, and makljpeg.st
to cjpeg.prj, djpeg.prj, jpegtran.prj, and libjpeg.prj respectively.  The
project files should work as-is with Pure C.  For Turbo C, change library
filenames "pc..." to "tc..." in each project file.  Note that libjpeg.prj
selects jmemansi.c as the recommended memory manager.  You'll probably want to
adjust the DEFAULT_MAX_MEM setting --- you want it to be a couple hundred K
less than your normal free memory.  Put "#define DEFAULT_MAX_MEM nnnn" into
jconfig.h to do this.

To use the 68881/68882 coprocessor for the floating point DCT, add the
compiler option "-8" to the project files and replace pcfltlib.lib with
pc881lib.lib in cjpeg.prj and djpeg.prj.  Or if you don't have a
coprocessor, you may prefer to remove the float DCT code by undefining
DCT_FLOAT_SUPPORTED in jmorecfg.h (since without a coprocessor, the float
code will be too slow to be useful).  In that case, you can delete
pcfltlib.lib from the project files.

Note that you must make libjpeg.lib before making cjpeg.ttp, djpeg.ttp,
or jpegtran.ttp.  You'll have to perform the self-test by hand.

We haven't bothered to include project files for rdjpgcom and wrjpgcom.
Those source files should just be compiled by themselves; they don't
depend on the JPEG library.  You can use the default.prj project file
of the Pure C distribution to make the programs.

There is a bug in some older versions of the Turbo C library which causes the
space used by temporary files created with "tmpfile()" not to be freed after
an abnormal program exit.  If you check your disk afterwards, you will find
cluster chains that are allocated but not used by a file.  This should not
happen in cjpeg/djpeg/jpegtran, since we enable a signal catcher to explicitly
close temp files before exiting.  But if you use the JPEG library with your
own code, be sure to supply a signal catcher, or else use a different
system-dependent memory manager.


Cray:

Should you be so fortunate as to be running JPEG on a Cray YMP, there is a
compiler bug in old versions of Cray's Standard C (prior to 3.1).  If you
still have an old compiler, 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 V5beta1, line 204 of jchuff.c and line 176 of jdhuff.c).
[This bug may or may not still occur with the current IJG code, but it's
probably a dead issue anyway...]


HP-UX:

If you have HP-UX 7.05 or later with the "software development" C compiler,
you should run the compiler in ANSI mode.  If using the configure script,
say
	./configure CC='cc -Aa'
(or -Ae if you prefer).  If configuring by hand, use makefile.ansi and 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 system, then you must use makefile.unix
(and do NOT add -Aa); or just run configure without the CC option.

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
use makefile.unix, or run configure without the CC option.