Skip to content

Latest commit

 

History

History
161 lines (93 loc) · 5.97 KB

INSTALL.md

File metadata and controls

161 lines (93 loc) · 5.97 KB

Building libzip

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.

Dependencies

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.

Building libzip

1. Download the source code.

The newest release can be found on the download page or on GitHub.

2. Unpack the source code and navigate to the source directory.

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.1

3. Create a build directory and navigate to it.

cmake -E make_directory build
cd build

Please note that building directly in the source directory is not supported. Always create a separate build directory as shown above.

4. Run cmake to configure the build system.

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.

5. Build libzip.

cmake --build .

6. Run the test suite (optional).

To check that libzip works as expected, run the test suite.

ctest -j20

The number after -j specifies how many tests to run in parallel. 20 is a good default for modern systems.

7. Install libzip (optional).

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.

Test Suite Code Coverage

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.

Special System Requirements

Small Stack Size

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.

32-bit Linux

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.

Building the Website

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.