This commit was generated by cvs2svn to compensate for changes in r36, which
[alioth/cvs.git] / zlib / win32 / DLL_FAQ.txt
1
2             Frequently Asked Questions about ZLIB1.DLL
3
4
5 This document describes the design, the rationale, and the usage
6 of the official DLL build of zlib, named ZLIB1.DLL.  If you have
7 general questions about zlib, you should see the file "FAQ" found
8 in the zlib distribution, or at the following location:
9   http://www.gzip.org/zlib/zlib_faq.html
10
11
12  1. What is ZLIB1.DLL, and how can I get it?
13
14   - ZLIB1.DLL is the official build of zlib as a DLL.
15     (Please remark the character '1' in the name.)
16
17     Pointers to a precompiled ZLIB1.DLL can be found in the zlib
18     web site at:
19       http://www.zlib.org/
20
21     Applications that link to ZLIB1.DLL can rely on the following
22     specification:
23
24     * The exported symbols are exclusively defined in the source
25       files "zlib.h" and "zlib.def", found in an official zlib
26       source distribution.
27     * The symbols are exported by name, not by ordinal.
28     * The exported names are undecorated.
29     * The calling convention of functions is "C" (CDECL).
30     * The ZLIB1.DLL binary is linked to MSVCRT.DLL.
31
32     The archive in which ZLIB1.DLL is bundled contains compiled
33     test programs that must run with a valid build of ZLIB1.DLL.
34     It is recommended to download the prebuilt DLL from the zlib
35     web site, instead of building it yourself, to avoid potential
36     incompatibilities that could be introduced by your compiler
37     and build settings.  If you do build the DLL yourself, please
38     make sure that it complies with all the above requirements,
39     and it runs with the precompiled test programs, bundled with
40     the original ZLIB1.DLL distribution.
41
42     If, for any reason, you need to build an incompatible DLL,
43     please use a different file name.
44
45
46  2. Why did you change the name of the DLL to ZLIB1.DLL?
47     What happened to the old ZLIB.DLL?
48
49   - The old ZLIB.DLL, built from zlib-1.1.4 or earlier, required
50     compilation settings that were incompatible to those used by
51     a static build.  The DLL settings were supposed to be enabled
52     by defining the macro ZLIB_DLL, before including "zlib.h".
53     Incorrect handling of this macro was silently accepted at
54     build time, resulting in two major problems:
55
56     * ZLIB_DLL was missing from the old makefile.  When building
57       the DLL, not all people added it to the build options.  In
58       consequence, incompatible incarnations of ZLIB.DLL started
59       to circulate around the net.
60
61     * When switching from using the static library to using the
62       DLL, applications had to define the ZLIB_DLL macro and
63       to recompile all the sources that contained calls to zlib
64       functions.  Failure to do so resulted in creating binaries
65       that were unable to run with the official ZLIB.DLL build.
66
67     The only possible solution that we could foresee was to make
68     a binary-incompatible change in the DLL interface, in order to
69     remove the dependency on the ZLIB_DLL macro, and to release
70     the new DLL under a different name.
71
72     We chose the name ZLIB1.DLL, where '1' indicates the major
73     zlib version number.  We hope that we will not have to break
74     the binary compatibility again, at least not as long as the
75     zlib-1.x series will last.
76
77     There is still a ZLIB_DLL macro, that can trigger a more
78     efficient build and use of the DLL, but compatibility no
79     longer dependents on it.
80
81
82  3. Can I build ZLIB.DLL from the new zlib sources, and replace
83     an old ZLIB.DLL, that was built from zlib-1.1.4 or earlier?
84
85   - In principle, you can do it by assigning calling convention
86     keywords to the macros ZEXPORT and ZEXPORTVA.  In practice,
87     it depends on what you mean by "an old ZLIB.DLL", because the
88     old DLL exists in several mutually-incompatible versions.
89     You have to find out first what kind of calling convention is
90     being used in your particular ZLIB.DLL build, and to use the
91     same one in the new build.  If you don't know what this is all
92     about, you might be better off if you would just leave the old
93     DLL intact.
94
95
96  4. Can I compile my application using the new zlib interface, and
97     link it to an old ZLIB.DLL, that was built from zlib-1.1.4 or
98     earlier?
99
100   - The official answer is "no"; the real answer depends again on
101     what kind of ZLIB.DLL you have.  Even if you are lucky, this
102     course of action is unreliable.
103
104     If you rebuild your application and you intend to use a newer
105     version of zlib (post- 1.1.4), it is strongly recommended to
106     link it to the new ZLIB1.DLL.
107
108
109  5. Why are the zlib symbols exported by name, and not by ordinal?
110
111   - Although exporting symbols by ordinal is a little faster, it
112     is risky.  Any single glitch in the maintenance or use of the
113     DEF file that contains the ordinals can result in incompatible
114     builds and frustrating crashes.  Simply put, the benefits of
115     exporting symbols by ordinal do not justify the risks.
116
117     Technically, it should be possible to maintain ordinals in
118     the DEF file, and still export the symbols by name.  Ordinals
119     exist in every DLL, and even if the dynamic linking performed
120     at the DLL startup is searching for names, ordinals serve as
121     hints, for a faster name lookup.  However, if the DEF file
122     contains ordinals, the Microsoft linker automatically builds
123     an implib that will cause the executables linked to it to use
124     those ordinals, and not the names.  It is interesting to
125     notice that the GNU linker for Win32 does not suffer from this
126     problem.
127
128     It is possible to avoid the DEF file if the exported symbols
129     are accompanied by a "__declspec(dllexport)" attribute in the
130     source files.  You can do this in zlib by predefining the
131     ZLIB_DLL macro.
132
133
134  6. I see that the ZLIB1.DLL functions use the "C" (CDECL) calling
135     convention.  Why not use the STDCALL convention?
136     STDCALL is the standard convention in Win32, and I need it in
137     my Visual Basic project!
138
139     (For readability, we use CDECL to refer to the convention
140      triggered by the "__cdecl" keyword, STDCALL to refer to
141      the convention triggered by "__stdcall", and FASTCALL to
142      refer to the convention triggered by "__fastcall".)
143
144   - Most of the native Windows API functions (without varargs) use
145     indeed the WINAPI convention (which translates to STDCALL in
146     Win32), but the standard C functions use CDECL.  If a user
147     application is intrinsically tied to the Windows API (e.g.
148     it calls native Windows API functions such as CreateFile()),
149     sometimes it makes sense to decorate its own functions with
150     WINAPI.  But if ANSI C or POSIX portability is a goal (e.g.
151     it calls standard C functions such as fopen()), it is not a
152     sound decision to request the inclusion of <windows.h>, or to
153     use non-ANSI constructs, for the sole purpose to make the user
154     functions STDCALL-able.
155
156     The functionality offered by zlib is not in the category of
157     "Windows functionality", but is more like "C functionality".
158
159     Technically, STDCALL is not bad; in fact, it is slightly
160     faster than CDECL, and it works with variable-argument
161     functions, just like CDECL.  It is unfortunate that, in spite
162     of using STDCALL in the Windows API, it is not the default
163     convention used by the C compilers that run under Windows.
164     The roots of the problem reside deep inside the unsafety of
165     the K&R-style function prototypes, where the argument types
166     are not specified; but that is another story for another day.
167
168     The remaining fact is that CDECL is the default convention.
169     Even if an explicit convention is hard-coded into the function
170     prototypes inside C headers, problems may appear.  The
171     necessity to expose the convention in users' callbacks is one
172     of these problems.
173
174     The calling convention issues are also important when using
175     zlib in other programming languages.  Some of them, like Ada
176     (GNAT) and Fortran (GNU G77), have C bindings implemented
177     initially on Unix, and relying on the C calling convention.
178     On the other hand, the pre- .NET versions of Microsoft Visual
179     Basic require STDCALL, while Borland Delphi prefers, although
180     it does not require, FASTCALL.
181
182     In fairness to all possible uses of zlib outside the C
183     programming language, we choose the default "C" convention.
184     Anyone interested in different bindings or conventions is
185     encouraged to maintain specialized projects.  The "contrib/"
186     directory from the zlib distribution already holds a couple
187     of foreign bindings, such as Ada, C++, and Delphi.
188
189
190  7. I need a DLL for my Visual Basic project.  What can I do?
191
192   - Define the ZLIB_WINAPI macro before including "zlib.h", when
193     building both the DLL and the user application (except that
194     you don't need to define anything when using the DLL in Visual
195     Basic).  The ZLIB_WINAPI macro will switch on the WINAPI
196     (STDCALL) convention.  The name of this DLL must be different
197     than the official ZLIB1.DLL.
198
199     Gilles Vollant has contributed a build named ZLIBWAPI.DLL,
200     with the ZLIB_WINAPI macro turned on, and with the minizip
201     functionality built in.  For more information, please read
202     the notes inside "contrib/vstudio/readme.txt", found in the
203     zlib distribution.
204
205
206  8. I need to use zlib in my Microsoft .NET project.  What can I
207     do?
208
209   - Henrik Ravn has contributed a .NET wrapper around zlib.  Look
210     into contrib/dotzlib/, inside the zlib distribution.
211
212
213  9. If my application uses ZLIB1.DLL, should I link it to
214     MSVCRT.DLL?  Why?
215
216   - It is not required, but it is recommended to link your
217     application to MSVCRT.DLL, if it uses ZLIB1.DLL.
218
219     The executables (.EXE, .DLL, etc.) that are involved in the
220     same process and are using the C run-time library (i.e. they
221     are calling standard C functions), must link to the same
222     library.  There are several libraries in the Win32 system:
223     CRTDLL.DLL, MSVCRT.DLL, the static C libraries, etc.
224     Since ZLIB1.DLL is linked to MSVCRT.DLL, the executables that
225     depend on it should also be linked to MSVCRT.DLL.
226
227
228 10. Why are you saying that ZLIB1.DLL and my application should
229     be linked to the same C run-time (CRT) library?  I linked my
230     application and my DLLs to different C libraries (e.g. my
231     application to a static library, and my DLLs to MSVCRT.DLL),
232     and everything works fine.
233
234   - If a user library invokes only pure Win32 API (accessible via
235     <windows.h> and the related headers), its DLL build will work
236     in any context.  But if this library invokes standard C API,
237     things get more complicated.
238
239     There is a single Win32 library in a Win32 system.  Every
240     function in this library resides in a single DLL module, that
241     is safe to call from anywhere.  On the other hand, there are
242     multiple versions of the C library, and each of them has its
243     own separate internal state.  Standalone executables and user
244     DLLs that call standard C functions must link to a C run-time
245     (CRT) library, be it static or shared (DLL).  Intermixing
246     occurs when an executable (not necessarily standalone) and a
247     DLL are linked to different CRTs, and both are running in the
248     same process.
249
250     Intermixing multiple CRTs is possible, as long as their
251     internal states are kept intact.  The Microsoft Knowledge Base
252     articles KB94248 "HOWTO: Use the C Run-Time" and KB140584
253     "HOWTO: Link with the Correct C Run-Time (CRT) Library"
254     mention the potential problems raised by intermixing.
255
256     If intermixing works for you, it's because your application
257     and DLLs are avoiding the corruption of each of the CRTs'
258     internal states, maybe by careful design, or maybe by fortune.
259
260     Also note that linking ZLIB1.DLL to non-Microsoft CRTs, such
261     as those provided by Borland, raises similar problems.
262
263
264 11. Why are you linking ZLIB1.DLL to MSVCRT.DLL?
265
266   - MSVCRT.DLL exists on every Windows 95 with a new service pack
267     installed, or with Microsoft Internet Explorer 4 or later, and
268     on all other Windows 4.x or later (Windows 98, Windows NT 4,
269     or later).  It is freely distributable; if not present in the
270     system, it can be downloaded from Microsoft or from other
271     software provider for free.
272
273     The fact that MSVCRT.DLL does not exist on a virgin Windows 95
274     is not so problematic.  Windows 95 is scarcely found nowadays,
275     Microsoft ended its support a long time ago, and many recent
276     applications from various vendors, including Microsoft, do not
277     even run on it.  Furthermore, no serious user should run
278     Windows 95 without a proper update installed.
279
280
281 12. Why are you not linking ZLIB1.DLL to
282     <<my favorite C run-time library>> ?
283
284   - We considered and abandoned the following alternatives:
285
286     * Linking ZLIB1.DLL to a static C library (LIBC.LIB, or
287       LIBCMT.LIB) is not a good option.  People are using the DLL
288       mainly to save disk space.  If you are linking your program
289       to a static C library, you may as well consider linking zlib
290       in statically, too.
291
292     * Linking ZLIB1.DLL to CRTDLL.DLL looks appealing, because
293       CRTDLL.DLL is present on every Win32 installation.
294       Unfortunately, it has a series of problems: it does not
295       work properly with Microsoft's C++ libraries, it does not
296       provide support for 64-bit file offsets, (and so on...),
297       and Microsoft discontinued its support a long time ago.
298
299     * Linking ZLIB1.DLL to MSVCR70.DLL or MSVCR71.DLL, supplied
300       with the Microsoft .NET platform, and Visual C++ 7.0/7.1,
301       raises problems related to the status of ZLIB1.DLL as a
302       system component.  According to the Microsoft Knowledge Base
303       article KB326922 "INFO: Redistribution of the Shared C
304       Runtime Component in Visual C++ .NET", MSVCR70.DLL and
305       MSVCR71.DLL are not supposed to function as system DLLs,
306       because they may clash with MSVCRT.DLL.  Instead, the
307       application's installer is supposed to put these DLLs
308       (if needed) in the application's private directory.
309       If ZLIB1.DLL depends on a non-system runtime, it cannot
310       function as a redistributable system component.
311
312     * Linking ZLIB1.DLL to non-Microsoft runtimes, such as
313       Borland's, or Cygwin's, raises problems related to the
314       reliable presence of these runtimes on Win32 systems.
315       It's easier to let the DLL build of zlib up to the people
316       who distribute these runtimes, and who may proceed as
317       explained in the answer to Question 14.
318
319
320 13. If ZLIB1.DLL cannot be linked to MSVCR70.DLL or MSVCR71.DLL,
321     how can I build/use ZLIB1.DLL in Microsoft Visual C++ 7.0
322     (Visual Studio .NET) or newer?
323
324   - Due to the problems explained in the Microsoft Knowledge Base
325     article KB326922 (see the previous answer), the C runtime that
326     comes with the VC7 environment is no longer considered a
327     system component.  That is, it should not be assumed that this
328     runtime exists, or may be installed in a system directory.
329     Since ZLIB1.DLL is supposed to be a system component, it may
330     not depend on a non-system component.
331
332     In order to link ZLIB1.DLL and your application to MSVCRT.DLL
333     in VC7, you need the library of Visual C++ 6.0 or older.  If
334     you don't have this library at hand, it's probably best not to
335     use ZLIB1.DLL.
336
337     We are hoping that, in the future, Microsoft will provide a
338     way to build applications linked to a proper system runtime,
339     from the Visual C++ environment.  Until then, you have a
340     couple of alternatives, such as linking zlib in statically.
341     If your application requires dynamic linking, you may proceed
342     as explained in the answer to Question 14.
343
344
345 14. I need to link my own DLL build to a CRT different than
346     MSVCRT.DLL.  What can I do?
347
348   - Feel free to rebuild the DLL from the zlib sources, and link
349     it the way you want.  You should, however, clearly state that
350     your build is unofficial.  You should give it a different file
351     name, and/or install it in a private directory that can be
352     accessed by your application only, and is not visible to the
353     others (e.g. it's not in the SYSTEM or the SYSTEM32 directory,
354     and it's not in the PATH).  Otherwise, your build may clash
355     with applications that link to the official build.
356
357     For example, in Cygwin, zlib is linked to the Cygwin runtime
358     CYGWIN1.DLL, and it is distributed under the name CYGZ.DLL.
359
360
361 15. May I include additional pieces of code that I find useful,
362     link them in ZLIB1.DLL, and export them?
363
364   - No.  A legitimate build of ZLIB1.DLL must not include code
365     that does not originate from the official zlib source code.
366     But you can make your own private DLL build, under a different
367     file name, as suggested in the previous answer.
368
369     For example, zlib is a part of the VCL library, distributed
370     with Borland Delphi and C++ Builder.  The DLL build of VCL
371     is a redistributable file, named VCLxx.DLL.
372
373
374 16. May I remove some functionality out of ZLIB1.DLL, by enabling
375     macros like NO_GZCOMPRESS or NO_GZIP at compile time?
376
377   - No.  A legitimate build of ZLIB1.DLL must provide the complete
378     zlib functionality, as implemented in the official zlib source
379     code.  But you can make your own private DLL build, under a
380     different file name, as suggested in the previous answer.
381
382
383 17. I made my own ZLIB1.DLL build.  Can I test it for compliance?
384
385   - We prefer that you download the official DLL from the zlib
386     web site.  If you need something peculiar from this DLL, you
387     can send your suggestion to the zlib mailing list.
388
389     However, in case you do rebuild the DLL yourself, you can run
390     it with the test programs found in the DLL distribution.
391     Running these test programs is not a guarantee of compliance,
392     but a failure can imply a detected problem.
393
394 **
395
396 This document is written and maintained by
397 Cosmin Truta <cosmint@cs.ubbcluj.ro>