This guide shows how to build libzip from source. It assumes basic familiarity with using the command line and building software from source.
This guide uses cmake to invoke all required commands to be platform-independent. You can, of course, also use the commands appropriate for your platform directly.
libzip uses cmake to build.
You'll need zlib (at least version 1.1.2). It comes with most operating systems.
For supporting bzip2-compressed zip archives, you need bzip2.
For supporting lzma- and xz-compressed zip archives, you need liblzma which is part of xz (at least version 5.2).
For supporting zstd-compressed zip archives, you need zstd.
For command line editing support in the zip shell (zipsh), you need readline or editline.
For AES (encryption) support, you need one of these cryptographic libraries, listed in order of preference:
- Apple's CommonCrypto (available on macOS and iOS)
- Microsoft Windows Cryptography Framework
- OpenSSL (at least version 1.0)
- GnuTLS and Nettle (at least nettle 3.0)
If you don't want to use a library even if it is installed, you can
pass -DENABLE_<LIBRARY>=OFF to cmake, where <LIBRARY> is one of
COMMONCRYPTO, GNUTLS, or OPENSSL.
For running the tests, you need to have Python, nihtest, and CMocka installed.
For code coverage report of the test suite, you need to have lcov installed.
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.
How to install the dependencies depends on your operating system. On Linux, you can usually install them via your package manager; you will need to install the -dev packages for libraries. On macOS, you can use Homebrew or Mac Ports. On Windows, you can use vcpkg. Details on how to use these package managers is beyond the scope of this guide, but should be easy to find online.
The newest release can be found on the download page or on GitHub.
The version in the file name may differ, adjust the command accordingly.
cmake -E tar xf libzip-1.14.1.tar.xz
cd libzip-1.14.1cmake -E make_directory build
cd buildPlease note that building directly in the source directory is not supported. Always create a separate build directory as shown above.
cmake ..If you want to customize the build, you can pass additional parameters to cmake after .. in the form of -Dparameter=value. See below for some useful parameters:
BUILD_SHARED_LIBS
: set to ON or OFF to enable/disable building of shared libraries, defaults to ON
CMAKE_INSTALL_PREFIX
: for setting the installation path
CMAKE_C_FLAGS
: for setting custom compiler flags, for example -DCMAKE_C_FLAGS="-DMY_CUSTOM_FLAG"
DOCUMENTATION_FORMAT
: choose one of man, mdoc, and html for the installed documentation (default: decided by cmake depending on available tools)
LIBZIP_DO_INSTALL
: If you include libzip as a subproject, link it statically and do not want to let it install its files, set this variable to OFF. Defaults to ON.
LIMIT_LZMA_WINDOW
: If set to a number, limits the LZMA window size to that number of bytes. Without a limit, LZMA compression can use up to 4GiB of memory. Defaults to no limit.
You can also check the cmake FAQ for more information.
cmake --build .To check that libzip works as expected, run the test suite.
ctest -j20The number after -j specifies how many tests to run in parallel. 20 is a good default for modern systems.
cmake --install .Installing to the default location may require root privileges. You can specify a different installation location by passing -DCMAKE_INSTALL_PREFIX=/path/to/install to cmake in step 4.
To enable collecting code coverage, pass -DENABLE_COVERAGE=ON to cmake. After running the tests with ctest, run cmake --build . --target coverage to create the report in coverage/index.html.
Please note that this builds libzip with coverage gathering enabled, which has a noticeable performance impact. You should not use such a build in production.
For efficiency, libzip allocates buffers on the stack by default. These buffers are small enough to fit on the stack on modern systems, but especially on embedded systems, they might exhaust available stack space.
If you are compiling on a system with a small stack size, add
-DZIP_ALLOCATE_BUFFER to CMAKE_C_FLAGS. This causes libzip to allocate buffers on the heap instead. The performance impact should not be significant.
If you are building on a 32-bit Linux system it might be necessary
to define _FILE_OFFSET_BITS to 64. Your distro will need to provide
a fts.h file that is new enough to support this, or the build
will break in zipcmp.
The website uses Zensical.
Install it with pip install zensical.
To view the website locally, run ./support/serve and open http://localhost:8002 in your web browser.
Note: There was a bug in zensical versions 0.0.68 to 0.0.70 inclusive that prevented the website from being served correctly.