mirror of
https://github.com/c64scene-ar/llvm-6502.git
synced 2024-08-20 11:29:24 +00:00
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@11148 91177308-0d34-0410-b5e6-96231b3b80d8
372 lines
16 KiB
Plaintext
372 lines
16 KiB
Plaintext
|
|
Frequently Asked Questions about ZLIB1.DLL
|
|
|
|
|
|
This document describes the design, the rationale, and the usage
|
|
of the official DLL build of zlib, named ZLIB1.DLL. If you have
|
|
general questions about zlib, you should see the file "FAQ" found
|
|
in the zlib distribution, or at the following location:
|
|
http://www.gzip.org/zlib/zlib_faq.html
|
|
|
|
|
|
1. What is ZLIB1.DLL, and how can I get it?
|
|
|
|
- ZLIB1.DLL is the official build of zlib as a DLL.
|
|
(Please remark the symbol '1' in the name.)
|
|
|
|
Pointers to a precompiled ZLIB1.DLL can be found in the zlib
|
|
web site at:
|
|
http://www.zlib.org/
|
|
|
|
Applications that link to ZLIB1.DLL can rely on the following
|
|
specification:
|
|
|
|
* The exported symbols are exclusively defined in the source
|
|
files "zlib.h" and "zlib.def", found in an official zlib
|
|
source distribution.
|
|
* The symbols are exported by name, not by ordinal.
|
|
* The exported names are undecorated.
|
|
* The calling convention of functions is "C" (CDECL).
|
|
* The ZLIB1.DLL binary is linked to MSVCRT.DLL.
|
|
|
|
The archive in which ZLIB1.DLL is bundled contains compiled
|
|
test programs that must run with a valid build of ZLIB1.DLL.
|
|
It is recommended to download the prebuilt DLL from the zlib
|
|
web site, instead of building it yourself, to avoid potential
|
|
incompatibilities that could be introduced by your compiler
|
|
and build settings. If you do build the DLL yourself, please
|
|
make sure that it complies with all the above requirements,
|
|
and it runs with the precompiled test programs, bundled with
|
|
the original ZLIB1.DLL distribution and available at the zlib
|
|
web site.
|
|
|
|
If, for any reason, you need to build an incompatible DLL,
|
|
please use a different name.
|
|
|
|
|
|
2. Why did you change the name of the DLL to ZLIB1.DLL?
|
|
What happened to the old ZLIB.DLL?
|
|
|
|
- The old ZLIB.DLL, built from zlib-1.1.x and earlier, required
|
|
compilation settings that were incompatible to those used by a
|
|
static build. The DLL settings were supposed to be enabled by
|
|
defining the macro ZLIB_DLL, before including "zlib.h".
|
|
Incorrect handling of this macro was silently accepted at
|
|
build time, resulting in two major problems:
|
|
|
|
* ZLIB_DLL was missing from the old makefile. When building
|
|
the DLL, not all people added it to the build options. In
|
|
consequence, incompatible incarnations of ZLIB.DLL started
|
|
to circulate around the net.
|
|
|
|
* When switching from using the static library to using the
|
|
DLL, applications had to define the ZLIB_DLL macro and
|
|
to recompile all the sources that contained calls to zlib
|
|
functions. Failure to do so resulted in creating binaries
|
|
that were unable to run with the official ZLIB.DLL build.
|
|
|
|
The only possible solution that we could foresee was to make a
|
|
binary-incompatible change in the DLL interfacing, in order to
|
|
remove the dependency on the ZLIB_DLL macro, and to release
|
|
the new DLL under a different name.
|
|
|
|
We chose the name ZLIB1.DLL, where '1' indicates the major
|
|
zlib version number. We hope that we will not have to break
|
|
the binary compatibility again, at least not as long as the
|
|
zlib-1.x series will last.
|
|
|
|
There is still a ZLIB_DLL macro, that can trigger a more
|
|
efficient build and use of the DLL, but compatibility no
|
|
longer dependents on it.
|
|
|
|
|
|
3. Can I build ZLIB.DLL from the new zlib sources, and replace
|
|
an old ZLIB.DLL, that was built from zlib-1.1.4 or earlier?
|
|
|
|
- In principle, you can do it by assigning calling convention
|
|
keywords to the macros ZEXPORT and ZEXPORTVA. In practice,
|
|
it depends on what you mean by "an old ZLIB.DLL", because
|
|
the old DLL exists in several mutually-incompatible versions.
|
|
|
|
If you have a compiled application that works with a certain
|
|
ZLIB.DLL without any known security issues, there is hardly
|
|
a need to rebuild the DLL from new sources only to link it to
|
|
the old app binary. But if you really want to do it, you have
|
|
to find out first what kind of calling convention uses your
|
|
particular ZLIB.DLL build, and to use the same one in the new
|
|
build. If you don't know what this is all about, you might be
|
|
better off if you would just forget it.
|
|
|
|
|
|
4. Can I compile my application using the new zlib interface, and
|
|
link it to an old ZLIB.DLL, that was built from zlib-1.1.4 or
|
|
earlier?
|
|
|
|
- The official answer is "no"; the real answer depends again on
|
|
what kind of ZLIB.DLL you have. Even if you are lucky, this
|
|
course of action is unreliable.
|
|
|
|
If you rebuild your application and you intend to use a newer
|
|
version of zlib (post- 1.1.4), it is strongly recommended to
|
|
link it to the new ZLIB1.DLL.
|
|
|
|
|
|
5. Why are the zlib symbols exported by name, and not by ordinal?
|
|
|
|
- Although exporting symbols by ordinal is a little faster, it
|
|
is risky. Any single glitch in the maintenance or use of the
|
|
DEF file that contains the ordinals can result in incompatible
|
|
builds and frustrating crashes. Simply put, the benefits of
|
|
exporting symbols by ordinal do not justify the risks.
|
|
|
|
Technically, it should be possible to maintain ordinals in
|
|
the DEF file, and still export the symbols by name. Ordinals
|
|
exist in every DLL, and even if the dynamic linking performed
|
|
at the DLL startup is searching for names, ordinals serve as
|
|
hints, for a faster name lookup. However, if the DEF file
|
|
contains ordinals, the Microsoft linker automatically builds
|
|
an implib that will cause the executables linked to it to use
|
|
those ordinals, and not the names. It is interesting to
|
|
notice that the GNU linker for Win32 does not suffer from this
|
|
problem.
|
|
|
|
It is possible to avoid the DEF file if the exported symbols
|
|
are accompanied by a "__declspec(dllexport)" attribute in the
|
|
source files. You can do this in zlib by predefining the
|
|
ZLIB_DLL macro.
|
|
|
|
|
|
6. I see that the ZLIB1.DLL functions use the "C" (CDECL) calling
|
|
convention. Why not use the STDCALL convention?
|
|
STDCALL is the standard convention in Win32, and I need it in
|
|
my Visual Basic project!
|
|
|
|
(For readability, we use CDECL to refer to the convention
|
|
triggered by the "__cdecl" keyword, STDCALL to refer to
|
|
the convention triggered by "__stdcall", and FASTCALL to
|
|
refer to the convention triggered by "__fastcall".)
|
|
|
|
- Most of the native Windows API functions (without varargs) use
|
|
indeed the WINAPI convention (which translates to STDCALL in
|
|
Win32), but the standard C functions use CDECL. If a user
|
|
application is intrinsically tied to the Windows API (e.g.
|
|
it calls native Windows API functions such as CreateFile()),
|
|
sometimes it makes sense to decorate its own functions with
|
|
WINAPI. But if ANSI C or POSIX portability is a goal (e.g.
|
|
it calls standard C functions such as fopen()), it is not a
|
|
sound decision to request the inclusion of <windows.h>, or to
|
|
use non-ANSI constructs, for the sole purpose to make the user
|
|
functions STDCALL-able.
|
|
|
|
The functionality offered by zlib is not in the category of
|
|
"Windows functionality", but is more like "C functionality".
|
|
|
|
Technically, STDCALL is not bad; in fact, it is slightly
|
|
faster than CDECL, and it works with variable-argument
|
|
functions, just like CDECL. It is unfortunate that, in spite
|
|
of using STDCALL in the Windows API, it is not the default
|
|
convention used by the C compilers that run under Windows.
|
|
The roots of the problem reside deep inside the unsafety of
|
|
the K&R-style function prototypes, where the argument types
|
|
are not specified; but that is another story for another day.
|
|
|
|
The fact that remains is that CDECL is the default convention.
|
|
Even if an explicit convention (such as STDCALL or FASTCALL)
|
|
is hard-coded into the function prototypes inside C headers,
|
|
problems may appear. One problem, for example, deals with the
|
|
necessity to expose the convention in users' callbacks.
|
|
|
|
The calling convention issues are also important when using
|
|
zlib in other programming languages. Some of them, like Ada
|
|
(GNAT) and Fortran (GNU G77), have C bindings implemented
|
|
initially on Unix, and relying on the C calling convention.
|
|
On the other hand, the pre- .NET versions of Microsoft Visual
|
|
Basic require STDCALL, while Borland Delphi prefers (although
|
|
it does not require) FASTCALL.
|
|
|
|
In fairness to all possible uses of zlib outside the C
|
|
programming language, we choose the default "C" convention.
|
|
Anyone interested in different bindings or conventions is
|
|
encouraged to maintain specialized projects. The "contrib/"
|
|
directory from the zlib distribution already holds a couple
|
|
of foreign bindings, such as Ada, C++, and Delphi.
|
|
|
|
|
|
7. I need a DLL for my Visual Basic project. What can I do?
|
|
|
|
- Define the ZLIB_WINAPI macro before including "zlib.h", when
|
|
building both the DLL and the user application (except that
|
|
you don't need to define anything when using the DLL in Visual
|
|
Basic). The ZLIB_WINAPI macro will switch on the WINAPI
|
|
(STDCALL) convention. The name of this DLL must be different
|
|
than the official ZLIB1.DLL.
|
|
|
|
Gilles Vollant has contributed a build named ZLIBWAPI.DLL,
|
|
with the ZLIB_WINAPI macro turned on, and with the minizip
|
|
functionality built in. For more information, please read
|
|
the notes inside "contrib/vstudio/readme.txt", found in the
|
|
zlib distribution.
|
|
|
|
|
|
8. If my application uses ZLIB1.DLL, should I link it to
|
|
MSVCRT.DLL? Why?
|
|
|
|
- It is not required, but it is recommended to link your
|
|
application to MSVCRT.DLL, if it uses ZLIB1.DLL.
|
|
|
|
The executables (.EXE, .DLL, etc.) that are involved in the
|
|
same process and are using the C run-time library (i.e. they
|
|
are calling standard C functions), must link to the same
|
|
library. There are several libraries in the Win32 system:
|
|
CRTDLL.DLL, MSVCRT.DLL, the static C libraries, etc.
|
|
Since ZLIB1.DLL is linked to MSVCRT.DLL, the executables that
|
|
depend on it should also be linked to MSVCRT.DLL.
|
|
|
|
|
|
9. Why are you saying that ZLIB1.DLL and my application must be
|
|
linked to the same C run-time (CRT) library? I linked my
|
|
application and my DLLs to different C libraries (e.g. my
|
|
application to a static library, and my DLLs to MSVCRT.DLL),
|
|
and everything works fine.
|
|
|
|
- If a user library invokes only pure Win32 API (accessible via
|
|
<windows.h> and the related headers), its DLL build will work
|
|
in any context. But if this library invokes standard C API,
|
|
things get more complicated.
|
|
|
|
There is a single Win32 library in a Win32 system. Every
|
|
function in this library resides in a single DLL module, that
|
|
is safe to call from anywhere. On the other hand, there are
|
|
multiple versions of the C library, and each of them has its
|
|
own separate internal state. Standalone executables and user
|
|
DLLs that call standard C functions must link to a C run-time
|
|
(CRT) library, be it static or shared (DLL). Intermixing
|
|
occurs when an executable (not necessarily standalone) and a
|
|
DLL are linked to different CRTs, and both are running in the
|
|
same process.
|
|
|
|
Intermixing multiple CRTs is possible, as long as their
|
|
internal states are kept intact. The Microsoft Knowledge Base
|
|
articles KB94248 "HOWTO: Use the C Run-Time" and KB140584
|
|
"HOWTO: Link with the Correct C Run-Time (CRT) Library"
|
|
mention the potential problems raised by intermixing.
|
|
|
|
If intermixing works for you, it's because your application
|
|
and DLLs are avoiding the corruption of each of the CRTs'
|
|
internal states, maybe by careful design, or maybe by fortune.
|
|
|
|
Also note that linking ZLIB1.DLL to non-Microsoft CRTs (such
|
|
as those provided by Borland) raises similar problems.
|
|
|
|
|
|
10. Why are you linking ZLIB1.DLL to MSVCRT.DLL?
|
|
|
|
- MSVCRT.DLL exists on every Windows 95 with a new service pack
|
|
installed, or with Microsoft Internet Explorer 4 or later, and
|
|
on all other Windows 4.x or later (Windows 98, Windows NT 4,
|
|
or later). It is freely distributable; if not present in the
|
|
system, it can be downloaded from Microsoft or from other
|
|
software provider for free.
|
|
|
|
The fact that MSVCRT.DLL does not exist on a virgin Windows 95
|
|
is not so problematic. The number of Windows 95 installations
|
|
is rapidly decreasing, Microsoft stopped supporting it a long
|
|
time ago, and many recent applications from various vendors,
|
|
including Microsoft, do not even run on it. Furthermore, no
|
|
serious user should run Windows 95 without a proper update
|
|
installed.
|
|
|
|
There is also the fact that the mainstream C compilers for
|
|
Windows are Microsoft Visual C++ 6.0, and gcc/MinGW. Both
|
|
are producing executables that link to MSVCRT.DLL by default,
|
|
without offering other dynamic CRTs as alternatives easy to
|
|
select by users.
|
|
|
|
|
|
11. Why are you not linking ZLIB1.DLL to
|
|
<<my favorite C run-time library>> ?
|
|
|
|
- We considered and abandoned the following alternatives:
|
|
|
|
* Linking ZLIB1.DLL to a static C library (LIBC.LIB, or
|
|
LIBCMT.LIB) is not a good option. People are using the DLL
|
|
mainly to save disk space. If you are linking your program
|
|
to a static C library, you may as well consider linking zlib
|
|
in statically, too.
|
|
|
|
* Linking ZLIB1.DLL to CRTDLL.DLL looks very appealing,
|
|
because CRTDLL.DLL is present on every Win32 installation.
|
|
Unfortunately, it has a series of problems: it raises
|
|
difficulties when using it with C++ code, it does not work
|
|
with 64-bit file offsets, (and so on...), and Microsoft
|
|
discontinued its support a long time ago.
|
|
|
|
* Linking ZLIB1.DLL to MSVCR70.DLL, supplied with the
|
|
Microsoft .NET platform and Visual C++ 7.0 or newer, is not
|
|
a good option. Although it is available for free download
|
|
and distribution, its presence is scarce on today's Win32
|
|
installations. If it will ever become more popular than
|
|
MSVCRT.DLL and will be pre-installed on the future Win32
|
|
systems, we will probably think again about it.
|
|
|
|
* Linking ZLIB1.DLL to NTDLL.DLL is not possible.
|
|
NTDLL.DLL exports only a part of the C library, and only on
|
|
Windows NT systems.
|
|
|
|
|
|
12. I need to link my own DLL build to a CRT different than
|
|
MSVCRT.DLL. What can I do?
|
|
|
|
- Feel free to rebuild the DLL from the zlib sources, and link
|
|
it the way you want. You should, however, clearly state that
|
|
your build is unofficial. You should give it a different file
|
|
name, and/or install it in a private directory that can be
|
|
accessed by your application only, and is not visible to the
|
|
others (e.g. it's not in the SYSTEM or the SYSTEM32 directory,
|
|
and it's not in the PATH). Otherwise, your build may clash
|
|
with applications that link to the official build.
|
|
|
|
For example, in Cygwin, zlib is linked to the Cygwin runtime
|
|
CYGWIN1.DLL, and it is distributed under the name CYGZ.DLL.
|
|
|
|
|
|
13. May I include additional pieces of code that I find useful,
|
|
link them in ZLIB1.DLL, and export them?
|
|
|
|
- No. A legitimate build of ZLIB1.DLL must not include code
|
|
that does not originate from the official zlib source code.
|
|
But you can make your own private DLL build, under a different
|
|
file name, as suggested in the previous answer.
|
|
|
|
For example, in Borland Delphi and C++ Builder, zlib is a part
|
|
of the standard VCL library. If an application links to VCL
|
|
dynamically, the name of the distributable binary (VCLxx.DLL)
|
|
does not posess any danger of clashing with a legitimate but
|
|
incompatible ZLIB1.DLL.
|
|
|
|
|
|
14. May I remove some functionality out of ZLIB1.DLL, by enabling
|
|
macros like NO_GZCOMPRESS or NO_GZIP at compile time?
|
|
|
|
- No. A legitimate build of ZLIB1.DLL must provide the complete
|
|
zlib functionality, as implemented in the official zlib source
|
|
code. But you can make your own private DLL build, under a
|
|
different file name, as suggested in the previous answer.
|
|
|
|
|
|
15. I made my own ZLIB1.DLL build. Can I test it for compliance?
|
|
|
|
- We prefer that you download the official DLL from the zlib
|
|
web site. If you need something peculiar from this DLL, you
|
|
can send your suggestion to the zlib mailing list.
|
|
|
|
However, in case you do rebuild the DLL yourself, you can run
|
|
it with the test programs found in the DLL distribution.
|
|
Running these test programs is not a guarantee of compliance,
|
|
but a failure can imply a detected problem.
|
|
|
|
**
|
|
|
|
This document is written and maintained by
|
|
Cosmin Truta <cosmint@cs.ubbcluj.ro>
|