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