From: Hans Kristian Rosbach <hk-git@circlestorm.org>
Date: Sat, 30 Jan 2021 14:46:24 +0000 (+0100)
Subject: Add porting guide.
X-Git-Tag: 2.0.0~14
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bf34a16e436c00eaeebcef0f8291ae7bfab0bdfd;p=thirdparty%2Fzlib-ng.git

Add porting guide.
Sync cmake dfltcc descriptions with README.
---

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 07ca5128..3da8cef1 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 00000000..6fa09b87
--- /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.