OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-dev/] [or1k-gcc/] [zlib/] [win32/] [DLL_FAQ.txt] - Blame information for rev 770

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 745 jeremybenn
 
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 , 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
     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
    <> ?
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 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.