home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 5 / ctrom5b.zip / ctrom5b / DOS / GRAFISCH / JPGSRC5A / INSTALL.DOC < prev    next >
Text File  |  1994-12-07  |  36KB  |  753 lines
  1. INSTALLATION INSTRUCTIONS for the Independent JPEG Group's JPEG software
  2.  
  3. Copyright (C) 1991-1994, Thomas G. Lane.
  4. This file is part of the Independent JPEG Group's software.
  5. For conditions of distribution and use, see the accompanying README file.
  6.  
  7.  
  8. This file explains how to configure and install the IJG software.  We have
  9. tried to make this software extremely portable and flexible, so that it can be
  10. adapted to almost any environment.  The downside of this decision is that the
  11. installation process is complicated.  We have provided shortcuts to simplify
  12. the task on common systems.  But in any case, you will need at least a little
  13. familiarity with C programming and program build procedures for your system.
  14.  
  15. If you are only using this software as part of a larger program, the larger
  16. program's installation procedure may take care of configuring the IJG code.
  17. For example, Ghostscript's installation script will configure the IJG code.
  18. You don't need to read this file if you just want to compile Ghostscript.
  19.  
  20. If you are on a Unix machine, you may not need to read this file at all.
  21. Try doing
  22.     ./configure
  23.     make
  24.     make test
  25. If that doesn't complain, do
  26.     make install
  27. (better do "make -n install" first to see if the makefile will put the files
  28. where you want them).  Read further if you run into snags or want to customize
  29. the code for your system.
  30.  
  31.  
  32. TABLE OF CONTENTS
  33. -----------------
  34.  
  35. Before you start
  36. Configuring the software:
  37.     using the automatic "configure" script
  38.     using one of the supplied jconfig and makefile files
  39.     by hand
  40. Building the software
  41. Testing the software
  42. Installing the software
  43. Optional stuff
  44. Optimization
  45. Hints for specific systems
  46.  
  47.  
  48. BEFORE YOU START
  49. ================
  50.  
  51. Before installing the software you must unpack the distributed source code.
  52. Since you are reading this file, you have probably already succeeded in this
  53. task.  However, there is a potential for error if you needed to convert the
  54. files to the local standard text file format (for example, if you are on
  55. MS-DOS you may have converted LF end-of-line to CR/LF).  You must apply
  56. such conversion to all the files EXCEPT those whose names begin with "test".
  57. The test files contain binary data; if you change them in any way then the
  58. self-test will give bad results.
  59.  
  60. Please check the last section of this file to see if there are hints for the
  61. specific machine or compiler you are using.
  62.  
  63.  
  64. CONFIGURING THE SOFTWARE
  65. ========================
  66.  
  67. To configure the IJG code for your system, you need to create two files:
  68.   * jconfig.h: contains values for system-dependent #define symbols.
  69.   * Makefile: controls the compilation process.
  70. (On a non-Unix machine, you may create "project files" or some other
  71. substitute for a Makefile.  jconfig.h is needed in any environment.)
  72.  
  73. We provide three different ways to generate these files:
  74.   * On a Unix system, you can just run the "configure" script.
  75.   * We provide sample jconfig files and makefiles for popular machines;
  76.     if your machine matches one of the samples, just copy the right sample
  77.     files to jconfig.h and Makefile.
  78.   * If all else fails, read the instructions below and make your own files.
  79.  
  80.  
  81. Configuring the software using the automatic "configure" script
  82. ---------------------------------------------------------------
  83.  
  84. If you are on a Unix machine, you can just type
  85.     ./configure
  86. and let the configure script construct appropriate configuration files.
  87. If you're using "csh" on an old version of System V, you might need to type
  88.     sh configure
  89. instead to prevent csh from trying to execute configure itself.
  90. Expect configure to run for a few minutes, particularly on slower machines;
  91. it works by compiling a series of test programs.
  92.  
  93. Configure was created with GNU Autoconf and it follows the usual conventions
  94. for GNU configure scripts.  It makes a few assumptions that you may want to
  95. override.  You can do this by providing optional switches to configure:
  96.  
  97. * Configure will use gcc (GNU C compiler) if it's available, otherwise cc.
  98. To force a particular compiler to be selected, use the CC option, for example
  99.     ./configure CC='cc'
  100. The same method can be used to include any unusual compiler switches.
  101. For example, on HP-UX you probably want to say
  102.     ./configure CC='cc -Aa'
  103. to get HP's compiler to run in ANSI mode.
  104.  
  105. * The default CFLAGS setting is "-O".  You can override this by saying,
  106. for example, ./configure CFLAGS='-O2'.
  107.  
  108. * Configure will set up the makefile so that "make install" will install files
  109. into /usr/local/bin, /usr/local/man, etc.  You can specify an installation
  110. prefix other than "/usr/local" by giving configure the option "--prefix=PATH".
  111.  
  112. * If you don't have a lot of swap space, you may need to enable the IJG
  113. software's internal virtual memory mechanism.  To do this, give the option
  114. "--enable-maxmem=N" where N is the default maxmemory limit in megabytes.
  115. This is discussed in more detail under "Selecting a memory manager", below.
  116. You probably don't need to worry about this on reasonably-sized Unix machines,
  117. unless you plan to process very large images.
  118.  
  119. Configure has some other features that are useful if you are cross-compiling
  120. or working in a network of multiple machine types; but if you need those
  121. features, you probably already know how to use them.
  122.  
  123.  
  124. Configuring the software using one of the supplied jconfig and makefile files
  125. -----------------------------------------------------------------------------
  126.  
  127. If you have one of these systems, you can just use the provided configuration
  128. files:
  129.  
  130. Makefile    jconfig file    System and/or compiler
  131.  
  132. makefile.manx    jconfig.manx    Amiga, Manx Aztec C
  133. makefile.sas    jconfig.sas    Amiga, SAS C
  134. mak*jpeg.st    jconfig.st    Atari ST/STE/TT, Pure C or Turbo C
  135. makefile.bcc    jconfig.bcc    MS-DOS, Borland C (Turbo C)
  136. makefile.dj    jconfig.dj    MS-DOS, DJGPP (Delorie's port of GNU C)
  137. makefile.mc6    jconfig.mc6    MS-DOS, Microsoft C version 6.x and up
  138. makefile.mms    jconfig.vms    Digital VMS, with MMS software
  139. makefile.vms    jconfig.vms    Digital VMS, without MMS software
  140.  
  141. Copy the proper jconfig file to jconfig.h and the makefile to Makefile
  142. (or whatever your system uses as the standard makefile name).  For the
  143. Atari, we provide three project files; see the Atari hints below.
  144.  
  145.  
  146. Configuring the software by hand
  147. --------------------------------
  148.  
  149. First, generate a jconfig.h file.  If you are moderately familiar with C,
  150. the comments in jconfig.doc should be enough information to do this; just
  151. copy jconfig.doc to jconfig.h and edit it appropriately.  Otherwise, you may
  152. prefer to use the ckconfig.c program.  You will need to compile and execute
  153. ckconfig.c by hand --- we hope you know at least enough to do that.
  154. ckconfig.c may not compile the first try (in fact, the whole idea is for it
  155. to fail if anything is going to).  If you get compile errors, fix them by
  156. editing ckconfig.c according to the directions given in ckconfig.c.  Once
  157. you get it to run, it will write a suitable jconfig.h file, and will also
  158. print out some advice about which makefile to use.
  159.  
  160. You may also want to look at the canned jconfig files, if there is one for a
  161. system similar to yours.
  162.  
  163. Second, select a makefile and copy it to Makefile (or whatever your system
  164. uses as the standard makefile name).  The most generic makefiles we provide
  165. are
  166.     makefile.ansi:    if your C compiler supports function prototypes
  167.     makefile.unix:    if not.
  168. (You have function prototypes if ckconfig.c put "#define HAVE_PROTOTYPES"
  169. in jconfig.h.)  You may want to start from one of the other makefiles if
  170. there is one for a system similar to yours.
  171.  
  172. Look over the selected Makefile and adjust options as needed.  In particular
  173. you may want to change the CC and CFLAGS definitions.  For instance, if you
  174. are using GCC, set CC=gcc.  If you had to use any compiler switches to get
  175. ckconfig.c to work, make sure the same switches are in CFLAGS.
  176.  
  177. If you are on a system that doesn't use makefiles, you'll need to set up
  178. project files (or whatever you do use) to compile all the source files and
  179. link them into executable files cjpeg, djpeg, rdjpgcom, and wrjpgcom.  See
  180. the file lists in any of the makefiles to find out which files go into each
  181. program.  Note that the provided makefiles all make a "library" file libjpeg
  182. first, but you don't have to do that if you don't want to; the file lists
  183. identify which source files are actually needed for compression,
  184. decompression, or both.  As a last resort, you can make a batch script that
  185. just compiles everything and links it all together; makefile.vms is an
  186. example of this (it's for VMS systems that have no make-like utility).
  187.  
  188. Here are comments about some specific configuration decisions you'll
  189. need to make:
  190.  
  191. Command line style
  192. ------------------
  193.  
  194. cjpeg and djpeg can use a Unix-like command line style which supports
  195. redirection and piping, like this:
  196.     cjpeg inputfile >outputfile
  197.     cjpeg <inputfile >outputfile
  198.     source program | cjpeg >outputfile
  199. The simpler "two file" command line style is just
  200.     cjpeg inputfile outputfile
  201. You may prefer the two-file style, particularly if you don't have pipes.
  202.  
  203. You MUST use two-file style on any system that doesn't cope well with binary
  204. data fed through stdin/stdout; this is true for some MS-DOS compilers, for
  205. example.  If you're not on a Unix system, it's safest to assume you need
  206. two-file style.  (But if your compiler provides either the Posix-standard
  207. fdopen() library routine or a Microsoft-compatible setmode() routine, you
  208. can safely use the Unix command line style, by defining USE_FDOPEN or
  209. USE_SETMODE respectively.)
  210.  
  211. To use the two-file style, make jconfig.h say "#define TWO_FILE_COMMANDLINE".
  212.  
  213. Selecting a memory manager
  214. --------------------------
  215.  
  216. The IJG code is capable of working on images that are too big to fit in main
  217. memory; data is swapped out to temporary files as necessary.  However, the
  218. code to do this is rather system-dependent.  We provide four different
  219. memory managers:
  220.  
  221. * jmemansi.c    This version uses the ANSI-standard library routine tmpfile(),
  222.         which not all non-ANSI systems have.  On some systems
  223.         tmpfile() may put the temporary file in a non-optimal
  224.         location; if you don't like what it does, use jmemname.c.
  225.  
  226. * jmemname.c    This version creates named temporary files.  For anything
  227.         except a Unix machine, you'll need to configure the
  228.         select_file_name() routine appropriately; see the comments
  229.         near the head of jmemname.c.  If you use this version, define
  230.         NEED_SIGNAL_CATCHER in jconfig.h to make sure the temp files
  231.         are removed if the program is aborted.
  232.  
  233. * jmemnobs.c    (That stands for No Backing Store :-).)  This will compile on
  234.         almost any system, but it assumes you have enough main memory
  235.         or virtual memory to hold the biggest images you work with.
  236.  
  237. * jmemdos.c    This should be used with most 16-bit MS-DOS compilers.
  238.         See the system-specific notes about MS-DOS for more info.
  239.         IMPORTANT: if you use this, define USE_MSDOS_MEMMGR in
  240.         jconfig.h, and include the assembly file jmemdosa.asm in the
  241.         programs.  The supplied makefiles and jconfig files for
  242.         MS-DOS compilers already do both.
  243.  
  244. To use a particular memory manager, change the SYSDEPMEM variable in your
  245. makefile to equal the corresponding object file name (for example, jmemansi.o
  246. or jmemansi.obj for jmemansi.c).
  247.  
  248. If you have plenty of (real or virtual) main memory, just use jmemnobs.c.
  249. "Plenty" means about ten bytes for every pixel in the largest images
  250. you plan to process, so a lot of systems don't meet this criterion.
  251. If yours doesn't, try jmemansi.c first.  If that doesn't compile, you'll have
  252. to use jmemname.c; be sure to adjust select_file_name() for local conditions.
  253. You may also need to change unlink() to remove() in close_backing_store().
  254.  
  255. Except with jmemnobs.c, you need to adjust the DEFAULT_MAX_MEM setting to a
  256. reasonable value for your system (either by adding a #define for
  257. DEFAULT_MAX_MEM to jconfig.h, or by adding a -D switch to the Makefile).
  258. This value limits the amount of data space the program will attempt to
  259. allocate.  Code and static data space isn't counted, so the actual memory
  260. needs for cjpeg or djpeg are typically 100 to 150Kb more than the max-memory
  261. setting.  Larger max-memory settings reduce the amount of I/O needed to
  262. process a large image, but too large a value can result in "insufficient
  263. memory" failures.  On most Unix machines (and other systems with virtual
  264. memory), just set DEFAULT_MAX_MEM to several million and forget it.  At the
  265. other end of the spectrum, for MS-DOS machines you probably can't go much
  266. above 300K to 400K.  (On MS-DOS the value refers to conventional memory only.
  267. Extended/expanded memory is handled separately by jmemdos.c.)
  268.  
  269.  
  270. BUILDING THE SOFTWARE
  271. =====================
  272.  
  273. Now you should be able to compile the software.  Just say "make" (or
  274. whatever's necessary to start the compilation).  Have a cup of coffee.
  275.  
  276. Here are some things that could go wrong:
  277.  
  278. If your compiler complains about undefined structures, you should be able to
  279. shut it up by putting "#define INCOMPLETE_TYPES_BROKEN" in jconfig.h.
  280.  
  281. If you have trouble with missing system include files or inclusion of the
  282. wrong ones, read jinclude.h.  This shouldn't happen if you used configure
  283. or ckconfig.c to set up jconfig.h.
  284.  
  285. There are a fair number of routines that do not use all of their parameters;
  286. some compilers will issue warnings about this, which you can ignore.  There
  287. are also a few configuration checks that may give "unreachable code" warnings.
  288. Any other warning deserves investigation.
  289.  
  290. If you don't have a getenv() library routine, define NO_GETENV.
  291.  
  292. Also see the system-specific hints, below.
  293.  
  294.  
  295. TESTING THE SOFTWARE
  296. ====================
  297.  
  298. As a quick test of functionality we've included a small sample image in
  299. several forms:
  300.     testorig.jpg    Starting point for the djpeg tests.
  301.     testimg.ppm    The output of djpeg testorig.jpg
  302.     testimg.gif    The output of djpeg -gif testorig.jpg
  303.     testimg.jpg    The output of cjpeg testimg.ppm
  304. (The two .jpg files aren't identical since JPEG is lossy.)  If you can
  305. generate duplicates of the testimg.* files then you probably have working
  306. programs.
  307.  
  308. With most of the makefiles, "make test" will perform the necessary
  309. comparisons.
  310.  
  311. If you're using a makefile that doesn't provide the test option, run djpeg
  312. and cjpeg by hand to generate testout.ppm, testout.gif, and testout.jpg,
  313. then compare these to testimg.* with whatever binary file comparison tool
  314. you have.  The files should be bit-for-bit identical.
  315.  
  316. If the programs complain "MAX_ALLOC_CHUNK is wrong, please fix", then you
  317. need to reduce MAX_ALLOC_CHUNK to a value that fits in type size_t.
  318. Try adding "#define MAX_ALLOC_CHUNK 65520L" to jconfig.h.  A less likely
  319. configuration error is "ALIGN_TYPE is wrong, please fix": defining ALIGN_TYPE
  320. as long should take care of that one.
  321.  
  322. If the cjpeg test run fails with "Missing Huffman code table entry", it's a
  323. good bet that you needed to define RIGHT_SHIFT_IS_UNSIGNED.  Go back to the
  324. configuration step and run ckconfig.c.  (This is a good plan for any other
  325. test failure, too.)
  326.  
  327. If you are using Unix (one-file) command line style on a non-Unix system,
  328. it's a good idea to check that binary I/O through stdin/stdout actually
  329. works.  You should get the same results from "djpeg <testorig.jpg >out.ppm"
  330. as from "djpeg -outfile out.ppm testorig.jpg".  Note that the makefiles all
  331. use the latter style and therefore do not exercise stdin/stdout!  If this
  332. check fails, try recompiling cjpeg.c and djpeg.c with USE_SETMODE or
  333. USE_FDOPEN.  If it still doesn't work, better use two-file style.
  334. (rdjpgcom.c and wrjpgcom.c will also need to be recompiled.)
  335.  
  336. If you chose a memory manager other than jmemnobs.c, you should test that
  337. temporary-file usage works.  Try "djpeg -gif -max 0 testorig.jpg" and make
  338. sure its output matches testimg.gif.  If you have any really large images
  339. handy, try compressing them with -optimize and/or decompressing with -gif to
  340. make sure your DEFAULT_MAX_MEM setting is not too large.
  341.  
  342. NOTE: this is far from an exhaustive test of the JPEG software; some modules,
  343. such as 1-pass color quantization, are not exercised at all.  It's just a
  344. quick test to give you some confidence that you haven't missed something
  345. major.
  346.  
  347.  
  348. INSTALLING THE SOFTWARE
  349. =======================
  350.  
  351. Once you're done with the above steps, you can install the software by
  352. copying the executable files (cjpeg, djpeg, rdjpgcom, and wrjpgcom) to
  353. wherever you normally install programs.  On Unix systems, you'll also want
  354. to put the man pages (cjpeg.1, djpeg.1, rdjpgcom.1, wrjpgcom.1) in the
  355. man-page directory.  The canned makefiles don't support this step since
  356. there's such a wide variety of installation procedures on different systems.
  357.  
  358. If you generated a Makefile with the "configure" script, you can just say
  359.     make install
  360. to install the programs and their man pages into the standard places.
  361. (You'll probably need to be root to do this.)  We recommend first saying
  362.     make -n install
  363. to see where configure thought the files should go.  You may need to edit
  364. the Makefile, particularly if your system's conventions for man page
  365. filenames don't match what configure expects.
  366.  
  367. If you want to install the library file libjpeg.a and the include files j*.h
  368. (for use in compiling other programs besides cjpeg/djpeg), then say
  369.     make install-lib
  370.  
  371.  
  372. OPTIONAL STUFF
  373. ==============
  374.  
  375. Progress monitor:
  376.  
  377. If you like, you can #define PROGRESS_REPORT (in jconfig.h) to enable display
  378. of percent-done progress reports.  The routines provided in cjpeg.c/djpeg.c
  379. merely print percentages to stderr, but you can customize them to do
  380. something fancier.
  381.  
  382. Utah RLE file format support:
  383.  
  384. We distribute the software with support for RLE image files (Utah Raster
  385. Toolkit format) disabled, because the RLE support won't compile without the
  386. Utah library.  If you have URT version 3.1 or later, you can enable RLE
  387. support as follows:
  388.     1.  #define RLE_SUPPORTED in jconfig.h.
  389.     2.  Add a -I option to CFLAGS in the Makefile for the directory
  390.         containing the URT .h files (typically the "include"
  391.         subdirectory of the URT distribution).
  392.     3.  Add -L... -lrle to LDLIBS in the Makefile, where ... specifies
  393.         the directory containing the URT "librle.a" file (typically the
  394.         "lib" subdirectory of the URT distribution).
  395.  
  396. Removing code:
  397.  
  398. If you need to make a smaller version of the JPEG software, some optional
  399. functions can be removed at compile time.  See the xxx_SUPPORTED #defines in
  400. jconfig.h and jmorecfg.h.  If at all possible, we recommend that you leave in
  401. decoder support for all valid JPEG files, to ensure that you can read anyone's
  402. output.  Taking out support for image file formats that you don't use is the
  403. most painless way to make the programs smaller.  Another possibility is to
  404. remove some of the DCT methods: in particular, the "IFAST" method may not be
  405. enough faster than the others to be worth keeping on your machine.  (If you
  406. do remove ISLOW or IFAST, be sure to redefine JDCT_DEFAULT or JDCT_FASTEST
  407. to a supported method, by adding a #define in jconfig.h.)
  408.  
  409.  
  410. OPTIMIZATION
  411. ============
  412.  
  413. Unless you own a Cray, you'll probably be interested in making the JPEG
  414. software go as fast as possible.  This section covers some machine-dependent
  415. optimizations you may want to try.  We suggest that before trying any of
  416. this, you first get the basic installation to pass the self-test step.
  417. Repeat the self-test after any optimization to make sure that you haven't
  418. broken anything.
  419.  
  420. The integer DCT routines perform a lot of multiplications.  These
  421. multiplications must yield 32-bit results, but none of their input values
  422. are more than 16 bits wide.  On many machines, notably the 680x0 and 80x86
  423. CPUs, a 16x16=>32 bit multiply instruction is faster than a full 32x32=>32
  424. bit multiply.  Unfortunately there is no portable way to specify such a
  425. multiplication in C, but some compilers can generate one when you use the
  426. right combination of casts.  See the MULTIPLYxxx macro definitions in
  427. jdct.h.  If your compiler makes "int" be 32 bits and "short" be 16 bits,
  428. defining SHORTxSHORT_32 is fairly likely to work.  When experimenting with
  429. alternate definitions, be sure to test not only whether the code still works
  430. (use the self-test), but also whether it is actually faster --- on some
  431. compilers, alternate definitions may compute the right answer, yet be slower
  432. than the default.  Timing cjpeg on a large PPM input file is the best way to
  433. check this, as the DCT will be the largest fraction of the runtime in that
  434. mode.  (Note: some of the distributed compiler-specific jconfig files
  435. already contain #define switches to select appropriate MULTIPLYxxx
  436. definitions.)
  437.  
  438. If your machine has sufficiently fast floating point hardware, you may find
  439. that the float DCT method is faster than the integer DCT methods, even
  440. after tweaking the integer multiply macros.  In that case you may want to
  441. make the float DCT be the default method.  (The only objection to this is
  442. that float DCT results may vary slightly across machines.)  To do that, add
  443. "#define JDCT_DEFAULT JDCT_FLOAT" to jconfig.h.  Even if you don't change
  444. the default, you should redefine JDCT_FASTEST, which is the method selected
  445. by djpeg's -fast switch.  Don't forget to update the documentation files
  446. (usage.doc and/or cjpeg.1, djpeg.1) to agree with what you've done.
  447.  
  448. If access to "short" arrays is slow on your machine, it may be a win to
  449. define type JCOEF as int rather than short.  This will cost a good deal of
  450. memory though, particularly in some multi-pass modes, so don't do it unless
  451. you have memory to burn and short is REALLY slow.
  452.  
  453. If your compiler can compile function calls in-line, make sure the INLINE
  454. macro in jmorecfg.h is defined as the keyword that marks a function
  455. inline-able.  Some compilers have a switch that tells the compiler to inline
  456. any function it thinks is profitable (e.g., -finline-functions for gcc).
  457. Enabling such a switch is likely to make the compiled code bigger but faster.
  458.  
  459. In general, it's worth trying the maximum optimization level of your compiler,
  460. and experimenting with any optional optimizations such as loop unrolling.
  461. (Unfortunately, far too many compilers have optimizer bugs ... be prepared to
  462. back off if the code fails self-test.)  If you do any experimentation along
  463. these lines, please report the optimal settings to jpeg-info@uunet.uu.net so
  464. we can mention them in future releases.  Be sure to specify your machine and
  465. compiler version.
  466.  
  467.  
  468. HINTS FOR SPECIFIC SYSTEMS
  469. ==========================
  470.  
  471. We welcome reports on changes needed for systems not mentioned here.  Submit
  472. 'em to jpeg-info@uunet.uu.net.  Also, if configure or ckconfig.c is wrong
  473. about how to configure the JPEG software for your system, please let us know.
  474.  
  475.  
  476. Acorn RISC OS:
  477.  
  478. (Thanks to Simon Middleton for these hints on compiling with Desktop C.)
  479. After renaming the files according to Acorn conventions, take a copy of
  480. makefile.ansi, change all occurrences of 'libjpeg.a' to 'libjpeg.o' and
  481. change these definitions as indicated:
  482.  
  483. CFLAGS= -throwback -IC: -Wn
  484. LDLIBS=C:o.Stubs
  485. SYSDEPMEM=jmemansi.o
  486. LN=Link
  487. AR=LibFile -c -o
  488.  
  489. Also add a new line '.c.o:; $(cc) $< $(cflags) -c -o $@'.  Remove the
  490. lines '$(RM) libjpeg.o' and '$(AR2) libjpeg.o' and the 'jconfig.h'
  491. dependency section.
  492.  
  493. Copy jconfig.doc to jconfig.h.  Edit jconfig.h to define TWO_FILE_COMMANDLINE
  494. and CHAR_IS_UNSIGNED.
  495.  
  496. Run the makefile using !AMU not !Make.  If you want to use the 'clean' and
  497. 'test' makefile entries then you will have to fiddle with the syntax a bit
  498. and rename the test files.
  499.  
  500.  
  501. Amiga:
  502.  
  503. SAS C 6.50 reportedly is too buggy to compile the IJG code properly.
  504. A patch to update to 6.51 is available from SAS or AmiNet FTP sites.
  505.  
  506. The supplied config files are set up to use jmemname.c as the memory
  507. manager, with temporary files being created on the device named by
  508. "JPEGTMP:".
  509.  
  510.  
  511. Atari ST/STE/TT:
  512.  
  513. Copy the project files makcjpeg.st, makdjpeg.st, and makljpeg.st to cjpeg.prj,
  514. djpeg.prj, and libjpeg.prj respectively.  The project files should work as-is
  515. with Pure C.  For Turbo C, change library filenames "PC..." to "TC..." in
  516. cjpeg.prj and djpeg.prj.  Note that libjpeg.prj selects jmemansi.c as the
  517. recommended memory manager.  You'll probably want to adjust the
  518. DEFAULT_MAX_MEM setting --- you want it to be a couple hundred K less than
  519. your normal free memory.  Put "#define DEFAULT_MAX_MEM nnnn" into jconfig.h
  520. to do this.
  521.  
  522. To use the 68881/68882 coprocessor for the floating point DCT, add the
  523. compiler option "-8" to the project files and replace PCFLTLIB.LIB with
  524. PC881LIB.LIB in cjpeg.prj and djpeg.prj.  Or if you don't have a
  525. coprocessor, you may prefer to remove the float DCT code by undefining
  526. DCT_FLOAT_SUPPORTED in jmorecfg.h (since without a coprocessor, the float
  527. code will be too slow to be useful).  In that case, you can delete
  528. PCFLTLIB.LIB from the project files.
  529.  
  530. Note that you must make libjpeg.lib before making cjpeg.ttp or djpeg.ttp.
  531. You'll have to perform the self-test by hand.
  532.  
  533. We haven't bothered to include project files for rdjpgcom and wrjpgcom.
  534. Those source files should just be compiled by themselves; they don't
  535. depend on the JPEG library.
  536.  
  537. There is a bug in some older versions of the Turbo C library which causes the
  538. space used by temporary files created with "tmpfile()" not to be freed after
  539. an abnormal program exit.  If you check your disk afterwards, you will find
  540. cluster chains that are allocated but not used by a file.  This should not
  541. happen in cjpeg or djpeg, since we enable a signal catcher to explicitly close
  542. temp files before exiting.  But if you use the JPEG library with your own
  543. code, be sure to supply a signal catcher, or else use a different
  544. system-dependent memory manager.
  545.  
  546.  
  547. Cray:
  548.  
  549. Should you be so fortunate as to be running JPEG on a Cray YMP, there is a
  550. compiler bug in old versions of Cray's Standard C (prior to 3.1).  If you
  551. still have an old compiler, you'll need to insert a line reading
  552. "#pragma novector" just before the loop    
  553.     for (i = 1; i <= (int) htbl->bits[l]; i++)
  554.       huffsize[p++] = (char) l;
  555. in fix_huff_tbl (in V5beta1, line 204 of jchuff.c and line 176 of jdhuff.c).
  556. [This bug may or may not still occur with the current IJG code, but it's
  557. probably a dead issue anyway...]
  558.  
  559.  
  560. HP-UX:
  561.  
  562. If you have HP-UX 7.05 or later with the "software development" C compiler,
  563. you should run the compiler in ANSI mode.  If using the configure script,
  564. say
  565.     ./configure CC='cc -Aa'
  566. (or -Ae if you prefer).  If configuring by hand, use makefile.ansi and add
  567. "-Aa" to the CFLAGS line in the makefile.
  568.  
  569. If you have a pre-7.05 system, or if you are using the non-ANSI C compiler
  570. delivered with a minimum HP-UX system, then you must use makefile.unix
  571. (and do NOT add -Aa); or just run configure without the CC option.
  572.  
  573. On HP 9000 series 800 machines, the HP C compiler is buggy in revisions prior
  574. to A.08.07.  If you get complaints about "not a typedef name", you'll have to
  575. use makefile.unix, or run configure without the CC option.
  576.  
  577.  
  578. Macintosh, MPW:
  579.  
  580. We don't directly support MPW in the current release, but Larry Rosenstein
  581. ported an earlier version of the IJG code without very much trouble.  There's
  582. useful notes and conversion scripts in his kit for porting PBMPLUS to MPW.
  583. You can obtain the kit by FTP to ftp.apple.com, files /pub/lsr/pbmplus-port*.
  584.  
  585.  
  586. Macintosh, Metrowerks CodeWarrior:
  587.  
  588. Metrowerks release DR2 has problems with the IJG code; don't use it.  Release
  589. DR3.5 or later should be OK.
  590.  
  591. The command-line-style interface can be used by defining USE_CCOMMAND and
  592. TWO_FILE_COMMANDLINE (see next entry for more details).
  593.  
  594. On 680x0 Macs, Metrowerks defines type "double" as a 10-byte IEEE extended
  595. float.  jmemmgr.c won't like this: it wants sizeof(ALIGN_TYPE) to be a power
  596. of 2.  Add "#define ALIGN_TYPE long" to jconfig.h to eliminate the complaint.
  597.  
  598.  
  599. Macintosh, Think C:
  600.  
  601. The supplied user-interface files (cjpeg.c and djpeg.c) are set up to provide
  602. a Unix-style command line interface.  You can use this interface on the Mac
  603. by means of Think's ccommand() library routine.  However, a much better
  604. Mac-style user interface has been prepared by Jim Brunner.  You can obtain
  605. the additional source code needed for that user interface by FTP to
  606. sumex-aim.stanford.edu, file /info-mac/dev/src/jpeg-convert-c.hqx.  Jim's
  607. documentation also includes more detailed build instructions for Think C.
  608. (Jim is working on updating this code to work with v5 of the IJG library,
  609. but it wasn't ready as of v5 release time.  Should be out before too long.)
  610.  
  611. If you want to build the minimal command line version, proceed as follows.
  612. You'll have to prepare project files for the programs; we don't include any
  613. in the distribution since they are not text files.  Use the file lists in
  614. any of the supplied makefiles as a guide.  Also add the ANSI and Unix C
  615. libraries in a separate segment.  You may need to divide the JPEG files into
  616. more than one segment; we recommend dividing compression and decompression
  617. modules.  Define USE_CCOMMAND in jconfig.h so that the ccommand() routine is
  618. called.  You must also define TWO_FILE_COMMANDLINE because stdin/stdout
  619. don't handle binary data correctly.
  620.  
  621. On 680x0 Macs, Think C defines type "double" as a 12-byte IEEE extended float.
  622. jmemmgr.c won't like this: it wants sizeof(ALIGN_TYPE) to be a power of 2.
  623. Add "#define ALIGN_TYPE long" to jconfig.h to eliminate the complaint.
  624.  
  625.  
  626. MIPS R3000:
  627.  
  628. MIPS's cc version 1.31 has a rather nasty optimization bug.  Don't use -O
  629. if you have that compiler version.  (Use "cc -V" to check the version.)
  630. Note that the R3000 chip is found in workstations from DEC and others.
  631.  
  632.  
  633. MS-DOS, generic comments for 16-bit compilers:
  634.  
  635. The IJG code is designed to be compiled in 80x86 "small" or "medium" memory
  636. models (i.e., data pointers are 16 bits unless explicitly declared "far";
  637. code pointers can be either size).  You may be able to use small model to
  638. compile cjpeg or djpeg by itself, but you will probably have to use medium
  639. model for any larger application.  This won't make much difference in
  640. performance.  You *will* take a noticeable performance hit if you use a
  641. large-data memory model, and you should avoid "huge" model if at all
  642. possible.  Be sure that NEED_FAR_POINTERS is defined in jconfig.h if you use
  643. a small-data memory model; be sure it is NOT defined if you use a large-data
  644. model.  (The supplied makefiles and jconfig files for Borland and Microsoft C
  645. compile in medium model and define NEED_FAR_POINTERS.)
  646.  
  647. The DOS-specific memory manager, jmemdos.c, should be used if possible.
  648. It needs some assembly-code routines which are in jmemdosa.asm; make sure
  649. your makefile assembles that file and includes it in the library.  If you
  650. don't have a suitable assembler, you can get pre-assembled object files for
  651. jmemdosa by FTP from ftp.uu.net: graphics/jpeg/jdosaobj.zip.
  652.  
  653. When using jmemdos.c, jconfig.h must define USE_MSDOS_MEMMGR and must set
  654. MAX_ALLOC_CHUNK to less than 64K (65520L is a typical value).  If your
  655. C library's far-heap malloc() can't allocate blocks that large, reduce
  656. MAX_ALLOC_CHUNK to whatever it can handle.
  657.  
  658. If you can't use jmemdos.c for some reason --- for example, because you
  659. don't have an assembler to assemble jmemdosa.asm --- you'll have to fall
  660. back to jmemansi.c or jmemname.c.  You'll probably still need to set
  661. MAX_ALLOC_CHUNK in jconfig.h, because most DOS C libraries won't malloc()
  662. more than 64K at a time.  IMPORTANT: if you use jmemansi.c or jmemname.c,
  663. you will have to compile in a large-data memory model in order to get the
  664. right stdio library.  Too bad.
  665.  
  666. wrjpgcom needs to be compiled in large model, because it malloc()s a 64KB
  667. work area to hold the comment text.  If your C library's malloc can't
  668. handle that, reduce MAX_COM_LENGTH as necessary in wrjpgcom.c.
  669.  
  670. Most MS-DOS compilers treat stdin/stdout as text files, so you must use
  671. two-file command line style.  But if your compiler has either fdopen() or
  672. setmode(), you can use one-file style if you like.  To do this, define
  673. USE_SETMODE or USE_FDOPEN so that stdin/stdout will be set to binary mode.
  674. (USE_SETMODE seems to work with more DOS compilers than USE_FDOPEN.)  You
  675. should test that I/O through stdin/stdout produces the same results as I/O
  676. to explicitly named files... the "make test" procedures in the supplied
  677. makefiles do NOT use stdin/stdout.
  678.  
  679.  
  680. MS-DOS, generic comments for 32-bit compilers:
  681.  
  682. None of the above comments about memory models apply if you are using a
  683. 32-bit flat-memory-space environment, such as DJGPP or Watcom C.  (And you
  684. should use one if you have it, as performance will be much better than
  685. 8086-compatible code!)  For flat-memory-space compilers, do NOT define
  686. NEED_FAR_POINTERS, and do NOT use jmemdos.c.  Use jmemnobs.c if the
  687. environment supplies adequate virtual memory, otherwise use jmemansi.c or
  688. jmemname.c.
  689.  
  690. You'll still need to be careful about binary I/O through stdin/stdout.
  691. See the last paragraph of the previous section.
  692.  
  693.  
  694. MS-DOS, Borland C:
  695.  
  696. If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE.
  697. jconfig.bcc includes #define USE_SETMODE.  (fdopen does not work correctly.)
  698.  
  699. Be sure to convert all the source files to DOS text format (CR/LF newlines).
  700. Although Borland C will often work OK with unmodified Unix (LF newlines)
  701. source files, sometimes it will give bogus compile errors.
  702. "Illegal character '#'" is the most common such error.
  703.  
  704.  
  705. MS-DOS, DJGPP:
  706.  
  707. Use a recent version of DJGPP (1.11 or better).  If you prefer two-file
  708. command line style, change the supplied jconfig.dj to define
  709. TWO_FILE_COMMANDLINE.  makefile.dj is set up to generate only COFF files
  710. (cjpeg, djpeg, etc) when you say make.  After testing, say "make exe" to
  711. make executables with stub.exe, or "make standalone" if you want executables
  712. that include go32.  You will probably need to tweak the makefile's pointer to
  713. go32.exe to do "make standalone".
  714.  
  715.  
  716. MS-DOS, Microsoft C:
  717.  
  718. If you want one-file command line style, just undefine TWO_FILE_COMMANDLINE.
  719. jconfig.mc6 includes #define USE_SETMODE.  (fdopen does not work correctly.)
  720.  
  721. Old versions of MS C fail with an "out of macro expansion space" error
  722. because they can't cope with the macro TRACEMS8 (defined in jerror.h).
  723. If this happens to you, the easiest solution is to change TRACEMS8 to
  724. expand to nothing.  You'll lose the ability to dump out JPEG coefficient
  725. tables with djpeg -debug -debug, but at least you can compile.
  726.  
  727. Original MS C 6.0 is very buggy; it compiles incorrect code unless you turn
  728. off optimization entirely (remove -O from CFLAGS).  6.00A is better, but it
  729. still generates bad code if you enable loop optimizations (-Ol or -Ox).
  730.  
  731. MS C 8.0 reportedly fails to compile jquant1.c if optimization is turned off
  732. (yes, off).
  733.  
  734.  
  735. SGI:
  736.  
  737. Set "AR2= ar -ts" rather than "AR2= ranlib" in the Makefile.  If you are
  738. using configure, you should say
  739.     ./configure RANLIB='ar -ts'
  740.  
  741.  
  742. VMS:
  743.  
  744. On an Alpha/VMS system with MMS, be sure to use the "/Marco=Alpha=1"
  745. qualifier with MMS when building the JPEG package.
  746.  
  747. VAX/VMS v5.5-1 may have problems with the test step of the build procedure
  748. reporting differences when it compares the original and test GIF and JPG
  749. images.  If the error points to the last block of the files, it is most
  750. likely bogus and may be safely ignored.  It seems to be because the files
  751. are Stream_LF and Backup/Compare has difficulty with the (presumably) null
  752. padded files.  This problem was not observed on VAX/VMS v6.1 or AXP/VMS v6.1.
  753.