view release on metacpan or  search on metacpan

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

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

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

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.

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