INSTALL 19 KB

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