[96425] | 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
|
---|
[103316] | 131 | ci
|
---|
| 132 | ci_*.sh
|
---|
[96425] | 133 | configuration files:
|
---|
| 134 | configure.ac, configure, Makefile.am, Makefile.in,
|
---|
| 135 | autogen.sh, config.guess, ltmain.sh, missing, libpng.pc.in,
|
---|
| 136 | libpng-config.in, aclocal.m4, config.h.in, config.sub,
|
---|
[103316] | 137 | depcomp, install-sh, mkinstalldirs, test-pngtest.sh, etc.
|
---|
[96425] | 138 | contrib
|
---|
| 139 | arm-neon, conftest, examples, gregbook, libtests, pngminim,
|
---|
| 140 | pngminus, pngsuite, tools, visupng
|
---|
| 141 | projects
|
---|
[103316] | 142 | owatcom, visualc71, vstudio
|
---|
[96425] | 143 | scripts
|
---|
| 144 | makefile.*
|
---|
| 145 | *.def (module definition files)
|
---|
| 146 | etc.
|
---|
| 147 | pngtest.png
|
---|
| 148 | etc.
|
---|
| 149 | zlib
|
---|
[103316] | 150 | README, *.h, *.c, contrib, etc.
|
---|
[96425] | 151 |
|
---|
| 152 | If the line endings in the files look funny, you may wish to get the other
|
---|
| 153 | distribution of libpng. It is available in both tar.gz (UNIX style line
|
---|
| 154 | endings) and zip (DOS style line endings) formats.
|
---|
| 155 |
|
---|
| 156 | VI. Building with project files
|
---|
| 157 |
|
---|
[103316] | 158 | If you are building libpng with Microsoft Visual Studio, you can enter
|
---|
| 159 | the directory projects\visualc71 or projects\vstudio and follow the
|
---|
| 160 | instructions in README.txt.
|
---|
[96425] | 161 |
|
---|
[103316] | 162 | Otherwise, enter the zlib directory and follow the instructions in
|
---|
| 163 | zlib/README, then come back here and run "configure" or choose the
|
---|
| 164 | appropriate makefile in the scripts directory.
|
---|
[96425] | 165 |
|
---|
| 166 | VII. Building with makefiles
|
---|
| 167 |
|
---|
| 168 | Copy the file (or files) that you need from the
|
---|
| 169 | scripts directory into this directory, for example
|
---|
| 170 |
|
---|
[103316] | 171 | UNIX example:
|
---|
[96425] | 172 |
|
---|
[103316] | 173 | cp scripts/makefile.std Makefile
|
---|
| 174 | make
|
---|
[96425] | 175 |
|
---|
[103316] | 176 | Windows example:
|
---|
[96425] | 177 |
|
---|
[103316] | 178 | nmake -f scripts\makefile.vcwin32
|
---|
[96425] | 179 |
|
---|
| 180 | Read the makefile to see if you need to change any source or
|
---|
| 181 | target directories to match your preferences.
|
---|
| 182 |
|
---|
| 183 | Then read pnglibconf.dfa to see if you want to make any configuration
|
---|
| 184 | changes.
|
---|
| 185 |
|
---|
| 186 | Then just run "make" which will create the libpng library in
|
---|
| 187 | this directory and "make test" which will run a quick test that reads
|
---|
| 188 | the "pngtest.png" file and writes a "pngout.png" file that should be
|
---|
| 189 | identical to it. Look for "9782 zero samples" in the output of the
|
---|
| 190 | test. For more confidence, you can run another test by typing
|
---|
| 191 | "pngtest pngnow.png" and looking for "289 zero samples" in the output.
|
---|
| 192 | Also, you can run "pngtest -m contrib/pngsuite/*.png" and compare
|
---|
| 193 | your output with the result shown in contrib/pngsuite/README.
|
---|
| 194 |
|
---|
[103316] | 195 | Most of the makefiles used to allow you to run "make install" to put
|
---|
| 196 | the library in its final resting place, but that feature is no longer
|
---|
| 197 | supported. The only tested and supported manners to install libpng are
|
---|
| 198 | the conventional build and install procedures driven by the configure
|
---|
| 199 | script or by the CMake file.
|
---|
[96425] | 200 |
|
---|
[103316] | 201 | VIII. Configuring for DOS and other 16-bit platforms
|
---|
[96425] | 202 |
|
---|
[103316] | 203 | Officially, the support for 16-bit platforms has been removed.
|
---|
[96425] | 204 |
|
---|
| 205 | For DOS users who only have access to the lower 640K, you will
|
---|
| 206 | have to limit zlib's memory usage via a png_set_compression_mem_level()
|
---|
| 207 | call. See zlib.h or zconf.h in the zlib library for more information.
|
---|
| 208 |
|
---|
[103316] | 209 | You may be or may not be in luck if you target the "large" memory model,
|
---|
| 210 | but all the smaller models ("small", "compact" and "medium") are known
|
---|
| 211 | to be unworkable. For DOS users who have access beyond the lower 640K,
|
---|
| 212 | a "flat" 32-bit DOS model (such as DJGPP) is strongly recommended.
|
---|
[96425] | 213 |
|
---|
[103316] | 214 | For DOS users who only have access to the lower 640K, you will have to
|
---|
| 215 | limit zlib's memory usage via a png_set_compression_mem_level() call.
|
---|
| 216 | You will also have to look into zconf.h to tell zlib (and thus libpng)
|
---|
| 217 | that it cannot allocate more than 64K at a time. Even if you can, the
|
---|
| 218 | memory won't be accessible. Therefore, you should limit zlib and libpng
|
---|
| 219 | to 64K by defining MAXSEG_64K.
|
---|
[96425] | 220 |
|
---|
[103316] | 221 | IX. Prepending a prefix to exported symbols
|
---|
[96425] | 222 |
|
---|
| 223 | Starting with libpng-1.6.0, you can configure libpng (when using the
|
---|
| 224 | "configure" script) to prefix all exported symbols by means of the
|
---|
| 225 | configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
|
---|
| 226 | string beginning with a letter and containing only uppercase
|
---|
| 227 | and lowercase letters, digits, and the underscore (i.e., a C language
|
---|
| 228 | identifier). This creates a set of macros in pnglibconf.h, so this is
|
---|
| 229 | transparent to applications; their function calls get transformed by
|
---|
| 230 | the macros to use the modified names.
|
---|
| 231 |
|
---|
[103316] | 232 | X. Configuring for compiler xxx:
|
---|
[96425] | 233 |
|
---|
| 234 | All includes for libpng are in pngconf.h. If you need to add, change
|
---|
| 235 | or delete an include, this is the place to do it.
|
---|
| 236 | The includes that are not needed outside libpng are placed in pngpriv.h,
|
---|
| 237 | which is only used by the routines inside libpng itself.
|
---|
| 238 | The files in libpng proper only include pngpriv.h and png.h, which
|
---|
| 239 | in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
|
---|
| 240 | As of libpng-1.5.0, pngpriv.h also includes three other private header
|
---|
| 241 | files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
|
---|
| 242 | that previously appeared in the public headers.
|
---|
| 243 |
|
---|
[103316] | 244 | XI. Removing unwanted object code
|
---|
[96425] | 245 |
|
---|
| 246 | There are a bunch of #define's in pngconf.h that control what parts of
|
---|
| 247 | libpng are compiled. All the defines end in _SUPPORTED. If you are
|
---|
| 248 | never going to use a capability, you can change the #define to #undef
|
---|
| 249 | before recompiling libpng and save yourself code and data space, or
|
---|
| 250 | you can turn off individual capabilities with defines that begin with
|
---|
| 251 | "PNG_NO_".
|
---|
| 252 |
|
---|
| 253 | In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
|
---|
| 254 |
|
---|
| 255 | You can also turn all of the transforms and ancillary chunk capabilities
|
---|
| 256 | off en masse with compiler directives that define
|
---|
| 257 | PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
|
---|
| 258 | or all four, along with directives to turn on any of the capabilities that
|
---|
| 259 | you do want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the
|
---|
| 260 | extra transformations but still leave the library fully capable of reading
|
---|
| 261 | and writing PNG files with all known public chunks. Use of the
|
---|
| 262 | PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
|
---|
| 263 | that is incapable of reading or writing ancillary chunks. If you are
|
---|
| 264 | not using the progressive reading capability, you can turn that off
|
---|
| 265 | with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
|
---|
| 266 | capability, which you'll still have).
|
---|
| 267 |
|
---|
| 268 | All the reading and writing specific code are in separate files, so the
|
---|
| 269 | linker should only grab the files it needs. However, if you want to
|
---|
| 270 | make sure, or if you are building a stand alone library, all the
|
---|
| 271 | reading files start with "pngr" and all the writing files start with "pngw".
|
---|
| 272 | The files that don't match either (like png.c, pngtrans.c, etc.)
|
---|
| 273 | are used for both reading and writing, and always need to be included.
|
---|
| 274 | The progressive reader is in pngpread.c
|
---|
| 275 |
|
---|
| 276 | If you are creating or distributing a dynamically linked library (a .so
|
---|
| 277 | or DLL file), you should not remove or disable any parts of the library,
|
---|
| 278 | as this will cause applications linked with different versions of the
|
---|
| 279 | library to fail if they call functions not available in your library.
|
---|
| 280 | The size of the library itself should not be an issue, because only
|
---|
| 281 | those sections that are actually used will be loaded into memory.
|
---|
| 282 |
|
---|
[103316] | 283 | XII. Enabling or disabling hardware optimizations
|
---|
[96425] | 284 |
|
---|
| 285 | Certain hardware capabilities, such as the Intel SSE instructions,
|
---|
| 286 | are normally detected at run time. Enable them with configure options
|
---|
| 287 | such as one of
|
---|
| 288 |
|
---|
| 289 | --enable-arm-neon=yes
|
---|
| 290 | --enable-mips-msa=yes
|
---|
| 291 | --enable-intel-sse=yes
|
---|
| 292 | --enable-powerpc-vsx=yes
|
---|
| 293 |
|
---|
| 294 | or enable them all at once with
|
---|
| 295 |
|
---|
| 296 | --enable-hardware-optimizations=yes
|
---|
| 297 |
|
---|
| 298 | or, if you are not using "configure", you can use one
|
---|
| 299 | or more of
|
---|
| 300 |
|
---|
| 301 | CPPFLAGS += "-DPNG_ARM_NEON"
|
---|
| 302 | CPPFLAGS += "-DPNG_MIPS_MSA"
|
---|
| 303 | CPPFLAGS += "-DPNG_INTEL_SSE"
|
---|
| 304 | CPPFLAGS += "-DPNG_POWERPC_VSX"
|
---|
| 305 |
|
---|
| 306 | See for example scripts/makefile.linux-opt
|
---|
| 307 |
|
---|
| 308 | If you wish to avoid using them,
|
---|
| 309 | you can disable them via the configure option
|
---|
| 310 |
|
---|
| 311 | --disable-hardware-optimizations
|
---|
| 312 |
|
---|
| 313 | to disable them all, or
|
---|
| 314 |
|
---|
| 315 | --enable-intel-sse=no
|
---|
| 316 |
|
---|
| 317 | to disable a particular one,
|
---|
| 318 | or via compiler-command options such as
|
---|
| 319 |
|
---|
| 320 | CPPFLAGS += "-DPNG_ARM_NEON_OPT=0, -DPNG_MIPS_MSA_OPT=0,
|
---|
| 321 | -DPNG_INTEL_SSE_OPT=0, -DPNG_POWERPC_VSX_OPT=0"
|
---|
| 322 |
|
---|
| 323 | If you are using cmake, hardware optimizations are "on"
|
---|
| 324 | by default. To disable them, use
|
---|
| 325 |
|
---|
| 326 | cmake . -DPNG_ARM_NEON=no -DPNG_INTEL_SSE=no \
|
---|
| 327 | -DPNG_MIPS_MSA=no -DPNG_POWERPC_VSX=no
|
---|
| 328 |
|
---|
| 329 | or disable them all at once with
|
---|
| 330 |
|
---|
| 331 | cmake . -DPNG_HARDWARE_OPTIMIZATIONS=no
|
---|
| 332 |
|
---|
[103316] | 333 | XIII. Changes to the build and configuration of libpng in libpng-1.5.x
|
---|
[96425] | 334 |
|
---|
| 335 | Details of internal changes to the library code can be found in the CHANGES
|
---|
| 336 | file and in the GIT repository logs. These will be of no concern to the vast
|
---|
| 337 | majority of library users or builders; however, the few who configure libpng
|
---|
| 338 | to a non-default feature set may need to change how this is done.
|
---|
| 339 |
|
---|
| 340 | There should be no need for library builders to alter build scripts if
|
---|
| 341 | these use the distributed build support - configure or the makefiles -
|
---|
| 342 | however, users of the makefiles may care to update their build scripts
|
---|
| 343 | to build pnglibconf.h where the corresponding makefile does not do so.
|
---|
| 344 |
|
---|
| 345 | Building libpng with a non-default configuration has changed completely.
|
---|
| 346 | The old method using pngusr.h should still work correctly even though the
|
---|
| 347 | way pngusr.h is used in the build has been changed; however, library
|
---|
| 348 | builders will probably want to examine the changes to take advantage of
|
---|
| 349 | new capabilities and to simplify their build system.
|
---|
| 350 |
|
---|
| 351 | A. Specific changes to library configuration capabilities
|
---|
| 352 |
|
---|
| 353 | The exact mechanism used to control attributes of API functions has
|
---|
| 354 | changed. A single set of operating system independent macro definitions
|
---|
| 355 | is used and operating system specific directives are defined in
|
---|
| 356 | pnglibconf.h
|
---|
| 357 |
|
---|
| 358 | As part of this the mechanism used to choose procedure call standards on
|
---|
| 359 | those systems that allow a choice has been changed. At present this only
|
---|
| 360 | affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
|
---|
| 361 | running on Intel processors. As before, PNGAPI is defined where required
|
---|
| 362 | to control the exported API functions; however, two new macros, PNGCBAPI
|
---|
| 363 | and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
|
---|
| 364 | (PNGCAPI) for functions that must match a C library prototype (currently
|
---|
| 365 | only png_longjmp_ptr, which must match the C longjmp function.) The new
|
---|
| 366 | approach is documented in pngconf.h
|
---|
| 367 |
|
---|
| 368 | Despite these changes, libpng 1.5.0 only supports the native C function
|
---|
| 369 | calling standard on those platforms tested so far ("__cdecl" on Microsoft
|
---|
| 370 | Windows). This is because the support requirements for alternative
|
---|
| 371 | calling conventions seem to no longer exist. Developers who find it
|
---|
| 372 | necessary to set PNG_API_RULE to 1 should advise the mailing list
|
---|
| 373 | (png-mng-implement) of this and library builders who use Openwatcom and
|
---|
| 374 | therefore set PNG_API_RULE to 2 should also contact the mailing list.
|
---|
| 375 |
|
---|
| 376 | B. Changes to the configuration mechanism
|
---|
| 377 |
|
---|
| 378 | Prior to libpng-1.5.0 library builders who needed to configure libpng
|
---|
| 379 | had either to modify the exported pngconf.h header file to add system
|
---|
| 380 | specific configuration or had to write feature selection macros into
|
---|
| 381 | pngusr.h and cause this to be included into pngconf.h by defining
|
---|
| 382 | PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
|
---|
| 383 | application built without PNG_USER_CONFIG defined would see the
|
---|
| 384 | unmodified, default, libpng API and thus would probably fail to link.
|
---|
| 385 |
|
---|
| 386 | These mechanisms still work in the configure build and in any makefile
|
---|
| 387 | build that builds pnglibconf.h, although the feature selection macros
|
---|
| 388 | have changed somewhat as described above. In 1.5.0, however, pngusr.h is
|
---|
| 389 | processed only once, at the time the exported header file pnglibconf.h is
|
---|
| 390 | built. pngconf.h no longer includes pngusr.h; therefore, pngusr.h is ignored
|
---|
| 391 | after the build of pnglibconf.h and it is never included in an application
|
---|
| 392 | build.
|
---|
| 393 |
|
---|
| 394 | The formerly used alternative of adding a list of feature macros to the
|
---|
| 395 | CPPFLAGS setting in the build also still works; however, the macros will be
|
---|
| 396 | copied to pnglibconf.h and this may produce macro redefinition warnings
|
---|
| 397 | when the individual C files are compiled.
|
---|
| 398 |
|
---|
| 399 | All configuration now only works if pnglibconf.h is built from
|
---|
| 400 | scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan
|
---|
| 401 | (the original author of awk) maintains C source code of that awk and this
|
---|
| 402 | and all known later implementations (often called by subtly different
|
---|
| 403 | names - nawk and gawk for example) are adequate to build pnglibconf.h.
|
---|
| 404 | The Sun Microsystems (now Oracle) program 'awk' is an earlier version
|
---|
| 405 | and does not work; this may also apply to other systems that have a
|
---|
| 406 | functioning awk called 'nawk'.
|
---|
| 407 |
|
---|
| 408 | Configuration options are now documented in scripts/pnglibconf.dfa. This
|
---|
| 409 | file also includes dependency information that ensures a configuration is
|
---|
| 410 | consistent; that is, if a feature is switched off, dependent features are
|
---|
| 411 | also switched off. As a recommended alternative to using feature macros in
|
---|
| 412 | pngusr.h a system builder may also define equivalent options in pngusr.dfa
|
---|
| 413 | (or, indeed, any file) and add that to the configuration by setting
|
---|
| 414 | DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate
|
---|
| 415 | how to do this, and also illustrate a case where pngusr.h is still required.
|
---|
| 416 |
|
---|
| 417 | After you have built libpng, the definitions that were recorded in
|
---|
| 418 | pnglibconf.h are available to your application (pnglibconf.h is included
|
---|
| 419 | in png.h and gets installed alongside png.h and pngconf.h in your
|
---|
| 420 | $PREFIX/include directory). Do not edit pnglibconf.h after you have built
|
---|
| 421 | libpng, because than the settings would not accurately reflect the settings
|
---|
| 422 | that were used to build libpng.
|
---|
| 423 |
|
---|
[103316] | 424 | XIV. Setjmp/longjmp issues
|
---|
[96425] | 425 |
|
---|
| 426 | Libpng uses setjmp()/longjmp() for error handling. Unfortunately setjmp()
|
---|
| 427 | is known to be not thread-safe on some platforms and we don't know of
|
---|
| 428 | any platform where it is guaranteed to be thread-safe. Therefore, if
|
---|
| 429 | your application is going to be using multiple threads, you should
|
---|
| 430 | configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with
|
---|
| 431 | -DPNG_NO_SETJMP on your compile line, or with
|
---|
| 432 |
|
---|
| 433 | #undef PNG_SETJMP_SUPPORTED
|
---|
| 434 |
|
---|
| 435 | in your pnglibconf.h or pngusr.h.
|
---|
| 436 |
|
---|
| 437 | Starting with libpng-1.6.0, the library included a "simplified API".
|
---|
| 438 | This requires setjmp/longjmp, so you must either build the library
|
---|
| 439 | with PNG_SETJMP_SUPPORTED defined, or with PNG_SIMPLIFIED_READ_SUPPORTED
|
---|
| 440 | and PNG_SIMPLIFIED_WRITE_SUPPORTED undefined.
|
---|
| 441 |
|
---|
[103316] | 442 | XV. Common linking failures
|
---|
[96425] | 443 |
|
---|
| 444 | If your application fails to find libpng or zlib entries while linking:
|
---|
| 445 |
|
---|
| 446 | Be sure "-lz" appears after "-lpng" on your linking command.
|
---|
| 447 |
|
---|
| 448 | Be sure you have built libpng, zlib, and your application for the
|
---|
| 449 | same platform (e.g., 32-bit or 64-bit).
|
---|
| 450 |
|
---|
| 451 | If you are using the vstudio project, observe the WARNING in
|
---|
| 452 | project/vstudio/README.txt.
|
---|
| 453 |
|
---|
[103316] | 454 | XVI. Other sources of information about libpng:
|
---|
[96425] | 455 |
|
---|
| 456 | Further information can be found in the README and libpng-manual.txt
|
---|
| 457 | files, in the individual makefiles, in png.h, and the manual pages
|
---|
| 458 | libpng.3 and png.5.
|
---|
| 459 |
|
---|
[103316] | 460 | Copyright (c) 2022 Cosmin Truta
|
---|
[96425] | 461 | Copyright (c) 1998-2002,2006-2016 Glenn Randers-Pehrson
|
---|
| 462 | This document is released under the libpng license.
|
---|
| 463 | For conditions of distribution and use, see the disclaimer
|
---|
| 464 | and license in png.h.
|
---|