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 tries to maintain both API and
13ABI compatibility with the original zlib. Any issues regarding compatibility
14can be reported as bugs.
15
16In certain instances you may not be able to simply replace the zlib library/dll
17files and expect the application to work. The application may need to be
18recompiled against the zlib-ng headers and libs to ensure full compatibility.
19
20It is also possible for the deflate output stream to differ from the original
21zlib due to algorithmic differences between the two libraries. Any tests or
22applications that depend on the exact length of the deflate stream being a
23certain value will need to be updated.
24
25**Advantages:**
26- Easy to port to, since it only requires a recompile of the application and
27  no changes to the application code.
28
29**Disadvantages:**
30- Can conflict with a system-installed zlib, as that can often be linked in
31  by another library you are linking into your application. This can cause
32  crashes or incorrect output.
33- If your application is pre-allocating a memory buffer and you are providing
34  deflate/inflate init with your own allocator that allocates from that buffer
35  (looking at you nginx), you should be aware that zlib-ng needs to allocate
36  more memory than stock zlib needs. The same problem exists with Intel’s and
37  Cloudflare’s zlib forks. Doing this is not recommended since it makes it
38  very hard to maintain compatibility over time.
39
40**Build Considerations:**
41- Compile against the *zlib.h* provided by zlib-ng
42- Configuration header is named *zconf.h*
43- Static library is *libz.a* on Unix and macOS, or *zlib.lib* on Windows
44- Shared library is *libz.so* on Unix, *libz.dylib* on macOS, or *zlib1.dll*
45  on Windows
46- Type `z_size_t` is *unsigned long*
47
48zlib-ng native mode
49-------------------
50Zlib-ng in native mode is suitable for co-existing with the standard zlib
51library, allowing applications to implement support and testing separately.
52
53The zlib-ng native has implemented some modernization and simplifications
54in its API, intended to make life easier for application developers.
55
56**Advantages:**
57- Does not conflict with other zlib implementations, and can co-exist as a
58  system library along with zlib.
59- In certain places zlib-ng native uses more appropriate data types, removing
60  the need for some workarounds in the API compared to zlib.
61
62**Disadvantages:**
63- Requires minor changes to applications to use the prefixed zlib-ng
64  function calls and structs. Usually this means a small prefix `zng_` has to be added.
65
66**Build Considerations:**
67- Compile against *zlib-ng.h*
68- Configuration header is named *zconf-ng.h*
69- Static library is *libz-ng.a* on Unix and macOS, or *zlib-ng.lib* on Windows
70- Shared library is *libz-ng.so* on Unix, *libz-ng.dylib* on macOS, or
71  *zlib-ng2.dll* on Windows
72- Type `z_size_t` is *size_t*
73
74zlib-ng compile-time detection
75------------------------------
76
77To distinguish zlib-ng from other zlib implementations at compile-time check for the
78existence of `ZLIBNG_VERSION` defined in the zlib header.
79