Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 1 | |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 2 | Installing libpng |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 3 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 4 | Contents |
| 5 | |
Glenn Randers-Pehrson | e175eb1 | 2016-08-18 12:15:53 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 24 | |
| 25 | I. Simple installation |
| 26 | |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 27 | On Unix/Linux and similar systems, you can simply type |
| 28 | |
Glenn Randers-Pehrson | 7edd458 | 2006-12-07 19:16:44 -0600 | [diff] [blame] | 29 | ./configure [--prefix=/path] |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 30 | make check |
| 31 | make install |
| 32 | |
Glenn Randers-Pehrson | 91319c6 | 2014-07-04 11:46:17 -0500 | [diff] [blame] | 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" |
Glenn Randers-Pehrson | 67152e7 | 2014-10-24 22:11:11 -0500 | [diff] [blame] | 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", |
Glenn Randers-Pehrson | 4aa3f40 | 2014-10-24 21:45:38 -0500 | [diff] [blame] | 44 | below. |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 45 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 46 | II. Rebuilding the configure scripts |
| 47 | |
Glenn Randers-Pehrson | 871b1d0 | 2013-03-02 14:58:22 -0600 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | e2d113c | 2016-02-23 09:29:08 -0600 | [diff] [blame] | 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: |
Glenn Randers-Pehrson | 6667601 | 2010-10-16 07:18:09 -0500 | [diff] [blame] | 55 | |
Glenn Randers-Pehrson | 6612114 | 2010-10-16 07:22:19 -0500 | [diff] [blame] | 56 | ./configure --enable-maintainer-mode |
Glenn Randers-Pehrson | 6667601 | 2010-10-16 07:18:09 -0500 | [diff] [blame] | 57 | make maintainer-clean |
Glenn Randers-Pehrson | 871b1d0 | 2013-03-02 14:58:22 -0600 | [diff] [blame] | 58 | ./autogen.sh --maintainer --clean |
| 59 | ./autogen.sh --maintainer |
Glenn Randers-Pehrson | 6612114 | 2010-10-16 07:22:19 -0500 | [diff] [blame] | 60 | ./configure [--prefix=/path] [other options] |
Glenn Randers-Pehrson | 6667601 | 2010-10-16 07:18:09 -0500 | [diff] [blame] | 61 | make |
| 62 | make install |
| 63 | make check |
Glenn Randers-Pehrson | 6bc53be | 2006-06-16 07:52:03 -0500 | [diff] [blame] | 64 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 65 | III. Using scripts/makefile* |
| 66 | |
Glenn Randers-Pehrson | 6bc53be | 2006-06-16 07:52:03 -0500 | [diff] [blame] | 67 | Instead, you can use one of the custom-built makefiles in the |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 68 | "scripts" directory |
| 69 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 70 | cp scripts/pnglibconf.h.prebuilt pnglibconf.h |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 71 | cp scripts/makefile.system makefile |
| 72 | make test |
| 73 | make install |
| 74 | |
Glenn Randers-Pehrson | 9d27a1b | 2009-11-15 07:59:06 -0600 | [diff] [blame] | 75 | The files that are presently available in the scripts directory |
| 76 | are listed and described in scripts/README.txt. |
| 77 | |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 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 |
Viktor Szakats | 95f3c07 | 2017-05-27 13:54:30 +0000 | [diff] [blame] | 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. |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 84 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 99 | |
| 100 | If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 101 | in your environment and type |
| 102 | |
| 103 | make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 104 | |
| 105 | IV. Using cmake |
| 106 | |
Glenn Randers-Pehrson | 5b754aa | 2009-08-26 12:16:18 -0500 | [diff] [blame] | 107 | If you want to use "cmake" (see www.cmake.org), type |
Glenn Randers-Pehrson | 7edd458 | 2006-12-07 19:16:44 -0600 | [diff] [blame] | 108 | |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 109 | cmake . -DCMAKE_INSTALL_PREFIX=/path |
| 110 | make |
| 111 | make install |
Glenn Randers-Pehrson | 7edd458 | 2006-12-07 19:16:44 -0600 | [diff] [blame] | 112 | |
Glenn Randers-Pehrson | 91319c6 | 2014-07-04 11:46:17 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 117 | V. Directory structure |
Glenn Randers-Pehrson | c2a15d0 | 2014-03-16 19:53:29 -0500 | [diff] [blame] | 118 | |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 119 | You can rename the directories that you downloaded (they |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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". |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 122 | |
| 123 | Your directory structure should look like this: |
| 124 | |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 125 | .. (the parent directory) |
Glenn Randers-Pehrson | d9940f6 | 2016-07-08 08:43:30 -0500 | [diff] [blame] | 126 | libpng (this directory) |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 127 | INSTALL (this file) |
| 128 | README |
Glenn Randers-Pehrson | 67152e7 | 2014-10-24 22:11:11 -0500 | [diff] [blame] | 129 | *.h, *.c => libpng source files |
Glenn Randers-Pehrson | be199c1 | 2009-11-12 13:57:42 -0600 | [diff] [blame] | 130 | CMakeLists.txt => "cmake" script |
Glenn Randers-Pehrson | 22ad8f0 | 2009-11-14 07:25:31 -0600 | [diff] [blame] | 131 | configuration files: |
| 132 | configure.ac, configure, Makefile.am, Makefile.in, |
Glenn Randers-Pehrson | 39515c9 | 2010-08-28 06:21:35 -0500 | [diff] [blame] | 133 | autogen.sh, config.guess, ltmain.sh, missing, libpng.pc.in, |
| 134 | libpng-config.in, aclocal.m4, config.h.in, config.sub, |
Glenn Randers-Pehrson | 22ad8f0 | 2009-11-14 07:25:31 -0600 | [diff] [blame] | 135 | depcomp, install-sh, mkinstalldirs, test-pngtest.sh |
Glenn Randers-Pehrson | 860ab2b | 1999-10-14 07:43:10 -0500 | [diff] [blame] | 136 | contrib |
Glenn Randers-Pehrson | 4aa3f40 | 2014-10-24 21:45:38 -0500 | [diff] [blame] | 137 | arm-neon, conftest, examples, gregbook, libtests, pngminim, |
| 138 | pngminus, pngsuite, tools, visupng |
Glenn Randers-Pehrson | fbbb5ec | 2001-01-15 22:01:20 -0600 | [diff] [blame] | 139 | projects |
Glenn Randers-Pehrson | 67152e7 | 2014-10-24 22:11:11 -0500 | [diff] [blame] | 140 | cbuilder5, owatcom, visualc71, vstudio, xcode |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 141 | scripts |
| 142 | makefile.* |
Glenn Randers-Pehrson | be199c1 | 2009-11-12 13:57:42 -0600 | [diff] [blame] | 143 | *.def (module definition files) |
Glenn Randers-Pehrson | 8c66786 | 2010-08-24 16:16:35 -0500 | [diff] [blame] | 144 | etc. |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 145 | pngtest.png |
| 146 | etc. |
| 147 | zlib |
Glenn Randers-Pehrson | 67152e7 | 2014-10-24 22:11:11 -0500 | [diff] [blame] | 148 | README, *.h, *.c contrib, etc. |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 149 | |
Glenn Randers-Pehrson | 61c32d9 | 2000-02-04 23:40:16 -0600 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 154 | VI. Building with project files |
| 155 | |
Glenn Randers-Pehrson | 9c3ab68 | 2006-02-20 22:09:05 -0600 | [diff] [blame] | 156 | If you are building libpng with MSVC, you can enter the |
Glenn Randers-Pehrson | 67152e7 | 2014-10-24 22:11:11 -0500 | [diff] [blame] | 157 | libpng projects\visualc71 or vstudio directory and follow the instructions |
Glenn Randers-Pehrson | be199c1 | 2009-11-12 13:57:42 -0600 | [diff] [blame] | 158 | in README.txt. |
Glenn Randers-Pehrson | d436672 | 2000-06-04 14:29:29 -0500 | [diff] [blame] | 159 | |
Glenn Randers-Pehrson | a2aebb5 | 2009-11-14 17:58:32 -0600 | [diff] [blame] | 160 | Otherwise enter the zlib directory and follow the instructions in zlib/README, |
Glenn Randers-Pehrson | ddfebd3 | 2006-02-22 09:19:25 -0600 | [diff] [blame] | 161 | then come back here and run "configure" or choose the appropriate |
| 162 | makefile.sys in the scripts directory. |
Glenn Randers-Pehrson | db66d44 | 2000-06-23 21:38:16 -0500 | [diff] [blame] | 163 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 164 | VII. Building with makefiles |
| 165 | |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 166 | Copy the file (or files) that you need from the |
| 167 | scripts directory into this directory, for example |
| 168 | |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 178 | |
| 179 | Read the makefile to see if you need to change any source or |
| 180 | target directories to match your preferences. |
| 181 | |
Glenn Randers-Pehrson | 10973a5 | 2010-10-16 19:40:09 -0500 | [diff] [blame] | 182 | Then read pnglibconf.dfa to see if you want to make any configuration |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 183 | changes. |
| 184 | |
Glenn Randers-Pehrson | 9c3ab68 | 2006-02-20 22:09:05 -0600 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 6d8f3b0 | 1999-10-23 08:39:18 -0500 | [diff] [blame] | 192 | your output with the result shown in contrib/pngsuite/README. |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 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). |
Glenn Randers-Pehrson | d1e8c86 | 2002-06-20 06:54:34 -0500 | [diff] [blame] | 197 | Some also allow you to run "make test-installed" after you have |
Glenn Randers-Pehrson | 0cc2f95 | 2002-10-03 06:32:37 -0500 | [diff] [blame] | 198 | run "make install". |
Glenn Randers-Pehrson | 08a3343 | 1998-03-07 06:06:55 -0600 | [diff] [blame] | 199 | |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | bc27b2f | 2015-03-09 09:11:00 -0500 | [diff] [blame] | 203 | it cannot allocate more than 64K at a time. Even if you can, the memory |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | e175eb1 | 2016-08-18 12:15:53 -0500 | [diff] [blame] | 253 | "PNG_NO_". |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 285 | XIV. Enabling or disabling hardware optimizations |
| 286 | |
| 287 | Certain hardware capabilites, such as the Intel SSE instructions, |
Glenn Randers-Pehrson | 857ef82 | 2017-07-06 20:17:09 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | 50b6df5 | 2017-07-08 12:59:23 -0500 | [diff] [blame] | 296 | or enable them all at once with |
| 297 | |
| 298 | --enable-hardware-optimizations=yes |
| 299 | |
Glenn Randers-Pehrson | ecea632 | 2017-07-09 19:35:10 -0500 | [diff] [blame] | 300 | or, if you are not using "configure", you can use one |
| 301 | or more of |
Glenn Randers-Pehrson | 857ef82 | 2017-07-06 20:17:09 -0500 | [diff] [blame] | 302 | |
| 303 | CPPFLAGS += "-DPNG_ARM_NEON" |
| 304 | CPPFLAGS += "-DPNG_MIPS_MSA" |
| 305 | CPPFLAGS += "-DPNG_INTEL_SSE" |
| 306 | CPPFLAGS += "-DPNG_POWERPC_VSX" |
| 307 | |
Glenn Randers-Pehrson | ecea632 | 2017-07-09 19:35:10 -0500 | [diff] [blame] | 308 | See for example scripts/makefile.linux-opt |
| 309 | |
Glenn Randers-Pehrson | 857ef82 | 2017-07-06 20:17:09 -0500 | [diff] [blame] | 310 | If you wish to avoid using them, |
Glenn Randers-Pehrson | 50b6df5 | 2017-07-08 12:59:23 -0500 | [diff] [blame] | 311 | you can disable them via the configure option |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 312 | |
Glenn Randers-Pehrson | 50b6df5 | 2017-07-08 12:59:23 -0500 | [diff] [blame] | 313 | --disable-hardware-optimizations |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 314 | |
Glenn Randers-Pehrson | 50b6df5 | 2017-07-08 12:59:23 -0500 | [diff] [blame] | 315 | to disable them all, or |
| 316 | |
| 317 | --enable-intel-sse=no |
| 318 | |
| 319 | to disable a particular one, |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | 2b80b40 | 2017-07-08 19:25:08 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 335 | XV. Changes to the build and configuration of libpng in libpng-1.5.x |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | e175eb1 | 2016-08-18 12:15:53 -0500 | [diff] [blame] | 371 | calling standard on those platforms tested so far ("__cdecl" on Microsoft |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 91319c6 | 2014-07-04 11:46:17 -0500 | [diff] [blame] | 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. |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 395 | |
Glenn Randers-Pehrson | 44bda93 | 2014-09-18 09:25:50 -0500 | [diff] [blame] | 396 | The formerly used alternative of adding a list of feature macros to the |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 44bda93 | 2014-09-18 09:25:50 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 |
Glenn Randers-Pehrson | 44bda93 | 2014-09-18 09:25:50 -0500 | [diff] [blame] | 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. |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 425 | |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 426 | XVI. Setjmp/longjmp issues |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 435 | #undef PNG_SETJMP_SUPPORTED |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 436 | |
| 437 | in your pnglibconf.h or pngusr.h. |
| 438 | |
Glenn Randers-Pehrson | d375ca5 | 2015-02-21 12:29:36 -0600 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 444 | XVII. Common linking failures |
Glenn Randers-Pehrson | 11c8803 | 2016-07-02 14:29:29 -0500 | [diff] [blame] | 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 | |
Glenn Randers-Pehrson | f380ae5 | 2017-07-05 19:20:57 -0500 | [diff] [blame] | 456 | XVIII. Other sources of information about libpng: |
Glenn Randers-Pehrson | 372cad0 | 2014-03-21 13:26:43 -0500 | [diff] [blame] | 457 | |
Glenn Randers-Pehrson | f3abb2c | 2010-10-17 12:51:53 -0500 | [diff] [blame] | 458 | Further information can be found in the README and libpng-manual.txt |
Glenn Randers-Pehrson | 9c3ab68 | 2006-02-20 22:09:05 -0600 | [diff] [blame] | 459 | files, in the individual makefiles, in png.h, and the manual pages |
| 460 | libpng.3 and png.5. |
Glenn Randers-Pehrson | 9cab7a2 | 2016-08-17 06:39:26 -0500 | [diff] [blame] | 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. |