Installing libpng On Unix/Linux and similar systems, you can simply type ./configure [--prefix=/path] make check make install and ignore the rest of this document. If configure does not work on your system, or if you have a need to change configure.ac or Makefile.am, and you have a reasonably up-to-date set of tools, running ./autogen.sh in a git clone before running ./configure may fix the problem. To be really sure that you aren't using any of the included pre-built scripts, you can do this: ./configure --enable-maintainer-mode make maintainer-clean ./autogen.sh --maintainer --clean ./autogen.sh --maintainer ./configure [--prefix=/path] [other options] make make install make check Instead, you can use one of the custom-built makefiles in the "scripts" directory cp scripts/makefile.system makefile make test make install The files that are presently available in the scripts directory are listed and described in scripts/README.txt. Or you can use one of the "projects" in the "projects" directory. Before installing libpng, you must first install zlib, if it is not already on your system. zlib can usually be found wherever you got libpng. zlib can be placed in another directory, at the same level as libpng. If your system already has a preinstalled zlib you will still need to have access to the zlib.h and zconf.h include files that correspond to the version of zlib that's installed. If you wish to test with a particular zlib that is not first in the standard library search path, put ZLIBLIB, ZLIBINC, CPPFLAGS, LDFLAGS, and LD_LIBRARY_PATH in your environment before running "make test" or "make distcheck": ZLIBLIB=/path/to/lib export ZLIBLIB ZLIBINC=/path/to/include export ZLIBINC CPPFLAGS="-I$ZLIBINC" export CPPFLAGS LDFLAGS="-L$ZLIBLIB" export LDFLAGS LD_LIBRARY_PATH="$ZLIBLIB:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC in your environment and type "make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test". If you want to use "cmake" (see www.cmake.org), type cmake . -DCMAKE_INSTALL_PREFIX=/path make make install You can rename the directories that you downloaded (they might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.7" or "zlib127") so that you have directories called "zlib" and "libpng". Your directory structure should look like this: .. (the parent directory) libpng (this directory) INSTALL (this file) README *.h *.c CMakeLists.txt => "cmake" script configuration files: configure.ac, configure, Makefile.am, Makefile.in, autogen.sh, config.guess, ltmain.sh, missing, libpng.pc.in, libpng-config.in, aclocal.m4, config.h.in, config.sub, depcomp, install-sh, mkinstalldirs, test-pngtest.sh contrib gregbook libtests pngminim pngminus pngsuite visupng projects visualc71 vstudio scripts makefile.* *.def (module definition files) etc. pngtest.png etc. zlib README *.h *.c contrib etc. If the line endings in the files look funny, you may wish to get the other distribution of libpng. It is available in both tar.gz (UNIX style line endings) and zip (DOS style line endings) formats. If you are building libpng with MSVC, you can enter the libpng projects\visualc6 or visualc71 directory and follow the instructions in README.txt. Otherwise enter the zlib directory and follow the instructions in zlib/README, then come back here and run "configure" or choose the appropriate makefile.sys in the scripts directory. Copy the file (or files) that you need from the scripts directory into this directory, for example MSDOS example: copy scripts\makefile.msc makefile UNIX example: cp scripts/makefile.std makefile Read the makefile to see if you need to change any source or target directories to match your preferences. Then read pnglibconf.dfa to see if you want to make any configuration changes. Then just run "make" which will create the libpng library in this directory and "make test" which will run a quick test that reads the "pngtest.png" file and writes a "pngout.png" file that should be identical to it. Look for "9782 zero samples" in the output of the test. For more confidence, you can run another test by typing "pngtest pngnow.png" and looking for "289 zero samples" in the output. Also, you can run "pngtest -m contrib/pngsuite/*.png" and compare your output with the result shown in contrib/pngsuite/README. Most of the makefiles will allow you to run "make install" to put the library in its final resting place (if you want to do that, run "make install" in the zlib directory first if necessary). Some also allow you to run "make test-installed" after you have run "make install". Configuring libpng for 16-bit platforms You will want to look into zconf.h to tell zlib (and thus libpng) that it cannot allocate more then 64K at a time. Even if you can, the memory won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K. Configuring for DOS For DOS users who only have access to the lower 640K, you will have to limit zlib's memory usage via a png_set_compression_mem_level() call. See zlib.h or zconf.h in the zlib library for more information. Configuring for Medium Model Libpng's support for medium model has been tested on most of the popular compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets defined, and FAR gets defined to far in pngconf.h, and you should be all set. Everything in the library (except for zlib's structure) is expecting far data. You must use the typedefs with the p or pp on the end for pointers (or at least look at them and be careful). Make note that the rows of data are defined as png_bytepp, which is an "unsigned char far * far *". Prepending a prefix to exported symbols Starting with libpng-1.6.0, you can configure libpng (when using the "configure" script) to prefix all exported symbols by means of the configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any string beginning with a letter and containing only uppercase and lowercase letters, digits, and the underscore (i.e., a C language identifier). This creates a set of macros in pnglibconf.h, so this is transparent to applications; their function calls get transformed by the macros to use the modified names. Configuring for compiler xxx: All includes for libpng are in pngconf.h. If you need to add, change or delete an include, this is the place to do it. The includes that are not needed outside libpng are placed in pngpriv.h, which is only used by the routines inside libpng itself. The files in libpng proper only include pngpriv.h and png.h, which in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h. As of libpng-1.5.0, pngpriv.h also includes three other private header files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material that previously appeared in the public headers. Removing unwanted object code There are a bunch of #define's in pngconf.h that control what parts of libpng are compiled. All the defines end in _SUPPORTED. If you are never going to use a capability, you can change the #define to #undef before recompiling libpng and save yourself code and data space, or you can turn off individual capabilities with defines that begin with PNG_NO_. In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead. You can also turn all of the transforms and ancillary chunk capabilities off en masse with compiler directives that define PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, or all four, along with directives to turn on any of the capabilities that you do want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra transformations but still leave the library fully capable of reading and writing PNG files with all known public chunks. Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library that is incapable of reading or writing ancillary chunks. If you are not using the progressive reading capability, you can turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING capability, which you'll still have). All the reading and writing specific code are in separate files, so the linker should only grab the files it needs. However, if you want to make sure, or if you are building a stand alone library, all the reading files start with "pngr" and all the writing files start with "pngw". The files that don't match either (like png.c, pngtrans.c, etc.) are used for both reading and writing, and always need to be included. The progressive reader is in pngpread.c If you are creating or distributing a dynamically linked library (a .so or DLL file), you should not remove or disable any parts of the library, as this will cause applications linked with different versions of the library to fail if they call functions not available in your library. The size of the library itself should not be an issue, because only those sections that are actually used will be loaded into memory. Changes to the build and configuration of libpng in libpng-1.5.x Details of internal changes to the library code can be found in the CHANGES file and in the GIT repository logs. These will be of no concern to the vast majority of library users or builders; however, the few who configure libpng to a non-default feature set may need to change how this is done. There should be no need for library builders to alter build scripts if these use the distributed build support - configure or the makefiles - however, users of the makefiles may care to update their build scripts to build pnglibconf.h where the corresponding makefile does not do so. Building libpng with a non-default configuration has changed completely. The old method using pngusr.h should still work correctly even though the way pngusr.h is used in the build has been changed; however, library builders will probably want to examine the changes to take advantage of new capabilities and to simplify their build system. 1. Specific changes to library configuration capabilities The library now supports a complete fixed point implementation and can thus be used on systems that have no floating point support or very limited or slow support. Previously gamma correction, an essential part of complete PNG support, required reasonably fast floating point. As part of this the choice of internal implementation has been made independent of the choice of fixed versus floating point APIs and all the missing fixed point APIs have been implemented. The exact mechanism used to control attributes of API functions has changed. A single set of operating system independent macro definitions is used and operating system specific directives are defined in pnglibconf.h As part of this the mechanism used to choose procedure call standards on those systems that allow a choice has been changed. At present this only affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems running on Intel processors. As before, PNGAPI is defined where required to control the exported API functions; however, two new macros, PNGCBAPI and PNGCAPI, are used instead for callback functions (PNGCBAPI) and (PNGCAPI) for functions that must match a C library prototype (currently only png_longjmp_ptr, which must match the C longjmp function.) The new approach is documented in pngconf.h Despite these changes, libpng 1.5.0 only supports the native C function calling standard on those platforms tested so far (__cdecl on Microsoft Windows). This is because the support requirements for alternative calling conventions seem to no longer exist. Developers who find it necessary to set PNG_API_RULE to 1 should advise the mailing list (png-mng-implement) of this and library builders who use Openwatcom and therefore set PNG_API_RULE to 2 should also contact the mailing list. A new test program, pngvalid, is provided in addition to pngtest. pngvalid validates the arithmetic accuracy of the gamma correction calculations and includes a number of validations of the file format. A subset of the full range of tests is run when "make check" is done (in the 'configure' build.) pngvalid also allows total allocated memory usage to be evaluated and performs additional memory overwrite validation. Many changes to individual feature macros have been made. The following are the changes most likely to be noticed by library builders who configure libpng: 1) All feature macros now have consistent naming: #define PNG_NO_feature turns the feature off #define PNG_feature_SUPPORTED turns the feature on pnglibconf.h contains one line for each feature macro which is either: #define PNG_feature_SUPPORTED if the feature is supported or: /*#undef PNG_feature_SUPPORTED*/ if it is not. Library code consistently checks for the 'SUPPORTED' macro. It does not, and libpng applications should not, check for the 'NO' macro which will not normally be defined even if the feature is not supported. The 'NO' macros are only used internally for setting or not setting the corresponding 'SUPPORTED' macros. Compatibility with the old names is provided as follows: PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED And the following definitions disable the corresponding feature: PNG_SETJMP_NOT_SUPPORTED disables SETJMP PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS Library builders should remove use of the above, inconsistent, names. 2) Warning and error message formatting was previously conditional on the STDIO feature. The library has been changed to use the CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled the library no longer uses the printf(3) functions, even though the default read/write implementations use (FILE) style stdio.h functions. 3) Three feature macros now control the fixed/floating point decisions: PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in practice these are normally required internally anyway (because the PNG file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT merely stops the function from being exported. PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating point implementation or the fixed point one. Typically the fixed point implementation is larger and slower than the floating point implementation on a system that supports floating point; however, it may be faster on a system which lacks floating point hardware and therefore uses a software emulation. 4) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the functions to read and write ints to be disabled independently of PNG_USE_READ_MACROS, which allows libpng to be built with the functions even though the default is to use the macros - this allows applications to choose at app buildtime whether or not to use macros (previously impossible because the functions weren't in the default build.) 2. Changes to the configuration mechanism Prior to libpng-1.5.0 library builders who needed to configure libpng had either to modify the exported pngconf.h header file to add system specific configuration or had to write feature selection macros into pngusr.h and cause this to be included into pngconf.h by defining PNG_USER_CONFIG. The latter mechanism had the disadvantage that an application built without PNG_USER_CONFIG defined would see the unmodified, default, libpng API and thus would probably fail to link. These mechanisms still work in the configure build and in any makefile build that builds pnglibconf.h, although the feature selection macros have changed somewhat as described above. In 1.5.0, however, pngusr.h is processed only once, when the exported header file pnglibconf.h is built. pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the build of pnglibconf.h and it is never included in an application build. The rarely used alternative of adding a list of feature macros to the CPPFLAGS setting in the build also still works; however, the macros will be copied to pnglibconf.h and this may produce macro redefinition warnings when the individual C files are compiled. All configuration now only works if pnglibconf.h is built from scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan (the original author of awk) maintains C source code of that awk and this and all known later implementations (often called by subtly different names - nawk and gawk for example) are adequate to build pnglibconf.h. The Sun Microsystems (now Oracle) program 'awk' is an earlier version and does not work; this may also apply to other systems that have a functioning awk called 'nawk'. Configuration options are now documented in scripts/pnglibconf.dfa. This file also includes dependency information that ensures a configuration is consistent; that is, if a feature is switched off dependent features are also removed. As a recommended alternative to using feature macros in pngusr.h a system builder may also define equivalent options in pngusr.dfa (or, indeed, any file) and add that to the configuration by setting DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate how to do this, and a case where pngusr.h is still required. Configuring libpng for multiprocessing Libpng uses setjmp()/longjmp() for error handling. Unfortunately setjmp() is known to be not thread-safe on some platforms and we don't know of any platform where it is guaranteed to be thread-safe. Therefore, if your application is going to be using multiple threads, you should configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with -DPNG_NO_SETJMP on your compile line, or with #undef PNG_SETJMP_SUPPORTED in your pnglibconf.h or pngusr.h. Other sources of information about libpng: Further information can be found in the README and libpng-manual.txt files, in the individual makefiles, in png.h, and the manual pages libpng.3 and png.5. Using the ./configure script -- 16 December 2002. ================================================= The ./configure script should work compatibly with what scripts/makefile.* did, however there are some options you might need to add to configure explicitly, which previously was done semi-automatically (if you didn't edit scripts/makefile.* yourself, that is) CFLAGS="-Wall -O -funroll-loops \ -malign-loops=2 -malign-functions=2" ./configure --prefix=/usr/include \ --with-pkgconfigdir=/usr/lib/pkgconfig --includedir=/usr/include You can alternatively specify --includedir=/usr/include, /usr/local/include, /usr/include/libpng%NN%, or whatever. If you find that the configure script is out-of-date or is not supporting your platform properly, try running autogen.sh to regenerate "configure", "Makefile.in", and the other configuration files. Then try configure again.