From bf34a16e436c00eaeebcef0f8291ae7bfab0bdfd Mon Sep 17 00:00:00 2001 From: Hans Kristian Rosbach Date: Sat, 30 Jan 2021 15:46:24 +0100 Subject: [PATCH] Add porting guide. Sync cmake dfltcc descriptions with README. --- CMakeLists.txt | 4 ++-- PORTING.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 2 deletions(-) create mode 100644 PORTING.md diff --git a/CMakeLists.txt b/CMakeLists.txt index 07ca5128b..3da8cef13 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -101,8 +101,8 @@ if(BASEARCH_ARM_FOUND) elseif(BASEARCH_PPC_FOUND) add_option(WITH_POWER8 "Build with optimisations for POWER8" ON) elseif(BASEARCH_S360_FOUND) - add_option(WITH_DFLTCC_DEFLATE "Use DEFLATE CONVERSION CALL instruction for compression on IBM Z" OFF) - add_option(WITH_DFLTCC_INFLATE "Use DEFLATE CONVERSION CALL instruction for decompression on IBM Z" OFF) + add_option(WITH_DFLTCC_DEFLATE "Build with DFLTCC intrinsics for compression on IBM Z" OFF) + add_option(WITH_DFLTCC_INFLATE "Build with DFLTCC intrinsics for decompression on IBM Z" OFF) elseif(BASEARCH_X86_FOUND) add_option(WITH_AVX2 "Build with AVX2" ON) add_option(WITH_SSE2 "Build with SSE2" ON) diff --git a/PORTING.md b/PORTING.md new file mode 100644 index 000000000..6fa09b878 --- /dev/null +++ b/PORTING.md @@ -0,0 +1,56 @@ +Porting applications to use zlib-ng +----------------------------------- + +Zlib-ng can be used/compiled in two different modes, that require some +consideration by the application developer. + +zlib-compat mode +---------------- +Zlib-ng can be compiled in zlib-compat mode, suitable for zlib-replacement +in a single application or system-wide. + +Please note that zlib-ng in zlib-compat mode is API-compatible but not +ABI-compatible, meaning that you cannot simply replace the zlib library/dll +files and expect the application to work. The application will need to be +recompiled against the zlib-ng headers and libs to ensure full compatability. + +Zlib-ng can be distinguished from other zlib implementations at compile-time +by checking for the existence of ZLIBNG_VERSION defined in the zlib.h header. + +Compile against the *zlib.h* provided by zlib-ng. + +**Advantages:** +- Easy to port to, since it only requires a recompile of the application and + no changes to the application code. + +**Disadvantages:** +- Can conflict with a system-installed zlib, as that can often be linked in + by another library you are linking into your application. This can cause + crashes or incorrect output. +- If your application is pre-allocating a memory buffer and you are providing + deflate/inflate init with your own allocator that allocates from that buffer + (looking at you nginx), you should be aware that zlib-ng needs to allocate + more memory than stock zlib needs. The same problem exists with Intels and + Cloudflares zlib forks. Doing this is not recommended since it makes it + very hard to maintain compatibility over time. + + +zlib-ng native mode +------------------- +Zlib-ng in native mode is suitable for co-existing with the standard zlib +library, allowing applications to implement support and testing separately. + +The zlib-ng native has implemented some modernization and simplifications +in its API, intended to make life easier for application developers. + +Compile against *zlib-ng.h*. + +**Advantages:** +- Does not conflict with other zlib implementations, and can co-exist as a + system library along with zlib. +- In certain places zlib-ng native uses more appropriate data types, removing + the need for some workarounds in the API compared to zlib. + +**Disadvantages:** +- Requires minor changes to applications to use the prefixed zlib-ng + function calls and structs. Usually this means a small prefix `zng_` has to be added. -- 2.47.3