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