[wxWidgets.git] / src / png / projects / vstudio / readme.txt


VisualStudio instructions

libpng version 1.4.4 - September 23, 2010

Copyright (c) 1998-2010 Glenn Randers-Pehrson

This code is released under the libpng license.
For conditions of distribution and use, see the disclaimer
and license in png.h

This directory  contains support for building libpng under MicroSoft
VisualStudio 2010.  It may also work under later versions of VisualStudio.
You should be familiar with VisualStudio before using this directory.

This is a slightly modified copy of the 'vstudio' solution from libpng
1.5; it is intended to provide compatibility for libpng 1.4 with later
releases of zlib (from 1.2.4) and to provide a migration aid for 1.5.

A 'VB' DLL is no longer produced - use the standard 'Release' DLL.

Initial preparations
====================
You should install the 'official' build of zlib on your system - follow the
instructions provided on http://www.zlib.net.  When a new release is being
made of zlib the instructions disappear for a while until the new official
build is available.  You will have to wait.

You must enter some information in zlib.props before attempting to build
with this 'solution'.  Please read and edit zlib.props first.  You will
probably not be familiar with the contents of zlib.props - do not worry,
it is mostly harmless.

Make sure that your official build layout matches the requirements listed
in zlib.props.  Prior to zlib-1.2.4 the official build (1.2.3) placed
include and library files in different directories - if you find this
has happened just put them all in the same directory.

This is all you need to do to build the 'release' and 'release library'
configurations.

Debugging
=========
The release configurations default to /Ox optimization.  Full debugging
information is produced (in the .pdb), but if you encounter a problem the
optimization may make it difficult to debug.  Simply rebuild with a lower
optimization level (e.g. /Od.)

Stop reading here
=================
You have enough information to build a working application.

Debug versions have limited support
===================================
This solution includes limited support for debug versions of libpng.  You
do not need these unless your own solution itself uses debug builds (it is
far more effective to debug on the release builds, there is no point building
a special debug build.)

If, despite the previous paragraph, you still feel you need a debug build you
will have to download the zlib source as well (http://www.zlib.net) and include
the directory where you unpack it in zlib.props.  This solution will then be
able to build a minimal zlib sufficient for libpng.  This build is only
suitable for making a debug libpng.

The debug build of libpng is minimally supported.  Support for debug builds of
zlib is also minimal.  You really don't want to do this.

This solution only supports the Multi-Threaded DLL C Runtime
============================================================
If you examine the solution you will find that it very deliberately lists
exactly which MicroSoft DLLs it is linking against.  It explicitly links
against msvcrt.lib.  The debug version links against msvcrtd.lib (this is
why it is a debug version - it's nothing to do with having any special
debug support, it doesn't).

These versions of the MicroSoft C runtime correspond to the compiler flags
/MD (release) and /MDd (debug) - the "Multi-Threaded DLL" implementation of the
C runtime library.

If you need to change this then you will have to make sure that both the
compiler flags and the ".lib" in the linker dependences match up.  Fortunately
neither zlib nor libpng require libraries other than a C runtime and
kernel32.

You cannot pass (FILE*) objects from a different runtime (including msvcrtd
to msvcrt) to libpng.  If you do then your program will crash within libpng
when it first makes a file read or write call.

It is likely if you have read this far that you have found you can't avoid
having multiple C runtimes in your program.  This is OK, it does work, but
you will have to implement the libpng file read/write callbacks rather than
using the internal libpng default.  This is easy.
Commit	Line	Data
b61cc19c PC	1
	2	VisualStudio instructions
	3
	4	libpng version 1.4.4 - September 23, 2010
	5
	6	Copyright (c) 1998-2010 Glenn Randers-Pehrson
	7
	8	This code is released under the libpng license.
	9	For conditions of distribution and use, see the disclaimer
	10	and license in png.h
	11
	12	This directory contains support for building libpng under MicroSoft
	13	VisualStudio 2010. It may also work under later versions of VisualStudio.
	14	You should be familiar with VisualStudio before using this directory.
	15
	16	This is a slightly modified copy of the 'vstudio' solution from libpng
	17	1.5; it is intended to provide compatibility for libpng 1.4 with later
	18	releases of zlib (from 1.2.4) and to provide a migration aid for 1.5.
	19
	20	A 'VB' DLL is no longer produced - use the standard 'Release' DLL.
	21
	22	Initial preparations
	23	====================
	24	You should install the 'official' build of zlib on your system - follow the
	25	instructions provided on http://www.zlib.net. When a new release is being
	26	made of zlib the instructions disappear for a while until the new official
	27	build is available. You will have to wait.
	28
	29	You must enter some information in zlib.props before attempting to build
	30	with this 'solution'. Please read and edit zlib.props first. You will
	31	probably not be familiar with the contents of zlib.props - do not worry,
	32	it is mostly harmless.
	33
	34	Make sure that your official build layout matches the requirements listed
	35	in zlib.props. Prior to zlib-1.2.4 the official build (1.2.3) placed
	36	include and library files in different directories - if you find this
	37	has happened just put them all in the same directory.
	38
	39	This is all you need to do to build the 'release' and 'release library'
	40	configurations.
	41
	42	Debugging
	43	=========
	44	The release configurations default to /Ox optimization. Full debugging
	45	information is produced (in the .pdb), but if you encounter a problem the
	46	optimization may make it difficult to debug. Simply rebuild with a lower
	47	optimization level (e.g. /Od.)
	48
	49	Stop reading here
	50	=================
	51	You have enough information to build a working application.
	52
	53	Debug versions have limited support
	54	===================================
	55	This solution includes limited support for debug versions of libpng. You
	56	do not need these unless your own solution itself uses debug builds (it is
	57	far more effective to debug on the release builds, there is no point building
	58	a special debug build.)
	59
	60	If, despite the previous paragraph, you still feel you need a debug build you
	61	will have to download the zlib source as well (http://www.zlib.net) and include
	62	the directory where you unpack it in zlib.props. This solution will then be
	63	able to build a minimal zlib sufficient for libpng. This build is only
	64	suitable for making a debug libpng.
65
66	The debug build of libpng is minimally supported. Support for debug builds of
67	zlib is also minimal. You really don't want to do this.
68
69	This solution only supports the Multi-Threaded DLL C Runtime
70	============================================================
71	If you examine the solution you will find that it very deliberately lists
72	exactly which MicroSoft DLLs it is linking against. It explicitly links
73	against msvcrt.lib. The debug version links against msvcrtd.lib (this is
74	why it is a debug version - it's nothing to do with having any special
75	debug support, it doesn't).
76
77	These versions of the MicroSoft C runtime correspond to the compiler flags
78	/MD (release) and /MDd (debug) - the "Multi-Threaded DLL" implementation of the
79	C runtime library.
80
81	If you need to change this then you will have to make sure that both the
82	compiler flags and the ".lib" in the linker dependences match up. Fortunately
83	neither zlib nor libpng require libraries other than a C runtime and
84	kernel32.
85
86	You cannot pass (FILE*) objects from a different runtime (including msvcrtd
87	to msvcrt) to libpng. If you do then your program will crash within libpng
88	when it first makes a file read or write call.
89
90	It is likely if you have read this far that you have found you can't avoid
91	having multiple C runtimes in your program. This is OK, it does work, but
92	you will have to implement the libpng file read/write callbacks rather than
93	using the internal libpng default. This is easy.