diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CONTRIBUTORS | 37 | ||||
| -rw-r--r-- | doc/HISTORY | 275 | ||||
| -rw-r--r-- | doc/Netpbm.programming | 96 | ||||
| -rw-r--r-- | doc/TESTS | 186 | ||||
| -rw-r--r-- | doc/patent_summary | 4 |
5 files changed, 398 insertions, 200 deletions
diff --git a/doc/CONTRIBUTORS b/doc/CONTRIBUTORS new file mode 100644 index 00000000..d44cfe79 --- /dev/null +++ b/doc/CONTRIBUTORS @@ -0,0 +1,37 @@ +As an open source project, Netpbm has been written and otherwise supported by +myriad people from all over. Most of them have made isolated contributions +such as a single program, a single new feature, or a single bug fix. To save +clerical effort, we do not list them here and instead refer you to the HISTORY +file. This file lists people who have made broad contributions that wouldn't +be well summarized by the HISTORY file. + +Jef Poskanzer had the original idea for what is now Netpbm and wrote dozens of +programs and the original library code, as well as inventing and designing the +PNM formats and writing documentation. Jef's code contributions stopped in +1991 and because of rewrites, there is not much of Jef's code still remaining, +with what does remain being mostly obsolete. Nonetheless, the impact of that +original code is enormous, as everything in Netpbm today is derived in some +way from Jef's work. + +Bryan Henderson has been maintaining Netpbm since 1999 and has written more +code, in lines, than anyone else. Most of that is just rewriting old code in +a more maintainable style. But Bryan has also fixed more bugs than anyone, +since the normal bug reporting procedure is to tell the maintainer, and Bryan +normally fixes bugs reported that way himself. Bryan has also added many +features and whole programs at the suggestion of users. Bryan has written +most of the documentation, whether by writing manuals for programs whose +authors declined to do so or by rewriting manuals to make them more clear when +users had trouble using Netpbm. + +Akira F Urushibata has made myriad contributions since 2004. Much of the PBM +processing code is his, as he rewrote existing programs to be much faster, in +particular by using special bit-processing machine instructions. He also +created the entire test framework and regression test suite and runs those +regression tests and other tests regularly, and often develops fixes for the +bugs found. Nobody else has done significant alpha testing of Netpbm except +where developers have done it to test code they just wrote. This testing has +turned up many bugs in code going all the way back to 1989. + +Scott Pakin has contributed numerous programs over the years including the +fairly significant work 'pamstereogram'. + diff --git a/doc/HISTORY b/doc/HISTORY index 4304cab7..becf84a0 100644 --- a/doc/HISTORY +++ b/doc/HISTORY @@ -4,7 +4,25 @@ Netpbm. CHANGE HISTORY -------------- -15.06.19 BJH Release 10.70.07 +15.06.28 BJH Release 10.71.00 + + Add pamtopng. Thanks Willem vanSchaik (willem@schaik.com). + + pnmtopng: Add -srgbintent. + + pamstereogram: Add -xbegin. Change default to render from + center outwards intead of from right to left, thus making the + center of the image the crispest part. Thanks Scott Pakin + (scott@pakin.org). + + pamstereogram: Allow -xshift and -yshift to be negative. Thanks + Scott Pakin (scott@pakin.org). + + pnmpsnr: Add -rgb. + + ppmtoicr: remove -rle option. Actually, it never worked + because of a bug. Now it isn't expected to. Ppmtoicr was + new in 1991. pnmtopalm: Fix arithmetic overflow with ridiculously large image. Introduced after Netpbm 10.26 (January 2005) but before @@ -25,6 +43,12 @@ CHANGE HISTORY file name argument. Always broken. (pbmtomatrixorbital was new in Netpbm 10.18 (Setpember 2003). + sbigtopgm: fix detection of camera type. Always broken + (sbigtopgm was new in Netpbm 8.3 (March 2000)). + + sbigtopgm: fix recognition of compressed image. Broken in + Netpbm 10.70 (March 2015). + pbmtogo: Fix bug: garbage first row. Broken at least since November 1989. @@ -37,29 +61,25 @@ CHANGE HISTORY escp2topbm: Fix buffer overrun on certain input. Always broken (escp2topbm was new in Netpbm 10.18 (September 2003)). -15.05.27 BJH Release 10.70.06 - - sbigtopgm: fix detection of camera type. Always broken - (sbigtopgm was new in Netpbm 8.3 (March 2000)). - - sbigtopgm: fix recognition of compressed image. Broken in - Netpbm 10.70.00 (March 2015). - libnetpbm: pm_stripeq: fix bug: wild pointer access when comparator is shorter than comparand. Doesn't affect function, but could cause crash or privacy exposure. Affects reading of a PAM file by any program. Introduced in one of Netpbm 10.27 (March 2005) through 10.35 (August 2006). + pnmconvol: Fix bug: wrong output for pixels that convolve to + negative values (should be clipped to zero). Introduced in + Netpbm 10.68 (September 2014). + pbmtog3: Fix buffer overrun. Introduced in Netpbm 10.23 (July 2004). - pbmtoatk: Fix crash with very long input file name argument. - Always broken (pbmtoatk was new in 1991). - cameratopam: Fix arithmetic underflow in JPEG processing; unknown effect. + pbmtoxbm: Fix bug: crash with zero width input. Broken in + Netpbm 10.37 (December 2006). + sbigtopgm: fix buffer overrun with invalid input image. Always present (sbigtopgm was new in Netpbm 8.3 (March 2000)). @@ -80,10 +100,9 @@ CHANGE HISTORY than 640 pixels. Always broken (pbmtopi3 was new in September 1991). -15.05.18 BJH Release 10.70.05 - - pbmtoxbm: Fix bug: crash with zero width input. Broken in - Netpbm 10.37 (December 2006). + st4topgm: Fix bug: with no argument, uses file named "'" instead + of Standard Input. Always present (st45topgm was new in Netpbm + 10.70 (March 2015). pbmtomgr: Fix incorrect output when input is too large (must be at most 4095 pixels high or wide). Always broken. (pbmtomgr @@ -93,27 +112,26 @@ CHANGE HISTORY image height. Always broken. (pbmtomacp was new in X.V11R3 (March 1988). - Build: don't build and install libjbig and libjasper if we - are using external versions of them instead. + ppmtorgb3: Fix buffer overflow with long input file name. + Always present. (ppmtorgb3 was new in X.V11R4 (November 1989). -15.04.30 BJH Release 10.70.04 + ppmtoarbtxt: fix bug: wrong output when high numbers represent + darker. Broken in Netpbm 10.69 (November 2014). - pnmconvol: Fix bug: wrong output for pixels that convolve to - negative values (should be clipped to zero). Introduced in - Netpbm 10.68 (September 2014). + ppmtoarbtxt: better rounding in sample values. -15.04.29 BJH Release 10.70.03 + libnetpbm: Remove bitio.h as an external interface. - st4topgm: Fix bug: with no argument, uses file named "'" instead - of Standard Input. Always present (st45topgm was new in Netpbm - 10.70.00 (March 2015). + test: replace some GNU-only code with more portable code that + works on OS X. Thanks Ryan Schmidt <ryandesign@macports.org>. - ppmtorgb3: Fix buffer overflow with long input file name. - Always present. (ppmtorgb3 was new in X.V11R4 (November 1989). + makeman: deal properly with backlash in source. Thanks Willem + van Schaik <willem@schaik.com>. -15.04.17 BJH Release 10.70.02 + Build: don't build and install libjbig and libjasper if we + are using external versions of them instead. - Fix typo in doc/TESTS. + Build: various cross-compile fixes, especially for MinGW. Build: work around bug in GCC < 4.2 related to SSE2 builtins that causes compile of pamflip to fail. @@ -121,12 +139,7 @@ CHANGE HISTORY Build: fix 'make package' where config.mk sets a subdirectory other than 'man' for the manual. -15.04.05 BJH Release 10.70.01 - - ppmtoarbtxt: fix bug: wrong output when high numbers represent - darker. Broken in Netpbm 10.69 (November 2014). - - ppmtoarbtxt: better rounding in sample values. + Build: improve pointer man page text. 15.03.29 BJH Release 10.70.00 @@ -189,7 +202,7 @@ CHANGE HISTORY pnmnorm: add -bsingle, -wsingle. ppmtoarbtxt: Do some validation of format strings. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pamcrater: Add -verbose. @@ -305,15 +318,15 @@ CHANGE HISTORY 14.06.29 BJH Release 10.67.00 sgitopnm: add ability to convert 2-channel SGI image. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. sgitopnm: add ability to work with non-seekable input (e.g. a - pipe). Thanks Prophet of the Way <afu@wta.att.ne.jp>. + pipe). Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pamtotiff: add -output, use Standard Output normally (before, it had to be seekable. Also, you could do an append operation to Standard Output; now you have to use -output for that). Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pamsharpness: put primary output on Standard Output instead of on Standard Error as a Netpbm message. @@ -323,7 +336,7 @@ CHANGE HISTORY 10.65 (December 2013). sgitopnm: fix bug: no output if input is RLE compressed. Broken - in Netpbm 10.53 (December 2010). Thanks Prophet of the Way + in Netpbm 10.53 (December 2010). Thanks Akira F Urushibata <afu@wta.att.ne.jp>. jpegtopnm -dumpexif: fix incorrect display of resolution. @@ -354,7 +367,7 @@ CHANGE HISTORY 14.03.30 BJH Release 10.66.00 - Add pamvalidate. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Add pamvalidate. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. Add pamfix: Does what pamfixtrunc did, plus repairs excessive sample values. @@ -362,20 +375,20 @@ CHANGE HISTORY pamfixtrunc: implement as call to new pamfix. pgmhist, ppmhist: Add -forensic: Analyze invalid >maxval pixels. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. - pgmramp: add -diagonal. Thanks Prophet of the Way + pgmramp: add -diagonal. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. libnetpbm: Read functions validate that sample values do not - exceed maxval. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + exceed maxval. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. libnetpbm: Validate image dimensions are small enough that you - can allocate a row buffer. Thanks Prophet of the Way + can allocate a row buffer. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pgmhist: fix incorrect report of quantiles or crash due to array - bounds violation in some builds. Thanks Prophet of the Way + bounds violation in some builds. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. Always broken. Quantile reporting was new in Netpbm 10.61 (December 2012). @@ -393,22 +406,22 @@ CHANGE HISTORY both -xsize and -ysize. Introduced in 10.65. pgmramp: fix bogus output with really large images. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. Always broken. + Akira F Urushibata <afu@wta.att.ne.jp>. Always broken. ppmrelief: fix out-of-bound values in output. Always broken. ppmrelief was new in primordial Netpbm in 1989. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. ppmrelief: fix crash when input image is too small. Always broken. ppmrelief was new in primordial Netpbm in 1989. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pgmtexture: fix buffer overflow. Always broken. (Program was added in primordial Netpbm in 1991). pamdeinterlace: fix incorrect output with -takeodd and image has only one row. Always broken (pamdeinterlace was introduced in - Netpbm 9.21 (January 2001)). Thanks Prophet of the Way + Netpbm 9.21 (January 2001)). Thanks Akira F Urushibata <afu@wta.att.ne.jp>. configure: warn if user says JPEG library is in the linker's @@ -451,7 +464,7 @@ CHANGE HISTORY (September 2011). pnmtops: Fix crash with 12 bits per sample. Introduced in 10.53 - (December 2010). Thanks Prophet of the Way <afu@wta.att.ne.jp>. + (December 2010). Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmtops: Fix bug: wrong output with -ascii85. Introduced in 10.63 (June 2013). @@ -467,16 +480,16 @@ CHANGE HISTORY (September 2011). pbmtoepsi: fix handling of all-white image. Always broken. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pbmtoepsi: fix excessively long raster line. Always broken. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmshear: fix incorrect determination of background color. Always broken. ppmpat: fix crash with -squig with aspect ratio < 1:25 or - > 25:1. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + > 25:1. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. Always broken. pgmkernel: fix some pixels 1 less than they should be. @@ -496,7 +509,7 @@ CHANGE HISTORY as done already with GCC. Build: Use <emmintrin.h> interface for SSE intrinsics - instead of GCC-specific versions. Thanks Prophet of the Way + instead of GCC-specific versions. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. Build on system without vasprintf (not GNU libc): fix compiler @@ -519,7 +532,7 @@ CHANGE HISTORY Add pamtowinicon, winicontopam. Thanks Ludolf Holzheid (lholzheid@bihl-wiedemann.de). - pgmnoise: add -maxval, speed up. Thanks Prophet of the Way + pgmnoise: add -maxval, speed up. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. Perl programs: make them shell programs that reinvoke themselves @@ -586,11 +599,11 @@ CHANGE HISTORY memory access. ppmforge. fix crash when -mesh is 1 or less. Always broken - (program was added in Pbmplus (October 1991). Thanks Prophet of - the Way <afu@wta.att.ne.jp>. + (program was added in Pbmplus (October 1991). Thanks + Akira F Urushibata <afu@wta.att.ne.jp>. ppmforge: fix array bounds violation. Always broken (program - was added in Pbmplus (October 1991). Thanks Prophet of the Way + was added in Pbmplus (October 1991). Thanks Akira F Urushibata <afu@wta.att.ne.jp>. install: fix Perl warning in installnetpbm. Broken in @@ -677,8 +690,8 @@ CHANGE HISTORY pamtompfont, since Netpbm 10.50 (March 2010) in pbmpscale, since 10.44 (September 2008) in pgmhist. - xbmtopbm: fix incorrect output, memory leak. Thanks Prophet of - the Way <afu@wta.att.ne.jp>. + xbmtopbm: fix incorrect output, memory leak. Thanks Akira F + Urushibata <afu@wta.att.ne.jp>. sunicontopnm: Fix incorrect output for depth 8. Always broken (depth = 8 capability was added in Netpbm 10.53 (December 2010). @@ -690,7 +703,7 @@ CHANGE HISTORY ppmpat: Fix bug: wrong output with -poles. Broken in Netpbm 10.47 (June 2009). - Add tests. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Add tests. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. 12.09.30 BJH Release 10.60.00 @@ -702,7 +715,7 @@ CHANGE HISTORY in Netpbm 10.49 (December 2009). pnm_hashtuple: slight performance improvement from new hash - function. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + function. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. ppmtospu: wild memory accesses. Always broken (program added in Netpbm 10.58 (March 2012). @@ -813,11 +826,11 @@ CHANGE HISTORY pamcomp: Retain opacity information from underlying image. - pnmtops: Add PBM fast path. Thanks Prophet of the Way + pnmtops: Add PBM fast path. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. libnetpbm and most programs that use color maps: speedup with - new color hash function. Thanks Prophet of the Way + new color hash function. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmquant: use File::Temp::tempfile() instead of local @@ -935,10 +948,10 @@ CHANGE HISTORY pngtopam: include tuple type in output. Thanks Thomas Henlich <thenlich@users.sourceforge.net>. - sunicontopnm: Understands Depth=8. Thanks Prophet of the Way + sunicontopnm: Understands Depth=8. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. - sunicontopnm: Validate header. Thanks Prophet of the Way + sunicontopnm: Validate header. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. bmptopnm: Don't crash on invalid zero value of image height in @@ -954,11 +967,11 @@ CHANGE HISTORY ilbmtoppm: Don't crash on image that has a transparent color index, but no color map. - sunicontopnm: fix for 32 bit items in input. Thanks Prophet of - the Way <afu@wta.att.ne.jp>. + sunicontopnm: fix for 32 bit items in input. Thanks Akira F + Urushibata <afu@wta.att.ne.jp>. - sunicontopnm: fix arithmetic overflows. Thanks Prophet of the - Way <afu@wta.att.ne.jp>. + sunicontopnm: fix arithmetic overflows. Thanks Akira F + Urushibata <afu@wta.att.ne.jp>. icontopbm: rename to sunicontopnm. @@ -968,14 +981,14 @@ CHANGE HISTORY pamstereogram: slight change to dpi and eye separation defaults. invert near/far dark/light association. Thanks Scott Pakin. - pnmtops: Fix incorrect output with -flate. Thanks Prophet of - the Way <afu@wta.att.ne.jp>. + pnmtops: Fix incorrect output with -flate. Thanks Akira F + Urushibata <afu@wta.att.ne.jp>. sgitopnm: Fix arithmetic overflow on -channel option. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. sgitopnm: Fix crash with -channel on verbatim SGI image. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. fitstopnm: Deal properly with NaN in input image. @@ -986,7 +999,7 @@ CHANGE HISTORY pdbimgtopam: fix corrupted output image. Thanks Scott Pakin. - pnmtops: fix arithmetic overflows. Thanks Prophet of the Way + pnmtops: fix arithmetic overflows. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. Rename all external symbols that don't have a Netpbm prefix @@ -1048,20 +1061,20 @@ CHANGE HISTORY pamx: Make exit status 0 instead of 10 when window manager requests termination. - pnmsmooth: Respect -plain. Thanks Prophet of the Way + pnmsmooth: Respect -plain. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmsmooth: Don't display pnmconvol messages (i.e. run pnmconvol with -quiet). pamflip: speedup for PBM. Use SSE2 and skip some idempotent - pixel movement. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + pixel movement. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. anytopnm: recognize "PC bitmap" in 'file' response as BMP. (in addition to existing "PC bitmap data"). libnetpbm, various PBM programs: Use SSE insted of MMX. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pbmtext/libpbmfont: Fix wild pointer; probably asymptomatic. Introduced in Netpbm 10.39. @@ -1088,14 +1101,14 @@ CHANGE HISTORY avstopam: fix incorrect output. pnmsmooth: fix arithmetic overflow with absurdly large - convolution matrix dimensions. Thanks Prophet of the Way + convolution matrix dimensions. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmsmooth: fix wild pointer: causes wrong arguments to - 'pnmconvol'. Introduced in Netpbm 10.50. Thanks Prophet of the - Way <afu@wta.att.ne.jp>. + 'pnmconvol'. Introduced in Netpbm 10.50. Thanks Akira F + Urushibata <afu@wta.att.ne.jp>. - pamscale: fix -reduce. Introduced in Netpbm 10.27. + pamscale: fix -reduce. Introduced in Netpbm 10.27 (March 2005). pampaintspill: fix incorrect output. @@ -1132,10 +1145,10 @@ CHANGE HISTORY strange combination of luminosity and HSV value. pamenlarge: Make special fast path for scale factors up to 10 - (2, 3, and 5 already existed). Thanks Prophet of the Way + (2, 3, and 5 already existed). Thanks Akira F Urushibata <afu@wta.att.ne.jp>. - pamflip: Speed up for most images. Thanks Prophet of the Way + pamflip: Speed up for most images. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. ybmtopbm: Assume YBM format has raster in natural order @@ -1462,7 +1475,7 @@ CHANGE HISTORY computing means. pamcut, pnmcat, pnmpaste, pnmpad, g3topbm: Add fast PBM - path. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + path. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmpaste: fail if user specified stdin for both images. @@ -1477,10 +1490,10 @@ CHANGE HISTORY pamcut: don't crash when cutting a region entirely to the left or right of the input image, with -pad. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pamcut: don't crash when left > right or top > bottom with - -pad. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + -pad. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pgmhist: arbitrary output when total pixels doesn't fit in an integer. @@ -1571,7 +1584,7 @@ CHANGE HISTORY tag). pbmtext: fail cleanly if -width, -space, or -lspace is - too large for computation. Thanks Prophet of the Way + too large for computation. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmmargin: don't crash with zero margin request. @@ -1612,8 +1625,8 @@ CHANGE HISTORY 07.12.27 BJH Release 10.41.00 - pamenlarge: much faster for PBM. Thanks Prophet of the - Way <afu@wta.att.ne.jp>. + pamenlarge: much faster for PBM. Thanks Akira F Urushibata + <afu@wta.att.ne.jp>. pamenlarge: remove arithmetic overflow. @@ -1675,14 +1688,14 @@ CHANGE HISTORY <pebolle@tiscali.nl>. pnmmargin: add -plain option. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pnmgamma: improve error messages. pamstack: accept Standard Input properly. pnmmargin: recognize invalid options better. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. anytopnm, pnmmargin, pamstretch-gen, ppmquantall: fix small temporary file security exposure. @@ -1775,7 +1788,7 @@ CHANGE HISTORY Add pamfixtrunc. pamtogif: Add -aspect. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pamditherbw: Add -atkinson. @@ -1801,11 +1814,11 @@ CHANGE HISTORY misinterpretations. pamtogif: Speed up for monochrome images. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pamtogif: Speed up for small images by using smaller hash table (so smaller memory footprint). Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. libnetpbm: add pm_drain(). @@ -1879,21 +1892,21 @@ CHANGE HISTORY -interlace. pbmtoxbm: add -name option. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. ppmshift, ppmspread, ppmforge, pgmnoise, pgmcrater: better randomization; won't produce the same image if you run it twice within the same second. pbmtoxbm: Use packed PBM functions for efficiency. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. xbmtopbm: Use packed PBM functions for efficiency. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. cmuwmtopbm, mgrtopbm, pbmtocmuwm, pbmtoicon, pbmtomgr: Use packed PBM functions for efficiency. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. libnetpbm: add pnm_colorname(). @@ -1917,10 +1930,10 @@ CHANGE HISTORY rgb:0/0/0 style color name. pbmtoxbm, pbmtox10bm: merge. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pbmtox10bm: Fix generation of name in XBM file. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pbmtextps: Fix buffer overrun -- typical symptom: extra text generated. @@ -2160,7 +2173,7 @@ CHANGE HISTORY Add pgmmake. bmptopnm: Understands RLE4/RLE8 compressed BMP. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pnmgamma: Add -bt709tosrgb -srgbtobt709, -bt709tolinear, -lineartobt709, -gamma, -rgamma, -ggamma, -bgamma (gammma @@ -2204,11 +2217,11 @@ CHANGE HISTORY being verbose. ppmtobmp, bmptopnm: major speed improvement for PBM. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pbmtog3: Use new GCC features instead of assembly language for superspeed operations. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. pm_make_tmpfile(): Use TEMP and TMP environment variables if TMPDIR not set. @@ -2526,7 +2539,7 @@ CHANGE HISTORY has pointer size != word size and uses the general case code. libnetpbm: fix basic pm_readlittleshort() bug introduced - in 10.27. Affects mdatopbm, rawtopgm, lispmtopgm, + in 10.27 (March 2005). Affects mdatopbm, rawtopgm, lispmtopgm, pcxtoppm, winicontoppm, bmptopnm, sirtopnm, xwdtopnm, cameratopam. @@ -2571,8 +2584,9 @@ CHANGE HISTORY ppmtompeg: fix insecure temp file. Thanks Alexey Tourbin <at@altlinux.ru>. - libnetpbm: fix basic readlittlelong() bug introduced in 10.27. - Affects xwdtopnm, bmptopnm, winicontoppm, lispmtopgm. + libnetpbm: fix basic readlittlelong() bug introduced in 10.27 + (March 2005). Affects xwdtopnm, bmptopnm, winicontoppm, + lispmtopgm. pbmtext/libnetpbm: fix crash with -builtin=fixed. @@ -2865,37 +2879,34 @@ CHANGE HISTORY pamtopnm: accept extra planes (ignore them). - pamcut: major speedup. Thanks Prophet of the Way - <afu@wta.att.ne.jp> (Akira Urushibata ("Douso")). + pamcut: major speedup. Thanks Akira F Urushibata + <afu@wta.att.ne.jp> libnetpbm: Add pnm_getopacity(). libnetpbm: Add pnm_applyopacityrown(), pnm_unapplyopacityrown(). libnetpbm: "pam" read and write routines much more - efficient. Thanks Prophet of the Way - <afu@wta.att.ne.jp> (Akira Urushibata ("Douso")). + efficient. Thanks Akira F Urushibata + <afu@wta.att.ne.jp> Add pnm_formatpamrow(), pnm_allocrowimage(), - pnm_freerowimage(). Thanks Thanks Prophet of the Way - <afu@wta.att.ne.jp> (Akira Urushibata ("Douso")). + pnm_freerowimage(). Thanks Thanks Akira F Urushibata + <afu@wta.att.ne.jp> pnm_readpamrow(): Add option to have "tuplerow" argument NULL and not get the row's contents. Thanks Thanks - Prophet of the Way <afu@wta.att.ne.jp> (Akira Urushibata - ("Douso")). + Akira F Urushibata <afu@wta.att.ne.jp> - Add pnm_writepamrowmult(). Thanks Thanks Prophet of the - Way <afu@wta.att.ne.jp> (Akira Urushibata ("Douso")). + Add pnm_writepamrowmult(). Thanks Thanks Akira F Urushibata + <afu@wta.att.ne.jp>. libnetpbm: format plain format images more nicely. - Thanks Thanks Prophet of the Way <afu@wta.att.ne.jp> - (Akira Urushibata ("Douso")). + Thanks Thanks Akira F Urushibata <afu@wta.att.ne.jp> pamcut: fix bug: Blows up instead of failing cleanly when you try to cut beyond the bounds of the image. - Thanks Thanks Prophet of the Way <afu@wta.att.ne.jp> - (Akira Urushibata ("Douso")). + Thanks Thanks Akira F Urushibata <afu@wta.att.ne.jp> fix bug: MMX/SSE fast PBM writing (with gcc -msse) all wrong. @@ -2905,7 +2916,7 @@ CHANGE HISTORY to enlarge. Speed up pbm_writepbmrow() (and all PBM output programs) - by going a byte at a time. Thanks Prophet of the Way + by going a byte at a time. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pamperspective: fix bug that can cause memory corruption @@ -2936,11 +2947,11 @@ CHANGE HISTORY <esr@thyrsus.com>. pamflip: Large speed, memory improvements for - non-diagonal flips. Thanks Prophet of the Way + non-diagonal flips. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. jbigtopnm, pnmtojbig: Use packed PBM functions to speed up - greatly. Thanks Prophet of the Way <afu@wta.att.ne.jp>. + greatly. Thanks Akira F Urushibata <afu@wta.att.ne.jp>. g3topbm: Don't fail on premature EOF; produce partial output instead. @@ -3007,13 +3018,13 @@ CHANGE HISTORY maketuplergb(), makerowrgb(), makearrayrgb(). pnminvert: much faster for PBMs. Thanks - Prophet of the Way <afu@wta.att.ne.jp>. + Akira F Urushibata <afu@wta.att.ne.jp>. - pbmmake: use packed bits to speed up. Thanks Prophet of - the Way <afu@wta.att.ne.jp> (Akira Urushibata ("Douso")). + pbmmake: use packed bits to speed up. Thanks + Akira F Urushibata <afu@wta.att.ne.jp>. - pbmtog3: speedups. Thanks Prophet of the Way - <afu@wta.att.ne.jp> (Akira Urushibata ("Douso")). + pbmtog3: speedups. Thanks Akira F Urushibata + <afu@wta.att.ne.jp>. Fix gamma value (from .45 to 2.2) in pm_gamma709(), pm_ungamma709(). @@ -3144,7 +3155,7 @@ CHANGE HISTORY Thanks David Jones <drj@pobox.com>. pbmtog3: fix buffer overrun when image > 1728 columns. - Thanks Prophet of the Way <afu@wta.att.ne.jp>. + Thanks Akira F Urushibata <afu@wta.att.ne.jp>. pnmsvgalib: Correct error message - too wide -> too tall. diff --git a/doc/Netpbm.programming b/doc/Netpbm.programming index 62e4c569..c4d38ed4 100644 --- a/doc/Netpbm.programming +++ b/doc/Netpbm.programming @@ -65,6 +65,14 @@ named such as "pbmtog3.test". You can use those to verify your changes. You should also add to these tests and create new ones. But most developers don't. +As you code and test, do 'make dep' to create the header file dependency files +(depend.mk). Do it after 'configure' and every time you change the +dependencies. If you don't, 'make' won't know to recompile things when you +change the header files. For the convenience of users who are just building, +and not changing anything, the make files do work without a 'make dep', but do +so by automatically generating empty depend.mk files. This is not what you +want as a developer. + CODING GUIDELINES ----------------- @@ -111,7 +119,7 @@ before you read these. cause problems to other programs when you do a "merge build" of Netpbm. -* Always start the code in main() with a call to p?m_init(). +* Always start the code in main() with a call to pm_proginit(). * Use shhopt for option processing. i.e. call optParseOptions3(). This is really easy if you just copy the parseCommandLine() function @@ -197,9 +205,38 @@ before you read these. compose code just as easily with spaces as with tabs. * Limit your C code to original ANSI C. Not C99. Not C89. Not C++. Don't - use // for comments or put declarations in the interior of block. + use // for comments or put declarations in the interior of a block. Interpreted languages are OK, with Perl being preferred. +* Make output invariant with input. The program should produce the same output + when fed the same input. This helps with testing and also reduces the chance + of bugs being encountered randomly. + + This is an issue when there are "don't care" bits in the output. You should + normally make those zero. + + The valgrind utility helps you identify instances of undefined bits and + bytes getting to output. + + A common place to find "don't care" bits is padding at the end of a raster + row. You can use pbm_cleanrowend_packed() to clear padding bits when you + use pbm_writepbmrow_packed(). + + Some programs are designed to produce random output. For those, include a + -seed option to specify the seed of the random number generator so that a + tester can make the output predictable. + + +* Never assume that input will be valid; make sure your program can + handle corrupt input gracefully. + + Watch out for arithmetic overflows caused by large numbers in the input. + + Be careful when writing decoders. Make sure that corruptions in the + input image do not cause buffer overruns. + + + DISCONTINUED CODING GUIDELINES ------------------------------ @@ -207,6 +244,9 @@ DISCONTINUED CODING GUIDELINES Here are some things you will see in old Netpbm programs, but they are obsolete and you shouldn't propagate them into a new program: +* Use of pbm_init(), pgm_init(), ppm_init(), and pnm_init(). We use + pm_proginit() now. + * Tolerating non-standard C libraries. You may assume all users have ANSI and POSIX compliant C libraries. E.g. use strrchr() and forget about rindex(). @@ -305,6 +345,10 @@ code. Modular and structured above all. Declare a variable in the most local scope possible. + Global constants are OK. + +* Do not use static variables, except for global constants. + * Keep subroutines small. Generally under 50 lines. But if the routine is a long sequence of simple, similar things, it's OK for it run on ad infinitem. @@ -314,7 +358,7 @@ code. Modular and structured above all. * Do not say "if (a)" when you mean "if (a != 0)". Use "if (a)" only if a is a boolean variable. Or where it's defined so that zero is a special value - that means ("doesn't exist"). + that means "doesn't exist". * Do multiword variable names in camel case: "multiWordName". Underscores waste valuable screen real estate. @@ -325,6 +369,10 @@ code. Modular and structured above all. variable's value is a pointer to a color value, name it "colorP", not "color". +* A variable that represents the number of widgets should be "widgetCt", + ("widget count"), not "widgets". The latter should represent the actual + widgets instead. + * Put "const" as close as possible to the thing that is constant. "int const width", not "const int width". When pointers to constants are involved, it makes it much easier to read. @@ -332,4 +380,46 @@ code. Modular and structured above all. * Free something in the same subroutine that allocates it. Have exactly one free per allocate (this comes naturally if you eliminate gotos). +* Dynamically allocate buffers, for example raster buffers, rather than use + automatic variables. Accidentally overrunning an automatic variable, + typically stored on the stack, is much more dangerous than overrunning a + variable stored in the heap. + +* Use pm_asprintf() to compose strings, instead of sprintf(), strcat(), and + strcpy(). pm_asprintf() is essentially the same as GNU asprintf(), i.e. + sprintf(), except it dynamically allocates the result memory. This + effortlessly makes it impossible to overrun the result buffer. Use + pm_strfree() to free the result memory. You usually need not worry about + the pathological case that there is no memory available for the result, + because in that case, pm_asprintf() returns a constant string "OUT OF MEMORY" + and in most cases, that won't cause a disaster - just incorrect behavior that + is reasonable in the face of such a pathological situation. + +* Do not use the "register" qualifier of a variable. + + +MISCELLANEOUS +------------- + +Object code immutability across compilations +-------------------------------------------- + +In a normal build process the same source code always produces the same object +code. (Of course this depends on your compiler and its settings: if your +compiler writes time stamps into the objects, they will naturally be different +with each compilation.) + +The file lib/compile.h has a time stamp which gets written into libnetpbm.a +and libnetpbm.so . This will affect individual binary executables if they are +statically linked. + +If compile.h does not exist it will be created by the program +buildtools/stamp-date. Once created, compile.h will stay unchanged until you +do "make clean". + +If you make alterations to source which are entirely cosmetic (for example, +changes to comments or amount of indentation) and need to confirm that the +actual program logic is not affected, compare the object files. If you need +to compare library files (or for some reason, statically linked binaries) make +sure that the same compile.h is used throughout. diff --git a/doc/TESTS b/doc/TESTS index 9352b207..65f91d26 100644 --- a/doc/TESTS +++ b/doc/TESTS @@ -8,10 +8,11 @@ Contents 1.4 Repeatability 1.5 Execution time 1.6 Testing package in designated directory - 1.7 Post-install check - 1.8 Skipping test items - 1.9 Valgrind - + 1.7 Pre-packaging check + 1.8 Post-install check + 1.9 Skipping test items + 1.10 Valgrind + 2. Troubleshooting 2.1 Missing programs 2.2 Broken programs @@ -66,31 +67,47 @@ appear at the end: 1.3 Prerequisites ================= -The tests require the Bash command shell. The script Execute-Tests has some -expressions unique to bash. Quite old versions work, at least back to bash -v. 2.05b. +The tests require the Bash command shell. The script Execute-Tests has +some expressions unique to bash. Quite old versions work, at least back +to bash v. 2.05b. The tests also use the following utilities: - - awk - - cat - - cmp - - egrep - - head - - mktemp - - sed - - seq - - tee + - sh + - awk + - perl + + - cat + - cksum + - cmp + - cp + - cut + - date + - dirname + - egrep + - fgrep + - grep + - file + - head + - mkdir + - mktemp + - rm + - sed + - seq + - tee + - tr + - uniq 1.4 Repeatability ================= -The current version of the test package produces identical results if you run -"make check" repeatedly. The tests contain no random elements; some -Netpbm programs use randomness internally, but the tests seed their random -number generators with fixed values so that they too have repeatable results. +The current version of the test package produces identical results if +you run "make check" repeatedly. The tests contain no random elements; +some Netpbm programs use randomness internally, but the tests seed +their random number generators with fixed values so that they too have +repeatable results. @@ -114,64 +131,99 @@ you must do the same with "make check": -1.7 Post-install check -====================== +1.7 Pre-packaging check +======================= + +You can run the tests to check executables after compilation, before +packaging. This feature is intended for developers. + + make check-tree -You can run the tests after installation as well as from the package -directory. Just set $PBM_TESTPREFIX to the bin directory. For example, if -the Netpbm executables are in /usr/local/bin/ do +This test method is incompatible with merge build. - PBM_TESTPREFIX=/usr/local/bin make check +Currently this test method reports several errors when Netpbm is compiled in a +separate build directory. -If you want to test the executables in the default search path do - PBM_TESTPREFIX="" make check -If the color dictionary file rgb.txt is in a non-standard location, you must -set RGBDEF. If you don't, the tests will report several false positives. +1.8 Post-install check +====================== + +You can run the tests after installation. Run this way, the tests are of +programs in the default search path. + + make check-install - PBM_TESTPREFIX=/usr/local/bin RGBDEF=/etc/colors/rgb.txt make check +Make sure to set RGBDEF if the color dictionary file rgb.txt is in +a non-standard location. This must be an absolute path. + RGBDEF=/etc/colors/rgb.txt make check-install -1.8 Skipping test items + +1.9 Skipping test items ======================= The file test/Test-Order is a list of tests which are run. If you want to skip any test, remove the line or comment it out with a "#". +The variable "target", a comma-separated list of Netpbm programs +provides another way to run only select tests. For example to run +only the test scripts which examine giftopnm and pamtogif, do: + + make check target=giftopnm,pamtogif -1.9 Valgrind + +1.10 Valgrind ============ You can run the whole test under Valgrind. This is an advanced feature intended for programmers who work on Netpbm code. -To turn on Valgrind, uncomment this line in test/Execute: +To turn on Valgrind, set VALGRIND_TESTS to "on": + + make check VALGRIND_TESTS="on" + +Valgrind version 3.6.0 or newer is required. For information on +valgrind, visit http://www.valgrind.org/ . + +Valgrind results are output to files, one per process in the directory +/tmp/netpbm-test/valgrind . The file name consists of the test script +name, process ID and the suffix ".vout", e.g.: "ppmmake.18420.vout" . + +Valgrind errors are not reported in the summary report and do not +influence the success/failure count in any way. The following awk +one-liner will report ".vout" files with a positive error count in +the ERROR SUMMARY line: -# export PBM_TESTPREFIX="valgrind --log-fd=4 "${PBM_TESTPREFIX} + awk '/ERROR SUMMARY/ && $4>0 {print FILENAME}' \ + /tmp/netpbm-test/valgrind/*.vout - make check 4> valgrind.log -Note that Valgrind output is directed to file descriptor 4. +You can add or alter valgrind options by editing this line in +test/Execute-Tests: -Valgrind version 3.5.0 or newer is recommended. Older versions do -not report the command that is being executed. + vg_command_base="valgrind --trace-children=yes" -You can add any options for Valgrind should by editing the above mentioned -line. To run "valgrind --track-origins=yes", you must make two changes in +To run "valgrind --track-origins=yes", you must make two changes in config.mk: - - Add -g to CFLAGS. - - Turn stripping off. + - Add -g to CFLAGS + - Turn stripping off: STRIPFLAG = -Valgrind significantly increases execution time. You should consider paring -down the items in Test-Order. You probably don't need to run -"all-in-place.test", which has restrictions in the way errors are reported -when PBM_TESTPREFIX is not a simple directory path. Another test -"pamslice-roundtrip.test" is time-consuming, you may want to skip this one -too. +Valgrind significantly increases execution time. If ordinary +"make check" requires 10 seconds, "make check VALGRIND_TESTS=on" +will require roughly 12 minutes, maybe more. You should consider +either setting "target=..." or paring down the items in Test-Order. +In the latter case, you probably don't need to run "all-in-place.test" +and "legacy-names.test". + +The option "--trace-children-skip" is used to prevent valgrind from +stepping into child processes that are not relevant. This option +appears in valgrind v. 3.6.0. If you wish to conduct valgrind tests +with an older version, comment out the line in Execute-Tests with +"--trace-children-skip". @@ -181,7 +233,8 @@ too. 2.1 Missing programs ==================== -The first test run, "all-in-place.test" detects missing programs. +The first two tests run, "all-in-place.test" and "legacy-names.test" +detect missing programs. If you work around a build glitch with "make --keep-going" you will get a few errors here. @@ -191,10 +244,10 @@ problem, such as a misconfigured dynamic library or a directory-wide permission issue. This kind of failure is known to happen when N is set too high with "make -jN" (overambitious parallel make.) -The current test routines assume a typical build configuration - they are not -aware of the actual configuration you chose. If a choice you make during -configure causes "make" to skip compilation of certain programs, the test -routines won't know and will report failures. +The current test routines assume a typical build configuration - they are +not aware of the actual configuration you chose. If a choice you make +during configure causes "make" to skip compilation of certain programs, +the test routines won't know and will report failures. For details read 'Netpbm Library Prerequisites': http://netpbm.sourceforge.net/prereq.html . @@ -205,8 +258,8 @@ http://netpbm.sourceforge.net/prereq.html . =================== Broken programs will invariably lead to failures. Certain programs -(for instance, image generators 'pbmmake' and 'pgmmake') are used in numerous -test scripts. Problems in them will lead to multiple failures. +(for instance, image generators 'pbmmake' and 'pgmmake') are used in +numerous test scripts. Problems in them will lead to multiple failures. To aid you in this situation each test routine lists the necessary programs near the top. @@ -232,7 +285,7 @@ the color dictionary file rgb.txt. pathname of your rgb.txt file or don't use color names. This is highly unlikely to occur with "make check" right after packaging, -but may appear after installation. +but may appear in the post-installation check "make check-install". To check manually after installation, execute the following and see whether the proper output or the error message appears: @@ -249,6 +302,10 @@ Proper output: The simple remedy is properly setting the environment value RGBDEF to the location of rgb.txt. +RGBDEF must be an absolute path. The following will not work: + + RGBDEF=./lib/rgb.txt make check-install + If you want to hardcode the path, modify RGB_DB_PATH in pm_config.h and run "make" again. Note that running "configure" will cause pm_config.h to be overwritten; changes by editing will be lost. @@ -264,17 +321,19 @@ the newly built version is in place and in working condition. The test routines can test binaries other than the intended target, for example pre-compiled binaries distributed in .rpm -or .deb format. If PBM_TESTPREFIX is explicitly set to a directory -that contains programs from such a source, you should expect multiple -failures due to missing programs, missing features, etc. If -PBM_TESTPREFIX is set to "" (null), the outcome will depend heavily -on what version has precedence in PATH. +or .deb format. If the default binary search path gives priority +to a directory that contains programs from such a source, you should +expect multiple failures due to missing features, etc. with +"make check-install". Netpbm distributed with Debian or Ubuntu is called "Netpbm-Free" and is based on a fork which broke off in 2002. There are many differences. Many tests will fail. However, the test framework itself is valid for -these distributions. +these distributions. The following procedure will allow you to run +the tests on installed Netpbm programs, regardless of the version: + ./configure # accept the defaults + make check-install 2.5 System dependent issues @@ -294,6 +353,7 @@ is the one from glibc and skips certain tests if a different one is detected. + 3. Reporting test failures ========================== diff --git a/doc/patent_summary b/doc/patent_summary index 324fec0d..b9623d09 100644 --- a/doc/patent_summary +++ b/doc/patent_summary @@ -60,8 +60,8 @@ http://burnalljpegs.org contains information on this issue. MPEG patents ------------ -The original University of California distributeion of the Ppmtompeg code -conatins this statement in a README file: +The original University of California distribution of the Ppmtompeg code +contains this statement in a README file: ... patents are held by several companies on various aspects of the MPEG video standard. Companies or individuals who want to develop commercial |