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