Porting guide from zlib to zlib-ng

[gdevenyi]

For users who want to go all-in in switching from zlib to zlib-ng (i.e. don't use zlib-compat), I don't yet see a guide for porting to the new API.

[mtl1979]

We haven't stabilized the new API yet... Around the first release, we should have all the details necessary to make a porting guide...

Differences include for example:

• Some types, including struct members, are const always now
• Some types are always same bit width independent of architecture pointer size (no long or long long)
• Some struct members are smaller or larger than with zlib, hard-coding the size of structs is bad practice
• All allocated buffer sizes need to be multiples of 16 bytes, in future safe will be multiple of 64
• Some allocated buffers should be aligned to 16 byte boundary, see above, safe is to let zlib-ng allocate them

[nmoinvaz]

@mtl1979 is this still true, now that the NEON stuff has been removed?

• Some allocated buffers should be aligned to 16 byte boundary, see above, safe is to let zlib-ng allocate them

[mtl1979]

@nmoinvaz It still is true, especially on architectures where unaligned reads and writes are not allowed... Most compilers by default only align to 8-byte boundary. However now that we removed chunkmemset_3 and chunkmemset_6, there is no longer requirement that when the externally allocated buffer ends at 16 byte boundary, it should be padded with extra 16 bytes...

It just basically means minimum safe buffer size is 16 bytes and it is more efficient if buffer size is multiple of 16 bytes.

[nmoinvaz]

I am correct in assuming this only holds true for deflate* and inflate* functions? And that for gz* functions they have their own internal buffers..

[mtl1979]

gz* functions are just wrappers that use deflate/inflate...

[nmoinvaz]

The guide should also mention the user of the library should:

• Include zlib.h when zlib compatibility is on (see -DZLIB_COMPAT=ON or --zlib-compat)
• Otherwise include zlib-ng.h and all function names prefixed with zng_ (see PREFIX macros)

It will help prevent us from getting issues submitted like #827.