view release on metacpan or  search on metacpan

src/Source/LibPNG/INSTALL  view on Meta::CPAN

Despite these changes, libpng 1.5.0 only supports the native C function
calling standard on those platforms tested so far (__cdecl on Microsoft
Windows).  This is because the support requirements for alternative
calling conventions seem to no longer exist.  Developers who find it
necessary to set PNG_API_RULE to 1 should advise the mailing list
(png-mng-implement) of this and library builders who use Openwatcom and
therefore set PNG_API_RULE to 2 should also contact the mailing list.

B. Changes to the configuration mechanism

Prior to libpng-1.5.0 library builders who needed to configure libpng
had either to modify the exported pngconf.h header file to add system
specific configuration or had to write feature selection macros into
pngusr.h and cause this to be included into pngconf.h by defining
PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
application built without PNG_USER_CONFIG defined would see the
unmodified, default, libpng API and thus would probably fail to link.

These mechanisms still work in the configure build and in any makefile
build that builds pnglibconf.h, although the feature selection macros
have changed somewhat as described above.  In 1.5.0, however, pngusr.h is
processed only once, at the time the exported header file pnglibconf.h is
built.  pngconf.h no longer includes pngusr.h; therefore, pngusr.h is ignored
after the build of pnglibconf.h and it is never included in an application
build.

The formerly used alternative of adding a list of feature macros to the
CPPFLAGS setting in the build also still works; however, the macros will be
copied to pnglibconf.h and this may produce macro redefinition warnings
when the individual C files are compiled.

All configuration now only works if pnglibconf.h is built from
scripts/pnglibconf.dfa.  This requires the program awk.  Brian Kernighan
(the original author of awk) maintains C source code of that awk and this
and all known later implementations (often called by subtly different
names - nawk and gawk for example) are adequate to build pnglibconf.h.
The Sun Microsystems (now Oracle) program 'awk' is an earlier version
and does not work; this may also apply to other systems that have a
functioning awk called 'nawk'.

Configuration options are now documented in scripts/pnglibconf.dfa.  This
file also includes dependency information that ensures a configuration is
consistent; that is, if a feature is switched off, dependent features are
also switched off.  As a recommended alternative to using feature macros in
pngusr.h a system builder may also define equivalent options in pngusr.dfa
(or, indeed, any file) and add that to the configuration by setting
DFA_XTRA to the file name.  The makefiles in contrib/pngminim illustrate
how to do this, and also illustrate a case where pngusr.h is still required.

After you have built libpng, the definitions that were recorded in
pnglibconf.h are available to your application (pnglibconf.h is included
in png.h and gets installed alongside png.h and pngconf.h in your
$PREFIX/include directory).  Do not edit pnglibconf.h after you have built
libpng, because than the settings would not accurately reflect the settings
that were used to build libpng.

XV. Configuring libpng for multiprocessing

Libpng uses setjmp()/longjmp() for error handling.  Unfortunately setjmp()
is known to be not thread-safe on some platforms and we don't know of
any platform where it is guaranteed to be thread-safe.  Therefore, if
your application is going to be using multiple threads, you should
configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with
-DPNG_NO_SETJMP on your compile line, or with

  #undef PNG_SETJMP_SUPPORTED

in your pnglibconf.h or pngusr.h.

XVI. Other sources of information about libpng:

Further information can be found in the README and libpng-manual.txt
files, in the individual makefiles, in png.h, and the manual pages
libpng.3 and png.5.