1 2 Installing libpng 3 4 Contents 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 25 I. Simple installation 26 27 On Unix/Linux and similar systems, you can simply type 28 29 ./configure [--prefix=/path] 30 make check 31 make install 32 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" 35 subdirectories. 36 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. 40 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", 44 below. 45 46 II. Rebuilding the configure scripts 47 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, 54 do 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 65 III. Using scripts/makefile* 66 67 Instead, 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 75 The files that are presently available in the scripts directory 76 are listed and described in scripts/README.txt. 77 78 Or you can use one of the "projects" in the "projects" directory. 79 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. 84 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. 88 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" 92 or "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 100 If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC 101 in your environment and type 102 103 make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test 104 105 IV. Using cmake 106 107 If you want to use "cmake" (see www.cmake.org), type 108 109 cmake . -DCMAKE_INSTALL_PREFIX=/path 110 make 111 make install 112 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. 116 117 V. Directory structure 118 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". 122 123 Your 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 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. 153 154 VI. Building with project files 155 156 If you are building libpng with MSVC, you can enter the 157 libpng projects\visualc71 or vstudio directory and follow the instructions 158 in README.txt. 159 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. 163 164 VII. Building with makefiles 165 166 Copy the file (or files) that you need from the 167 scripts directory into this directory, for example 168 169 MSDOS example: 170 171 copy scripts\makefile.msc makefile 172 copy scripts\pnglibconf.h.prebuilt pnglibconf.h 173 174 UNIX example: 175 176 cp scripts/makefile.std makefile 177 cp scripts/pnglibconf.h.prebuilt pnglibconf.h 178 179 Read the makefile to see if you need to change any source or 180 target directories to match your preferences. 181 182 Then read pnglibconf.dfa to see if you want to make any configuration 183 changes. 184 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. 193 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 198 run "make install". 199 200 VIII. Configuring libpng for 16-bit platforms 201 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. 205 206 IX. Configuring for DOS 207 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. 211 212 X. Configuring for Medium Model 213 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 *". 222 223 XI. Prepending a prefix to exported symbols 224 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. 233 234 XII. Configuring for compiler xxx: 235 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. 245 246 XIII. Removing unwanted object code 247 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 253 "PNG_NO_". 254 255 In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead. 256 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). 269 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 277 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. 284 285 XIV. Enabling or disabling hardware optimizations 286 287 Certain hardware capabilites, such as the Intel SSE instructions, 288 are normally detected at run time. Enable them with configure options 289 such 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 296 or enable them all at once with 297 298 --enable-hardware-optimizations=yes 299 300 or, if you are not using "configure", you can use one 301 or more of 302 303 CPPFLAGS += "-DPNG_ARM_NEON" 304 CPPFLAGS += "-DPNG_MIPS_MSA" 305 CPPFLAGS += "-DPNG_INTEL_SSE" 306 CPPFLAGS += "-DPNG_POWERPC_VSX" 307 308 See for example scripts/makefile.linux-opt 309 310 If you wish to avoid using them, 311 you can disable them via the configure option 312 313 --disable-hardware-optimizations 314 315 to disable them all, or 316 317 --enable-intel-sse=no 318 319 to disable a particular one, 320 or 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 325 If you are using cmake, hardware optimizations are "on" 326 by 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 331 or disable them all at once with 332 333 cmake . -DPNG_HARDWARE_OPTIMIZATIONS=no 334 335 XV. Changes to the build and configuration of libpng in libpng-1.5.x 336 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. 341 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. 346 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. 352 353 A. Specific changes to library configuration capabilities 354 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 358 pnglibconf.h 359 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 369 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. 377 378 B. Changes to the configuration mechanism 379 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. 387 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 394 build. 395 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. 400 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'. 409 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. 418 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. 425 426 XVI. Setjmp/longjmp issues 427 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 434 435 #undef PNG_SETJMP_SUPPORTED 436 437 in your pnglibconf.h or pngusr.h. 438 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. 443 444 XVII. Common linking failures 445 446 If 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 456 XVIII. Other sources of information about libpng: 457 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 460 libpng.3 and png.5. 461 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. 466