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