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