Debian Codegraph @

src/3rdparty/libpng/INSTALL

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