Add 'neozip/' from commit 'c2712b8a345191f6ed79558c089777df94590087'

git-subtree-dir: neozip
git-subtree-mainline: b1e34e861b5d732afe828d58aad2c638135061fd
git-subtree-split: c2712b8a345191f6ed79558c089777df94590087

1 files changed, 111 insertions, 0 deletions

diff --git a/neozip/PORTING.md b/neozip/PORTING.md
new file mode 100644
index 0000000000..208f6ee9e7
--- /dev/null
+++ b/neozip/PORTING.md
@@ -0,0 +1,111 @@
+Porting applications to use zlib-ng
+===================================
+
+Zlib-ng can be used/compiled in two different modes, that require some
+consideration by the application developer.
+
+Changes from zlib affecting native and compat modes
+---------------------------------------------------
+Zlib-ng is not as conservative with memory allocation as Zlib is.
+
+Where Zlib's inflate will allocate a lower amount of memory depending on
+compression level and window size, zlib-ng will always allocate the maximum
+amount of memory and possibly leave parts of it unused.
+Zlib-ng's deflate will however allocate a lower amount of memory depending
+on compression level and window size.
+
+Zlib-ng also allocates one "big" buffer instead of doing multiple smaller
+allocations. This is faster, can lead to better cache locality and reduces
+space lost to alignment padding.
+
+At the time of writing, by default zlib-ng allocates the following amounts
+of memory on a 64-bit system (except on S390x that requires ~4KiB more):
+-  Deflate: 350.272 Bytes
+-  Inflate:  42.112 Bytes
+
+**Advantages:**
+- All memory is allocated during DeflateInit or InflateInit functions,
+  leaving the actual deflate/inflate functions free from allocations.
+- Zlib-ng can only fail from memory allocation errors during init.
+- Time spent doing memory allocation systemcalls is all done during init,
+  allowing applications to do prepare this before doing latency-sensitive
+  deflate/inflate later.
+- Can reduce wasted memory due to buffer alignment padding both by OS and zlib-ng.
+- Potentially improved memory locality.
+
+**Disadvantages:**
+- Zlib-ng allocates a little more memory than zlib does.
+
+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 tries to maintain both API and
+ABI compatibility with the original zlib. Any issues regarding compatibility
+can be reported as bugs.
+
+In certain instances you may not be able to simply replace the zlib library/dll
+files and expect the application to work. The application may need to be
+recompiled against the zlib-ng headers and libs to ensure full compatibility.
+
+It is also possible for the deflate output stream to differ from the original
+zlib due to algorithmic differences between the two libraries. Any tests or
+applications that depend on the exact length of the deflate stream being a
+certain value will need to be updated.
+
+**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 Intel’s and
+  Cloudflare’s zlib forks. Doing this is not recommended since it makes it
+  very hard to maintain compatibility over time.
+
+**Build Considerations:**
+- Compile against the *zlib.h* provided by zlib-ng
+- Configuration header is named *zconf.h*
+- Static library is *libz.a* on Unix and macOS, or *zlib.lib* on Windows
+- Shared library is *libz.so* on Unix, *libz.dylib* on macOS, or *zlib1.dll*
+  on Windows
+- Type `z_size_t` is *unsigned __int64* on 64-bit Windows, and *unsigned long* on 32-bit Windows, Unix and macOS
+- Type `z_uintmax_t` is *unsigned long* in zlib-compat mode, and *size_t* with zlib-ng API
+
+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.
+
+**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.
+
+**Build Considerations:**
+- Compile against *zlib-ng.h*
+- Configuration header is named *zconf-ng.h*
+- Static library is *libz-ng.a* on Unix and macOS, or *zlib-ng.lib* on Windows
+- Shared library is *libz-ng.so* on Unix, *libz-ng.dylib* on macOS, or
+  *zlib-ng2.dll* on Windows
+- Type `z_size_t` is *size_t*
+
+zlib-ng compile-time detection
+------------------------------
+
+To distinguish zlib-ng from other zlib implementations at compile-time check for the
+existence of `ZLIBNG_VERSION` defined in the zlib header.