1
  2    Installing libpng
  3
  4Contents
  5
  6       I. Simple installation
  7      II. Rebuilding the configure scripts
  8     III. Using scripts/makefile*
  9      IV. Using cmake
 10       V. Directory structure
 11      VI. Building with project files
 12     VII. Building with makefiles
 13    VIII. Configuring libpng for 16-bit platforms
 14      IX. Configuring for DOS
 15       X. Configuring for Medium Model
 16      XI. Prepending a prefix to exported symbols
 17     XII. Configuring for compiler xxx:
 18    XIII. Removing unwanted object code
 19     XIV. Enabling or disabling hardware optimizations
 20      XV. Changes to the build and configuration of libpng in libpng-1.5.x
 21     XVI. Setjmp/longjmp issues
 22    XVII. Common linking failures
 23   XVIII. Other sources of information about libpng
 24
 25I. Simple installation
 26
 27On Unix/Linux and similar systems, you can simply type
 28
 29    ./configure [--prefix=/path]
 30    make check
 31    make install
 32
 33and ignore the rest of this document.  "/path" is the path to the directory
 34where you want to install the libpng "lib", "include", and "bin"
 35subdirectories.
 36
 37If you downloaded a GIT clone, you will need to run ./autogen.sh before
 38running ./configure, to create "configure" and "Makefile.in" which are
 39not included in the GIT repository.
 40
 41Note that "configure" is only included in the "*.tar" distributions and not
 42in the "*.zip" or "*.7z" distributions. If you downloaded one of those
 43distributions, see "Building with project files" or "Building with makefiles",
 44below.
 45
 46II. Rebuilding the configure scripts
 47
 48If configure does not work on your system, or if you have a need to
 49change configure.ac or Makefile.am, and you have a reasonably
 50up-to-date set of tools, running ./autogen.sh in a git clone before
 51running ./configure may fix the problem.  To be really sure that you
 52aren't using any of the included pre-built scripts, especially if you
 53are building from a tar distribution instead of a git distribution,
 54do this:
 55
 56    ./configure --enable-maintainer-mode
 57    make maintainer-clean
 58    ./autogen.sh --maintainer --clean
 59    ./autogen.sh --maintainer
 60    ./configure [--prefix=/path] [other options]
 61    make
 62    make install
 63    make check
 64
 65III. Using scripts/makefile*
 66
 67Instead, you can use one of the custom-built makefiles in the
 68"scripts" directory
 69
 70    cp scripts/pnglibconf.h.prebuilt pnglibconf.h
 71    cp scripts/makefile.system makefile
 72    make test
 73    make install
 74
 75The files that are presently available in the scripts directory
 76are listed and described in scripts/README.txt.
 77
 78Or you can use one of the "projects" in the "projects" directory.
 79
 80Before installing libpng, you must first install zlib, if it
 81is not already on your system.  zlib can usually be found
 82wherever you got libpng; otherwise go to https://zlib.net/.  You can
 83place zlib in the same directory as libpng or in another directory.
 84
 85If your system already has a preinstalled zlib you will still need
 86to have access to the zlib.h and zconf.h include files that
 87correspond to the version of zlib that's installed.
 88
 89If you wish to test with a particular zlib that is not first in the
 90standard library search path, put ZLIBLIB, ZLIBINC, CPPFLAGS, LDFLAGS,
 91and LD_LIBRARY_PATH in your environment before running "make test"
 92or "make distcheck":
 93
 94    ZLIBLIB=/path/to/lib export ZLIBLIB
 95    ZLIBINC=/path/to/include export ZLIBINC
 96    CPPFLAGS="-I$ZLIBINC" export CPPFLAGS
 97    LDFLAGS="-L$ZLIBLIB" export LDFLAGS
 98    LD_LIBRARY_PATH="$ZLIBLIB:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH
 99
100If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC
101in your environment and type
102
103    make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test
104
105IV. Using cmake
106
107If you want to use "cmake" (see www.cmake.org), type
108
109    cmake . -DCMAKE_INSTALL_PREFIX=/path
110    make
111    make install
112
113As when using the simple configure method described above, "/path" points to
114the installation directory where you want to put the libpng "lib", "include",
115and "bin" subdirectories.
116
117V. Directory structure
118
119You can rename the directories that you downloaded (they
120might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.8"
121or "zlib128") so that you have directories called "zlib" and "libpng".
122
123Your directory structure should look like this:
124
125    .. (the parent directory)
126      libpng (this directory)
127          INSTALL (this file)
128          README
129          *.h, *.c  => libpng source files
130          CMakeLists.txt    =>  "cmake" script
131          configuration files:
132             configure.ac, configure, Makefile.am, Makefile.in,
133             autogen.sh, config.guess, ltmain.sh, missing, libpng.pc.in,
134             libpng-config.in, aclocal.m4, config.h.in, config.sub,
135             depcomp, install-sh, mkinstalldirs, test-pngtest.sh
136          contrib
137             arm-neon, conftest, examples, gregbook, libtests, pngminim,
138             pngminus, pngsuite, tools, visupng
139          projects
140             cbuilder5, owatcom, visualc71, vstudio, xcode
141          scripts
142             makefile.*
143             *.def (module definition files)
144             etc.
145          pngtest.png
146          etc.
147      zlib
148          README, *.h, *.c contrib, etc.
149
150If the line endings in the files look funny, you may wish to get the other
151distribution of libpng.  It is available in both tar.gz (UNIX style line
152endings) and zip (DOS style line endings) formats.
153
154VI. Building with project files
155
156If you are building libpng with MSVC, you can enter the
157libpng projects\visualc71 or vstudio directory and follow the instructions
158in README.txt.
159
160Otherwise enter the zlib directory and follow the instructions in zlib/README,
161then come back here and run "configure" or choose the appropriate
162makefile.sys in the scripts directory.
163
164VII. Building with makefiles
165
166Copy the file (or files) that you need from the
167scripts directory into this directory, for example
168
169MSDOS example:
170
171    copy scripts\makefile.msc makefile
172    copy scripts\pnglibconf.h.prebuilt pnglibconf.h
173
174UNIX example:
175
176    cp scripts/makefile.std makefile
177    cp scripts/pnglibconf.h.prebuilt pnglibconf.h
178
179Read the makefile to see if you need to change any source or
180target directories to match your preferences.
181
182Then read pnglibconf.dfa to see if you want to make any configuration
183changes.
184
185Then just run "make" which will create the libpng library in
186this directory and "make test" which will run a quick test that reads
187the "pngtest.png" file and writes a "pngout.png" file that should be
188identical to it.  Look for "9782 zero samples" in the output of the
189test.  For more confidence, you can run another test by typing
190"pngtest pngnow.png" and looking for "289 zero samples" in the output.
191Also, you can run "pngtest -m contrib/pngsuite/*.png" and compare
192your output with the result shown in contrib/pngsuite/README.
193
194Most of the makefiles will allow you to run "make install" to
195put the library in its final resting place (if you want to
196do that, run "make install" in the zlib directory first if necessary).
197Some also allow you to run "make test-installed" after you have
198run "make install".
199
200VIII. Configuring libpng for 16-bit platforms
201
202You will want to look into zconf.h to tell zlib (and thus libpng) that
203it cannot allocate more than 64K at a time.  Even if you can, the memory
204won't be accessible.  So limit zlib and libpng to 64K by defining MAXSEG_64K.
205
206IX. Configuring for DOS
207
208For DOS users who only have access to the lower 640K, you will
209have to limit zlib's memory usage via a png_set_compression_mem_level()
210call.  See zlib.h or zconf.h in the zlib library for more information.
211
212X. Configuring for Medium Model
213
214Libpng's support for medium model has been tested on most of the popular
215compilers.  Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
216defined, and FAR gets defined to far in pngconf.h, and you should be
217all set.  Everything in the library (except for zlib's structure) is
218expecting far data.  You must use the typedefs with the p or pp on
219the end for pointers (or at least look at them and be careful).  Make
220note that the rows of data are defined as png_bytepp, which is
221an "unsigned char far * far *".
222
223XI. Prepending a prefix to exported symbols
224
225Starting with libpng-1.6.0, you can configure libpng (when using the
226"configure" script) to prefix all exported symbols by means of the
227configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
228string beginning with a letter and containing only uppercase
229and lowercase letters, digits, and the underscore (i.e., a C language
230identifier).  This creates a set of macros in pnglibconf.h, so this is
231transparent to applications; their function calls get transformed by
232the macros to use the modified names.
233
234XII. Configuring for compiler xxx:
235
236All includes for libpng are in pngconf.h.  If you need to add, change
237or delete an include, this is the place to do it.
238The includes that are not needed outside libpng are placed in pngpriv.h,
239which is only used by the routines inside libpng itself.
240The files in libpng proper only include pngpriv.h and png.h, which
241in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
242As of libpng-1.5.0, pngpriv.h also includes three other private header
243files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
244that previously appeared in the public headers.
245
246XIII. Removing unwanted object code
247
248There are a bunch of #define's in pngconf.h that control what parts of
249libpng are compiled.  All the defines end in _SUPPORTED.  If you are
250never going to use a capability, you can change the #define to #undef
251before recompiling libpng and save yourself code and data space, or
252you can turn off individual capabilities with defines that begin with
253"PNG_NO_".
254
255In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
256
257You can also turn all of the transforms and ancillary chunk capabilities
258off en masse with compiler directives that define
259PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
260or all four, along with directives to turn on any of the capabilities that
261you do want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the
262extra transformations but still leave the library fully capable of reading
263and writing PNG files with all known public chunks. Use of the
264PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
265that is incapable of reading or writing ancillary chunks.  If you are
266not using the progressive reading capability, you can turn that off
267with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
268capability, which you'll still have).
269
270All the reading and writing specific code are in separate files, so the
271linker should only grab the files it needs.  However, if you want to
272make sure, or if you are building a stand alone library, all the
273reading files start with "pngr" and all the writing files start with "pngw".
274The files that don't match either (like png.c, pngtrans.c, etc.)
275are used for both reading and writing, and always need to be included.
276The progressive reader is in pngpread.c
277
278If you are creating or distributing a dynamically linked library (a .so
279or DLL file), you should not remove or disable any parts of the library,
280as this will cause applications linked with different versions of the
281library to fail if they call functions not available in your library.
282The size of the library itself should not be an issue, because only
283those sections that are actually used will be loaded into memory.
284
285XIV. Enabling or disabling hardware optimizations
286
287Certain hardware capabilites, such as the Intel SSE instructions,
288are normally detected at run time. Enable them with configure options
289such as one of
290
291   --enable-arm-neon=yes
292   --enable-mips-msa=yes
293   --enable-intel-sse=yes
294   --enable-powerpc-vsx=yes
295
296or enable them all at once with
297
298   --enable-hardware-optimizations=yes
299
300or, if you are not using "configure", you can use one
301or more of
302
303   CPPFLAGS += "-DPNG_ARM_NEON"
304   CPPFLAGS += "-DPNG_MIPS_MSA"
305   CPPFLAGS += "-DPNG_INTEL_SSE"
306   CPPFLAGS += "-DPNG_POWERPC_VSX"
307
308See for example scripts/makefile.linux-opt
309
310If you wish to avoid using them,
311you can disable them via the configure option
312
313   --disable-hardware-optimizations
314
315to disable them all, or
316
317   --enable-intel-sse=no
318
319to disable a particular one,
320or via compiler-command options such as
321
322   CPPFLAGS += "-DPNG_ARM_NEON_OPT=0, -DPNG_MIPS_MSA_OPT=0,
323   -DPNG_INTEL_SSE_OPT=0, -DPNG_POWERPC_VSX_OPT=0"
324
325If you are using cmake, hardware optimizations are "on"
326by default. To disable them, use
327
328    cmake . -DPNG_ARM_NEON=no -DPNG_INTEL_SSE=no \
329            -DPNG_MIPS_MSA=no -DPNG_POWERPC_VSX=no
330
331or disable them all at once with
332
333    cmake . -DPNG_HARDWARE_OPTIMIZATIONS=no
334
335XV. Changes to the build and configuration of libpng in libpng-1.5.x
336
337Details of internal changes to the library code can be found in the CHANGES
338file and in the GIT repository logs.  These will be of no concern to the vast
339majority of library users or builders; however, the few who configure libpng
340to a non-default feature set may need to change how this is done.
341
342There should be no need for library builders to alter build scripts if
343these use the distributed build support - configure or the makefiles -
344however, users of the makefiles may care to update their build scripts
345to build pnglibconf.h where the corresponding makefile does not do so.
346
347Building libpng with a non-default configuration has changed completely.
348The old method using pngusr.h should still work correctly even though the
349way pngusr.h is used in the build has been changed; however, library
350builders will probably want to examine the changes to take advantage of
351new capabilities and to simplify their build system.
352
353A. Specific changes to library configuration capabilities
354
355The exact mechanism used to control attributes of API functions has
356changed.  A single set of operating system independent macro definitions
357is used and operating system specific directives are defined in
358pnglibconf.h
359
360As part of this the mechanism used to choose procedure call standards on
361those systems that allow a choice has been changed.  At present this only
362affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
363running on Intel processors.  As before, PNGAPI is defined where required
364to control the exported API functions; however, two new macros, PNGCBAPI
365and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
366(PNGCAPI) for functions that must match a C library prototype (currently
367only png_longjmp_ptr, which must match the C longjmp function.)  The new
368approach is documented in pngconf.h
369
370Despite these changes, libpng 1.5.0 only supports the native C function
371calling standard on those platforms tested so far ("__cdecl" on Microsoft
372Windows).  This is because the support requirements for alternative
373calling conventions seem to no longer exist.  Developers who find it
374necessary to set PNG_API_RULE to 1 should advise the mailing list
375(png-mng-implement) of this and library builders who use Openwatcom and
376therefore set PNG_API_RULE to 2 should also contact the mailing list.
377
378B. Changes to the configuration mechanism
379
380Prior to libpng-1.5.0 library builders who needed to configure libpng
381had either to modify the exported pngconf.h header file to add system
382specific configuration or had to write feature selection macros into
383pngusr.h and cause this to be included into pngconf.h by defining
384PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
385application built without PNG_USER_CONFIG defined would see the
386unmodified, default, libpng API and thus would probably fail to link.
387
388These mechanisms still work in the configure build and in any makefile
389build that builds pnglibconf.h, although the feature selection macros
390have changed somewhat as described above.  In 1.5.0, however, pngusr.h is
391processed only once, at the time the exported header file pnglibconf.h is
392built.  pngconf.h no longer includes pngusr.h; therefore, pngusr.h is ignored
393after the build of pnglibconf.h and it is never included in an application
394build.
395
396The formerly used alternative of adding a list of feature macros to the
397CPPFLAGS setting in the build also still works; however, the macros will be
398copied to pnglibconf.h and this may produce macro redefinition warnings
399when the individual C files are compiled.
400
401All configuration now only works if pnglibconf.h is built from
402scripts/pnglibconf.dfa.  This requires the program awk.  Brian Kernighan
403(the original author of awk) maintains C source code of that awk and this
404and all known later implementations (often called by subtly different
405names - nawk and gawk for example) are adequate to build pnglibconf.h.
406The Sun Microsystems (now Oracle) program 'awk' is an earlier version
407and does not work; this may also apply to other systems that have a
408functioning awk called 'nawk'.
409
410Configuration options are now documented in scripts/pnglibconf.dfa.  This
411file also includes dependency information that ensures a configuration is
412consistent; that is, if a feature is switched off, dependent features are
413also switched off.  As a recommended alternative to using feature macros in
414pngusr.h a system builder may also define equivalent options in pngusr.dfa
415(or, indeed, any file) and add that to the configuration by setting
416DFA_XTRA to the file name.  The makefiles in contrib/pngminim illustrate
417how to do this, and also illustrate a case where pngusr.h is still required.
418
419After you have built libpng, the definitions that were recorded in
420pnglibconf.h are available to your application (pnglibconf.h is included
421in png.h and gets installed alongside png.h and pngconf.h in your
422$PREFIX/include directory).  Do not edit pnglibconf.h after you have built
423libpng, because than the settings would not accurately reflect the settings
424that were used to build libpng.
425
426XVI. Setjmp/longjmp issues
427
428Libpng uses setjmp()/longjmp() for error handling.  Unfortunately setjmp()
429is known to be not thread-safe on some platforms and we don't know of
430any platform where it is guaranteed to be thread-safe.  Therefore, if
431your application is going to be using multiple threads, you should
432configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with
433-DPNG_NO_SETJMP on your compile line, or with
434
435    #undef PNG_SETJMP_SUPPORTED
436
437in your pnglibconf.h or pngusr.h.
438
439Starting with libpng-1.6.0, the library included a "simplified API".
440This requires setjmp/longjmp, so you must either build the library
441with PNG_SETJMP_SUPPORTED defined, or with PNG_SIMPLIFIED_READ_SUPPORTED
442and PNG_SIMPLIFIED_WRITE_SUPPORTED undefined.
443
444XVII. Common linking failures
445
446If your application fails to find libpng or zlib entries while linking:
447
448  Be sure "-lz" appears after "-lpng" on your linking command.
449
450  Be sure you have built libpng, zlib, and your application for the
451  same platform (e.g., 32-bit or 64-bit).
452
453  If you are using the vstudio project, observe the WARNING in
454  project/vstudio/README.txt.
455
456XVIII. Other sources of information about libpng:
457
458Further information can be found in the README and libpng-manual.txt
459files, in the individual makefiles, in png.h, and the manual pages
460libpng.3 and png.5.
461
462Copyright (c) 1998-2002,2006-2016 Glenn Randers-Pehrson
463This document is released under the libpng license.
464For conditions of distribution and use, see the disclaimer
465and license in png.h.