[libpng16] Mention scripts/pnglibconf.h.prebuilt in INSTALL.
This commit is contained in:
Glenn Randers-Pehrson
parent
d74d82137b
commit
010222c55d
241
INSTALL
241
INSTALL
@ -1,27 +1,6 @@
|
||||
|
||||
Installing libpng
|
||||
|
||||
Contents
|
||||
|
||||
I. Simple installation
|
||||
II. Rebuilding the configure scripts
|
||||
III. Using scripts/makefile*
|
||||
IV. Using cmake
|
||||
V. Directory structure
|
||||
VI. Building with project files
|
||||
VII. Building with makefiles
|
||||
VIII. Configuring libpng for 16-bit platforms
|
||||
IX. Configuring for DOS
|
||||
X. Configuring for Medium Model
|
||||
XI. Prepending a prefix to exported symbols
|
||||
XII. Configuring for compiler xxx:
|
||||
XIII. Removing unwanted object code
|
||||
XIV. Changes to the build and configuration of libpng in libpng-1.5.x
|
||||
XV. Configuring libpng for multiprocessing
|
||||
XVI. Other sources of information about libpng:
|
||||
|
||||
I. Simple installation
|
||||
|
||||
On Unix/Linux and similar systems, you can simply type
|
||||
|
||||
./configure [--prefix=/path]
|
||||
@ -30,8 +9,6 @@ On Unix/Linux and similar systems, you can simply type
|
||||
|
||||
and ignore the rest of this document.
|
||||
|
||||
II. Rebuilding the configure scripts
|
||||
|
||||
If configure does not work on your system, or if you have a need to
|
||||
change configure.ac or Makefile.am, and you have a reasonably
|
||||
up-to-date set of tools, running ./autogen.sh in a git clone before
|
||||
@ -47,8 +24,6 @@ aren't using any of the included pre-built scripts, you can do this:
|
||||
make install
|
||||
make check
|
||||
|
||||
III. Using scripts/makefile*
|
||||
|
||||
Instead, you can use one of the custom-built makefiles in the
|
||||
"scripts" directory
|
||||
|
||||
@ -66,37 +41,19 @@ is not already on your system. zlib can usually be found
|
||||
wherever you got libpng. zlib can be placed in another directory,
|
||||
at the same level as libpng.
|
||||
|
||||
If your system already has a preinstalled zlib you will still need
|
||||
to have access to the zlib.h and zconf.h include files that
|
||||
correspond to the version of zlib that's installed.
|
||||
|
||||
If you wish to test with a particular zlib that is not first in the
|
||||
standard library search path, put ZLIBLIB, ZLIBINC, CPPFLAGS, LDFLAGS,
|
||||
and LD_LIBRARY_PATH in your environment before running "make test"
|
||||
or "make distcheck":
|
||||
|
||||
ZLIBLIB=/path/to/lib export ZLIBLIB
|
||||
ZLIBINC=/path/to/include export ZLIBINC
|
||||
CPPFLAGS="-I$ZLIBINC" export CPPFLAGS
|
||||
LDFLAGS="-L$ZLIBLIB" export LDFLAGS
|
||||
LD_LIBRARY_PATH="$ZLIBLIB:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH
|
||||
|
||||
If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC
|
||||
in your environment and type "make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test".
|
||||
|
||||
IV. Using cmake
|
||||
|
||||
If you want to use "cmake" (see www.cmake.org), type
|
||||
|
||||
cmake . -DCMAKE_INSTALL_PREFIX=/path
|
||||
make
|
||||
make install
|
||||
|
||||
V. Directory structure
|
||||
If your system already has a preinstalled zlib you will still need
|
||||
to have access to the zlib.h and zconf.h include files that
|
||||
correspond to the version of zlib that's installed.
|
||||
|
||||
You can rename the directories that you downloaded (they
|
||||
might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.8"
|
||||
or "zlib128") so that you have directories called "zlib" and "libpng".
|
||||
might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.5"
|
||||
or "zlib125") so that you have directories called "zlib" and "libpng".
|
||||
|
||||
Your directory structure should look like this:
|
||||
|
||||
@ -114,7 +71,6 @@ Your directory structure should look like this:
|
||||
depcomp, install-sh, mkinstalldirs, test-pngtest.sh
|
||||
contrib
|
||||
gregbook
|
||||
libtests
|
||||
pngminim
|
||||
pngminus
|
||||
pngsuite
|
||||
@ -139,8 +95,6 @@ If the line endings in the files look funny, you may wish to get the other
|
||||
distribution of libpng. It is available in both tar.gz (UNIX style line
|
||||
endings) and zip (DOS style line endings) formats.
|
||||
|
||||
VI. Building with project files
|
||||
|
||||
If you are building libpng with MSVC, you can enter the
|
||||
libpng projects\visualc6 or visualc71 directory and follow the instructions
|
||||
in README.txt.
|
||||
@ -149,8 +103,6 @@ Otherwise enter the zlib directory and follow the instructions in zlib/README,
|
||||
then come back here and run "configure" or choose the appropriate
|
||||
makefile.sys in the scripts directory.
|
||||
|
||||
VII. Building with makefiles
|
||||
|
||||
Copy the file (or files) that you need from the
|
||||
scripts directory into this directory, for example
|
||||
|
||||
@ -178,189 +130,6 @@ do that, run "make install" in the zlib directory first if necessary).
|
||||
Some also allow you to run "make test-installed" after you have
|
||||
run "make install".
|
||||
|
||||
VIII. Configuring libpng for 16-bit platforms
|
||||
|
||||
You will want to look into zconf.h to tell zlib (and thus libpng) that
|
||||
it cannot allocate more then 64K at a time. Even if you can, the memory
|
||||
won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
|
||||
|
||||
IX. Configuring for DOS
|
||||
|
||||
For DOS users who only have access to the lower 640K, you will
|
||||
have to limit zlib's memory usage via a png_set_compression_mem_level()
|
||||
call. See zlib.h or zconf.h in the zlib library for more information.
|
||||
|
||||
X. Configuring for Medium Model
|
||||
|
||||
Libpng's support for medium model has been tested on most of the popular
|
||||
compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
|
||||
defined, and FAR gets defined to far in pngconf.h, and you should be
|
||||
all set. Everything in the library (except for zlib's structure) is
|
||||
expecting far data. You must use the typedefs with the p or pp on
|
||||
the end for pointers (or at least look at them and be careful). Make
|
||||
note that the rows of data are defined as png_bytepp, which is
|
||||
an "unsigned char far * far *".
|
||||
|
||||
XI. Prepending a prefix to exported symbols
|
||||
|
||||
Starting with libpng-1.6.0, you can configure libpng (when using the
|
||||
"configure" script) to prefix all exported symbols by means of the
|
||||
configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
|
||||
string beginning with a letter and containing only uppercase
|
||||
and lowercase letters, digits, and the underscore (i.e., a C language
|
||||
identifier). This creates a set of macros in pnglibconf.h, so this is
|
||||
transparent to applications; their function calls get transformed by
|
||||
the macros to use the modified names.
|
||||
|
||||
XII. Configuring for compiler xxx:
|
||||
|
||||
All includes for libpng are in pngconf.h. If you need to add, change
|
||||
or delete an include, this is the place to do it.
|
||||
The includes that are not needed outside libpng are placed in pngpriv.h,
|
||||
which is only used by the routines inside libpng itself.
|
||||
The files in libpng proper only include pngpriv.h and png.h, which
|
||||
in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
|
||||
As of libpng-1.5.0, pngpriv.h also includes three other private header
|
||||
files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
|
||||
that previously appeared in the public headers.
|
||||
|
||||
XIII. Removing unwanted object code
|
||||
|
||||
There are a bunch of #define's in pngconf.h that control what parts of
|
||||
libpng are compiled. All the defines end in _SUPPORTED. If you are
|
||||
never going to use a capability, you can change the #define to #undef
|
||||
before recompiling libpng and save yourself code and data space, or
|
||||
you can turn off individual capabilities with defines that begin with
|
||||
PNG_NO_.
|
||||
|
||||
In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
|
||||
|
||||
You can also turn all of the transforms and ancillary chunk capabilities
|
||||
off en masse with compiler directives that define
|
||||
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
|
||||
or all four, along with directives to turn on any of the capabilities that
|
||||
you do want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the
|
||||
extra transformations but still leave the library fully capable of reading
|
||||
and writing PNG files with all known public chunks. Use of the
|
||||
PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
|
||||
that is incapable of reading or writing ancillary chunks. If you are
|
||||
not using the progressive reading capability, you can turn that off
|
||||
with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
|
||||
capability, which you'll still have).
|
||||
|
||||
All the reading and writing specific code are in separate files, so the
|
||||
linker should only grab the files it needs. However, if you want to
|
||||
make sure, or if you are building a stand alone library, all the
|
||||
reading files start with "pngr" and all the writing files start with "pngw".
|
||||
The files that don't match either (like png.c, pngtrans.c, etc.)
|
||||
are used for both reading and writing, and always need to be included.
|
||||
The progressive reader is in pngpread.c
|
||||
|
||||
If you are creating or distributing a dynamically linked library (a .so
|
||||
or DLL file), you should not remove or disable any parts of the library,
|
||||
as this will cause applications linked with different versions of the
|
||||
library to fail if they call functions not available in your library.
|
||||
The size of the library itself should not be an issue, because only
|
||||
those sections that are actually used will be loaded into memory.
|
||||
|
||||
XIV. Changes to the build and configuration of libpng in libpng-1.5.x
|
||||
|
||||
Details of internal changes to the library code can be found in the CHANGES
|
||||
file and in the GIT repository logs. These will be of no concern to the vast
|
||||
majority of library users or builders; however, the few who configure libpng
|
||||
to a non-default feature set may need to change how this is done.
|
||||
|
||||
There should be no need for library builders to alter build scripts if
|
||||
these use the distributed build support - configure or the makefiles -
|
||||
however, users of the makefiles may care to update their build scripts
|
||||
to build pnglibconf.h where the corresponding makefile does not do so.
|
||||
|
||||
Building libpng with a non-default configuration has changed completely.
|
||||
The old method using pngusr.h should still work correctly even though the
|
||||
way pngusr.h is used in the build has been changed; however, library
|
||||
builders will probably want to examine the changes to take advantage of
|
||||
new capabilities and to simplify their build system.
|
||||
|
||||
A. Specific changes to library configuration capabilities
|
||||
|
||||
The exact mechanism used to control attributes of API functions has
|
||||
changed. A single set of operating system independent macro definitions
|
||||
is used and operating system specific directives are defined in
|
||||
pnglibconf.h
|
||||
|
||||
As part of this the mechanism used to choose procedure call standards on
|
||||
those systems that allow a choice has been changed. At present this only
|
||||
affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
|
||||
running on Intel processors. As before, PNGAPI is defined where required
|
||||
to control the exported API functions; however, two new macros, PNGCBAPI
|
||||
and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
|
||||
(PNGCAPI) for functions that must match a C library prototype (currently
|
||||
only png_longjmp_ptr, which must match the C longjmp function.) The new
|
||||
approach is documented in pngconf.h
|
||||
|
||||
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, when 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 rarely 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 removed. 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 a case where pngusr.h is still required.
|
||||
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user