diff options
Diffstat (limited to 'docs/handbook/archived/ptlibzippy.md')
| -rw-r--r-- | docs/handbook/archived/ptlibzippy.md | 501 |
1 files changed, 501 insertions, 0 deletions
diff --git a/docs/handbook/archived/ptlibzippy.md b/docs/handbook/archived/ptlibzippy.md new file mode 100644 index 0000000000..21ad2d6ce1 --- /dev/null +++ b/docs/handbook/archived/ptlibzippy.md @@ -0,0 +1,501 @@ +# PTlibzippy + +## Overview + +PTlibzippy is a Project Tick fork of the [zlib](https://zlib.net/) data compression library. +It is a general-purpose lossless data compression library implementing the DEFLATE algorithm +as specified in RFCs 1950 (zlib format), 1951 (deflate format), and 1952 (gzip format). + +PTlibzippy was version 0.0.5.1 and was maintained as a detached fork to solve symbol +conflicts when bundling zlib alongside libpng in the ProjT Launcher's build system. + +**Status**: Archived — system zlib is now used instead of a bundled fork. + +--- + +## Project Identity + +| Property | Value | +|-------------------|----------------------------------------------------------| +| **Name** | PTlibzippy | +| **Location** | `archived/ptlibzippy/` | +| **Language** | C | +| **Version** | 0.0.5.1 | +| **License** | zlib license (permissive) | +| **Copyright** | 1995–2026 Jean-loup Gailly and Mark Adler; 2026 Project Tick | +| **Homepage** | https://projecttick.org/p/zlib | +| **FAQ** | https://projecttick.org/p/zlib/zlib_faq.html | +| **Contact** | community@community.projecttick.org | + +--- + +## Why a zlib Fork? + +The fork was created to solve a specific technical problem in the ProjT Launcher: + +### The Symbol Conflict Problem + +When the launcher bundled both zlib and libpng as static libraries, the linker +encountered duplicate symbol definitions. Both zlib and libpng's internal zlib +usage exported identical function names (e.g., `deflate`, `inflate`, `compress`), +causing link-time errors or runtime symbol resolution ambiguities. + +### The Solution + +PTlibzippy addressed this through: + +1. **Symbol prefixing** — The `PTLIBZIPPY_PREFIX` CMake option enables renaming all + public symbols with a custom prefix, preventing collisions +2. **PNG shim layer** — A custom `ptlibzippy_pngshim.c` file provided a compatibility + layer between the renamed zlib symbols and libpng's expectations +3. **Custom header names** — Headers were renamed (`ptlibzippy.h`, `ptzippyconf.h`, + `ptzippyguts.h`, `ptzippyutil.h`) to avoid include-path conflicts + +As noted in the ProjT Launcher changelog: +> "zlib symbol handling was refined to use libpng-targeted shim overrides instead +> of global prefixing." + +--- + +## License + +The zlib license is permissive and compatible with GPL: + +``` +Copyright notice: + + (C) 1995-2026 Jean-loup Gailly and Mark Adler + (C) 2026 Project Tick + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +``` + +--- + +## Build System + +PTlibzippy supported three build systems: + +### CMake (Primary) + +```cmake +cmake_minimum_required(VERSION 3.12...3.31) + +project( + PTlibzippy + LANGUAGES C + VERSION 0.0.5.1 + HOMEPAGE_URL "https://projecttick.org/p/zlib" + DESCRIPTION "PTlibzippy - a general-purpose lossless data-compression library") +``` + +#### CMake Options + +| Option | Default | Description | +|---------------------------|---------|----------------------------------------------| +| `PTLIBZIPPY_BUILD_TESTING`| `ON` | Enable building test programs | +| `PTLIBZIPPY_BUILD_SHARED` | `ON` | Build shared library (`libptlibzippy.so`) | +| `PTLIBZIPPY_BUILD_STATIC` | `ON` | Build static library (`libptlibzippystatic.a`)| +| `PTLIBZIPPY_INSTALL` | `ON` | Enable `make install` target | +| `PTLIBZIPPY_PREFIX` | `OFF` | Enable symbol prefixing for all public APIs | + +#### Feature Detection + +The CMake build detected platform capabilities: + +```cmake +check_type_size(off64_t OFF64_T) # Large file support +check_function_exists(fseeko HAVE_FSEEKO) # POSIX fseeko +check_include_file(stdarg.h HAVE_STDARG_H) +check_include_file(unistd.h HAVE_UNISTD_H) +``` + +And generated `ptzippyconf.h` with the results: + +```cmake +configure_file(${PTlibzippy_BINARY_DIR}/ptzippyconf.h.cmakein + ${PTlibzippy_BINARY_DIR}/ptzippyconf.h) +``` + +#### Visibility Attributes + +On non-Windows platforms, the build checked for GCC visibility attributes: + +```c +void f(void) __attribute__ ((visibility("hidden"))); +``` + +This enabled hiding internal symbols from the shared library's public API. + +#### Library Targets + +**Shared library:** + +```cmake +add_library(ptlibzippy SHARED ${PTLIBZIPPY_SRCS} ...) +add_library(PTlibzippy::PTlibzippy ALIAS ptlibzippy) + +target_compile_definitions(ptlibzippy + PRIVATE PTLIBZIPPY_BUILD PTLIBZIPPY_INTERNAL= ...) +``` + +**Static library:** + +```cmake +add_library(ptlibzippystatic STATIC ${PTLIBZIPPY_SRCS} ...) +``` + +On Windows, the static library gets a `"s"` suffix to distinguish from the import library. + +#### pkg-config + +A `ptlibzippy.pc` file was generated for pkg-config integration: + +```cmake +configure_file(${PTlibzippy_SOURCE_DIR}/ptlibzippy.pc.cmakein + ${PTLIBZIPPY_PC} @ONLY) +``` + +### Autotools + +Traditional Unix build: + +```bash +./configure +make +make test +make install +``` + +### Bazel + +``` +BUILD.bazel # Build rules +MODULE.bazel # Module definition +``` + +--- + +## Source Files + +### Public Headers + +| Header | Purpose | +|----------------|----------------------------------------------------| +| `ptlibzippy.h` | Public API (compress, decompress, gzip, etc.) | +| `ptzippyconf.h`| Configuration header (generated at build time) | + +### Private Headers + +| Header | Purpose | +|----------------|----------------------------------------------------| +| `crc32.h` | CRC-32 lookup tables | +| `deflate.h` | DEFLATE compression state machine | +| `ptzippyguts.h` | Internal definitions (gzip state) | +| `inffast.h` | Fast inflate inner loop | +| `inffixed.h` | Fixed Huffman code tables | +| `inflate.h` | Inflate state machine | +| `inftrees.h` | Huffman tree building | +| `trees.h` | Dynamic Huffman tree encoding | +| `ptzippyutil.h` | System-level utilities | + +### Source Files + +| Source | Purpose | +|-------------------------|-----------------------------------------------| +| `adler32.c` | Adler-32 checksum computation | +| `compress.c` | Compression convenience API | +| `crc32.c` | CRC-32 checksum computation | +| `deflate.c` | DEFLATE compression algorithm | +| `gzclose.c` | gzip file close | +| `gzlib.c` | gzip file utility functions | +| `gzread.c` | gzip file reading | +| `gzwrite.c` | gzip file writing | +| `inflate.c` | DEFLATE decompression algorithm | +| `infback.c` | Inflate using a callback interface | +| `inftrees.c` | Generate Huffman trees for inflate | +| `inffast.c` | Fast inner loop for inflate | +| `ptlibzippy_pngshim.c` | PNG integration shim (Project Tick addition) | +| `trees.c` | Output compressed data using Huffman coding | +| `uncompr.c` | Decompression convenience API | +| `ptzippyutil.c` | Operating system interface utilities | + +### Project Tick Additions + +The following files were added or renamed by Project Tick (not present in upstream zlib): + +| File | Change Type | Purpose | +|-------------------------|-------------|--------------------------------------| +| `ptlibzippy_pngshim.c` | Added | Shim for libpng symbol compatibility | +| `ptzippyguts.h` | Renamed | From `gzguts.h` | +| `ptzippyutil.c` | Renamed | From `zutil.c` | +| `ptzippyutil.h` | Renamed | From `zutil.h` | +| `ptzippyconf.h` | Renamed | From `zconf.h` | +| `ptlibzippy.h` | Renamed | From `zlib.h` | +| `ptlibzippy.pc.cmakein` | Renamed | From `zlib.pc.cmakein` | +| `COPYING.md` | Modified | Added Project Tick copyright | + +--- + +## Symbol Prefixing + +The `PTLIBZIPPY_PREFIX` option enables symbol prefixing for all public API functions. +When enabled, all zlib functions are prefixed to avoid collisions: + +| Original Symbol | Prefixed Symbol (example) | +|----------------|---------------------------| +| `deflate` | `pt_deflate` | +| `inflate` | `pt_inflate` | +| `compress` | `pt_compress` | +| `uncompress` | `pt_uncompress` | +| `crc32` | `pt_crc32` | +| `adler32` | `pt_adler32` | + +The prefix is configured through `ptzippyconf.h`: + +```cmake +set(PT_PREFIX ${PTLIBZIPPY_PREFIX}) +file(APPEND ${PTCONF_OUT_FILE} "#cmakedefine PT_PREFIX 1\n") +``` + +--- + +## PNG Shim Layer + +The `ptlibzippy_pngshim.c` file was the key Project Tick addition. It provided a +compatibility layer that allowed libpng to use PTlibzippy's renamed symbols +transparently. + +Without the shim, libpng would look for standard zlib function names (`deflate`, +`inflate`, etc.) and fail to link against PTlibzippy's prefixed versions. + +The shim worked by: +1. Including PTlibzippy's headers (with prefixed symbols) +2. Providing wrapper functions with the original zlib names +3. Each wrapper forwarded to the corresponding PTlibzippy function + +This approach was described in the changelog as: +> "zlib symbol handling was refined to use libpng-targeted shim overrides instead +> of global prefixing" + +--- + +## Cross-Platform Support + +PTlibzippy inherited zlib's extensive platform support: + +| Platform | Build System | Notes | +|------------------|-------------------------------|-------------------------------| +| Linux | CMake, Autotools, Makefile | Primary development platform | +| macOS | CMake, Autotools | | +| Windows | CMake, NMake, MSVC | DLL and static library | +| Windows (MinGW) | CMake, Makefile | | +| Cygwin | CMake, Autotools | DLL naming handled | +| Amiga | Makefile.pup, Makefile.sas | SAS/C compiler | +| OS/400 | Custom makefiles | IBM i (formerly AS/400) | +| QNX | Custom makefiles | QNX Neutrino | +| VMS | make_vms.com | OpenVMS command procedure | + +### Platform-Specific Notes from README + +- **64-bit Irix**: `deflate.c` must be compiled without optimization with `-O` +- **Digital Unix 4.0D**: Requires `cc -std1` for correct `gzprintf` behavior +- **HP-UX 9.05**: Some versions of `/bin/cc` are incompatible +- **PalmOS**: Supported via external port (https://palmzlib.sourceforge.net/) + +--- + +## Third-Party Contributions + +The `contrib/` directory contained community-contributed extensions: + +| Directory | Description | +|----------------|------------------------------------------------| +| `contrib/ada/` | Ada programming language bindings | +| `contrib/blast/`| PKWare Data Compression Library decompressor | +| `contrib/crc32vx/`| Vectorized CRC-32 for IBM z/Architecture | +| `contrib/delphi/`| Borland Delphi bindings | +| `contrib/dotzlib/`| .NET (C#) bindings | +| `contrib/gcc_gvmat64/`| x86-64 assembly optimizations | + +Ada bindings included full package specifications: + +``` +contrib/ada/ptlib.ads # Package spec +contrib/ada/ptlib.adb # Package body +contrib/ada/ptlib-thin.ads # Thin binding spec +contrib/ada/ptlib-thin.adb # Thin binding body +contrib/ada/ptlib-streams.ads # Stream interface spec +contrib/ada/ptlib-streams.adb # Stream interface body +``` + +--- + +## FAQ Highlights + +From the project FAQ: + +**Q: Is PTlibzippy Y2K-compliant?** +A: Yes. PTlibzippy doesn't handle dates. + +**Q: Can zlib handle .zip archives?** +A: Not by itself. See `contrib/minizip`. + +**Q: Can zlib handle .Z files?** +A: No. Use `uncompress` or `gunzip` subprocess. + +**Q: How can I make a Unix shared library?** +A: Default build produces shared + static libraries: +```bash +make distclean +./configure +make +``` + +--- + +## Language Bindings + +PTlibzippy (and its zlib base) was accessible from many languages: + +| Language | Interface | +|----------|---------------------------------------------------| +| C | Native API via `ptlibzippy.h` | +| C++ | Direct C API usage | +| Ada | `contrib/ada/` bindings | +| C# (.NET)| `contrib/dotzlib/` bindings | +| Delphi | `contrib/delphi/` bindings | +| Java | `java.util.zip` package (JDK built-in) | +| Perl | IO::Compress module | +| Python | `zlib` module (Python standard library) | +| Tcl | Built-in zlib support | + +--- + +## Integration with ProjT Launcher + +In the ProjT Launcher's CMake build, PTlibzippy was used via: + +```cmake +# From cmake/usePTlibzippy.cmake (referenced in the launcher's cmake/ directory) +``` + +The launcher's `CMakeLists.txt` imported PTlibzippy alongside other compression +libraries (bzip2, quazip) to handle: + +- Mod archive extraction (`.zip`, `.jar` files) +- Instance backup/restore +- Asset pack handling +- Modpack import/export (Modrinth `.mrpack`, CurseForge `.zip` formats) + +--- + +## Why It Was Archived + +PTlibzippy was archived when: + +1. **Symbol conflict resolution matured** — The launcher's build system evolved to + handle zlib/libpng coexistence without a custom fork +2. **System zlib preferred** — Using the system's zlib package reduced maintenance + burden and ensured security patches were applied promptly +3. **Launcher archived** — When ProjT Launcher was archived, its dependency libraries + (including PTlibzippy) were archived alongside it +4. **MeshMC approach** — The successor launcher (MeshMC) uses system libraries or + vendored sources with different conflict resolution strategies + +--- + +## Building (for Reference) + +### CMake + +```bash +cd archived/ptlibzippy/ +mkdir build && cd build +cmake .. +make +make test +``` + +### With Symbol Prefixing + +```bash +cmake .. -DPTLIBZIPPY_PREFIX=pt_ +make +``` + +### Autotools + +```bash +cd archived/ptlibzippy/ +./configure +make +make test +make install +``` + +### Static-Only Build + +```bash +cmake .. -DPTLIBZIPPY_BUILD_SHARED=OFF +make +``` + +Note: Build success is not guaranteed since the archived code is not maintained. + +--- + +## File Index + +From the project `INDEX` file: + +``` +CMakeLists.txt cmake build file +ChangeLog history of changes +FAQ Frequently Asked Questions about zlib +INDEX file listing +Makefile dummy Makefile that tells you to ./configure +Makefile.in template for Unix Makefile +README project overview +configure configure script for Unix +make_vms.com makefile for VMS +test/example.c zlib usage examples for build testing +test/minigzip.c minimal gzip-like functionality for build testing +test/infcover.c inf*.c code coverage for build coverage testing +treebuild.xml XML description of source file dependencies +ptzippyconf.h zlib configuration header (template) +ptlibzippy.h zlib public API header + +amiga/ makefiles for Amiga SAS C +doc/ documentation for formats and algorithms +msdos/ makefiles for MSDOS +old/ legacy makefiles and documentation +os400/ makefiles for OS/400 +qnx/ makefiles for QNX +watcom/ makefiles for OpenWatcom +win32/ makefiles for Windows +``` + +--- + +## Ownership + +Maintained by `@YongDo-Hyun` as defined in `ci/OWNERS`: + +``` +/archived/ptlibzippy/ @YongDo-Hyun +``` |