libzip Documentation

libzip is a C library designed for reading, creating, and modifying Zip archives. It is designed to be efficient, small, and stable, with a focus on data integrity (not creating corrupt files or deleting data even during errors).

Key Features:

• Data Sources: Read archives and file data from files or memory buffers.
• Large Archives: Supports Zip64 for large archives.
• Compression Algorithms: Supports Deflate, bzip2, LZMA, and zstd.
• Encryption: Supports Winzip AES and legacy PKWARE encryption.
• Error Recovery: Ability to revert unsaved changes.

To cross-compile libzip for Android, use the provided do.sh script. You may need to modify do.sh to specify a custom NDK directory or to adjust build parameters.

Prerequisites

You can prepare your development machine in two ways:

1. Manual Setup: Install the necessary prerequisites on your host machine (refer to docker/Dockerfile for the full list of required packages).
2. Docker (Recommended): Use Docker to avoid installing prerequisites on your host machine. You only need Docker installed. For detailed instructions on using the Docker method, see the Usage section in docker/Dockerfile.

# Example: Running the cross-compilation script
./do.sh

libzip is available through most major package managers depending on your operating system:

• Linux/Unix: Usually available as libzip or libzip-dev via your distribution's package manager.
• macOS: Available via Homebrew or Mac Ports.
• Windows: Available via vcpkg.

For building and installing libzip from source, refer to the INSTALL.md file in the repository.

To install the built libzip files, run cmake --install ..

Note: Installing to default system locations may require root privileges. You can specify a custom installation path during the configuration step using -DCMAKE_INSTALL_PREFIX=/path/to/install.

After building, you can verify the installation by running the test suite using ctest. You can specify the number of parallel jobs using the -j flag to speed up execution.

ctest -j20

libzip provides comprehensive documentation and reference material:

• Man Pages: The primary documentation is provided via man pages. You can find the libzip(3) man page, which serves as the entry point for all other documentation.
• HTML Documentation: Available at libzip.org or within the man/ directory of the repository.
• Source Examples: Practical usage examples are located in the examples/ and src/ subdirectories of the repository.
• API Changes: For information on API updates and migration guidance, consult API-CHANGES.md.

To build libzip from source, use cmake to configure the build system and then invoke the build command. This process involves downloading the source, creating a build directory, configuring with cmake, building, and optionally running tests or installing.

All dependencies except cmake and zlib are optional. If they are not found, the corresponding features will be disabled, but libzip will still build and work.

# 1. Unpack source
cmake -E tar xf libzip-1.14.1.tar.xz
cd libzip-1.14.1

# 2. Create build directory
cmake -E make_directory build
cd build

# 3. Configure
cmake ..

# 4. Build
cmake --build .

To collect code coverage during testing, enable it during the configuration step with -DENABLE_COVERAGE=ON. After running tests with ctest, build the coverage target to generate an HTML report.

Warning: Builds with coverage enabled should not be used in production.

cmake .. -DENABLE_COVERAGE=ON
ctest -j20
cmake --build . --target coverage
# Report is located at coverage/index.html

When running cmake .., you can customize the build using -Dparameter=value flags.

Common configuration parameters include:

• BUILD_SHARED_LIBS: Set to ON or OFF to enable/disable shared libraries (defaults to ON).
• CMAKE_INSTALL_PREFIX: Sets the installation path.
• DOCUMENTATION_FORMAT: Choose man, mdoc, or html for installed documentation.
• LIBZIP_DO_INSTALL: Set to OFF if including libzip as a subproject and you want to prevent it from installing its files (defaults to ON).

To use custom CFLAGS, set them in the environment before running cmake:

CFLAGS=-DMY_CUSTOM_FLAG cmake ..

cmake .. -DBUILD_SHARED_LIBS=OFF -DCMAKE_INSTALL_PREFIX=/custom/path

If you have a library installed but do not want libzip to use it, you can explicitly disable it by passing -DENABLE_<LIBRARY>=OFF to cmake.

Supported libraries for this flag include:

• COMMONCRYPTO
• GNUTLS
• OPENSSL

By default, libzip allocates small buffers on the stack for efficiency. On systems with very limited stack space (e.g., some embedded systems), this may cause stack exhaustion.

To force libzip to allocate buffers on the heap instead, add -DZIP_ALLOCATE_BUFFER to your CFLAGS during compilation.

CFLAGS=-DZIP_ALLOCATE_BUFFER cmake ..

When building on a 32-bit Linux system, you may need to define _FILE_OFFSET_BITS to 64 to ensure compatibility with fts.h in zipcmp.

CFLAGS="-D_FILE_OFFSET_BITS=64" cmake ..