Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/zlib/win32/DLL_FAQ.txt @ 2:b50eed0cc0ef upstream

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