1Porting applications to use zlib-ng
2===================================
3
4Zlib-ng can be used/compiled in two different modes, that require some
5consideration by the application developer.
6
7zlib-compat mode
8----------------
9Zlib-ng can be compiled in zlib-compat mode, suitable for zlib-replacement
10in a single application or system-wide.
11
12Please note that zlib-ng in zlib-compat mode is API-compatible but not
13ABI-compatible, meaning that you cannot simply replace the zlib library/dll
14files and expect the application to work. The application will need to be
15recompiled against the zlib-ng headers and libs to ensure full compatibility.
16
17**Advantages:**
18- Easy to port to, since it only requires a recompile of the application and
19  no changes to the application code.
20
21**Disadvantages:**
22- Can conflict with a system-installed zlib, as that can often be linked in
23  by another library you are linking into your application. This can cause
24  crashes or incorrect output.
25- If your application is pre-allocating a memory buffer and you are providing
26  deflate/inflate init with your own allocator that allocates from that buffer
27  (looking at you nginx), you should be aware that zlib-ng needs to allocate
28  more memory than stock zlib needs. The same problem exists with Intels and
29  Cloudflares zlib forks. Doing this is not recommended since it makes it
30  very hard to maintain compatibility over time.
31
32**Build Considerations:**
33- Compile against the *zlib.h* provided by zlib-ng
34- Configuration header is named *zconf.h*
35- Static library is *libz.a* on Unix and macOS, or *zlib.lib* on Windows
36- Shared library is *libz.so* on Unix, *libz.dylib* on macOS, or *zlib1.dll*
37  on Windows
38- Type `z_size_t` is *unsigned long*
39
40zlib-ng native mode
41-------------------
42Zlib-ng in native mode is suitable for co-existing with the standard zlib
43library, allowing applications to implement support and testing separately.
44
45The zlib-ng native has implemented some modernization and simplifications
46in its API, intended to make life easier for application developers.
47
48**Advantages:**
49- Does not conflict with other zlib implementations, and can co-exist as a
50  system library along with zlib.
51- In certain places zlib-ng native uses more appropriate data types, removing
52  the need for some workarounds in the API compared to zlib.
53
54**Disadvantages:**
55- Requires minor changes to applications to use the prefixed zlib-ng
56  function calls and structs. Usually this means a small prefix `zng_` has to be added.
57
58**Build Considerations:**
59- Compile against *zlib-ng.h*
60- Configuration header is named *zconf-ng.h*
61- Static library is *libz-ng.a* on Unix and macOS, or *zlib-ng.lib* on Windows
62- Shared library is *libz-ng.so* on Unix, *libz-ng.dylib* on macOS, or
63  *zlib-ng2.dll* on Windows
64- Type `z_size_t` is *size_t*
65
66zlib-ng compile-time detection
67------------------------------
68
69To distinguish zlib-ng from other zlib implementations at compile-time check for the
70existence of `ZLIBNG_VERSION` defined in the zlib header.
71