VirtualBox

source: vbox/trunk/src/libs/libpng-1.6.43/INSTALL

Last change on this file was 103316, checked in by vboxsync, 9 months ago

libpng-1.6.42: Applied and adjusted our libpng changes to 1.6.42. bugref:8515

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette