Disclaimer

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
A "Mission Critical Application" is any application in which failure of the Intel Product could result, directly or indirectly, in personal injury or death. SHOULD YOU PURCHASE OR USE INTEL'S PRODUCTS FOR ANY SUCH MISSION CRITICAL APPLICATION, YOU SHALL INDEMNIFY AND HOLD INTEL AND ITS SUBSIDIARIES, SUBCONTRACTORS AND AFFILIATES, AND THE DIRECTORS, OFFICERS, AND EMPLOYEES OF EACH, HARMLESS AGAINST ALL CLAIMS COSTS, DAMAGES, AND EXPENSES AND REASONABLE ATTORNEYS' FEES ARISING OUT OF, DIRECTLY OR INDIRECTLY, ANY CLAIM OF PRODUCT LIABILITY, PERSONAL INJURY, OR DEATH ARISING IN ANY WAY OUT OF SUCH MISSION CRITICAL APPLICATION, WHETHER OR NOT INTEL OR ITS SUBCONTRACTOR WAS NEGLIGENT IN THE DESIGN, MANUFACTURE, OR WARNING OF THE INTEL PRODUCT OR ANY OF ITS PARTS.

Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.
The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or go to: http://www.intel.com/design/literature.htm

Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. Go to: http://www.intel.com/products/processor_number/

BlueMoon, BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Inside, Core Inside, i960, Intel, the Intel logo, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel Sponsors of Tomorrow., the Intel Sponsors of Tomorrow. logo, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, InTru, the InTru logo, InTru soundmark, Itanium, Itanium Inside, MCS, MMX, Moblin, Pentium, Pentium Inside, skoool, the skoool logo, Sound Mark, The Journey Inside, vPro Inside, VTune, Xeon, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries.
* Other names and brands may be claimed as the property of others.

Microsoft, Windows, Visual Studio, Visual C++, and the Windows logo are trademarks, or registered trademarks of Microsoft Corporation in the United States and/or other countries.

Java is a registered trademark of Oracle and/or its affiliates.

Copyright(C) 2014-2016 Intel Corporation. All rights reserved.

Optimization Notice

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel.

Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804

License Definitions

By downloading and installing this product, you hereby agree that the accompanying materials are being provided to you under the terms and conditions of the End User License Agreement for the Intel® Integrated Performance Primitives (Intel® IPP) product previously accepted by you.

System Requirements

Recommended hardware:

Hardware requirements:

Software requirements:

For more information please see Intel® IPP System Requirements.

How to Build Zlib with Intel® Integrated Performance Primitives Library

Intel® IPP library contains several functions in data compression domain, which allow to speed up well-known Zlib library (http://zlib.net) in both data compression and decompression operations. Look "Intel® Integrated Performance Primitives for Intel® Architecture/Reference Manual. Volume 1: Signal Processing/Data Compression Functions/Dictionary-Based Compression Functions/ZLIB Coding Functions"

To utilize these functions, the source code of several Zlib functions must be updated (patched) with Intel IPP functions calls instead of parts of original code, prior to library build.

This document describes the required steps for Zlib source code preparation and library build.

Prerequisites

Zlib library has several stable versions in its repository: v.1.2.5.3, v.1.2.6.1, v.1.2.7.3 and v.1.2.8. You may want to update and speed up a particular Zlib version, which is used in your application, or on your operating system. For that, Intel® IPP product provides four source code patch files applicable to specific versions of Zlib.

Downloading, Patching and Build on Linux* and OS X*

Download

To start build process you need to download Zlib source code file from Zlib site (http://zlib.net). Below is the table of download addresses for specific Zlib versions, which can be updated with Intel® IPP library function calls.

Download tar file from specified address to working directory. Unpack downloaded archive with the following command on Linux*/OS X* systems.

$ tar xvf <archive file name>

This command will create the directory with the name zlib-<version> in your working directory, where <version> is selected Zlib version number from 1.2.5.3 to 1.2.8.

Patch

Go to zlib-<version> directory.

Apply corresponding source code patch file zlib-<version>.patch from Intel® IPP product distribution

$ patch -p1 < "path to corresponding patch file"

For example to patch Zlib v.1.2.6.1, go to zlib-1.2.6.1 directory and type

$ patch -p1 < ../zlib-1.2.6.1.patch

command, if patch files are located in upper directory.

The following diagnostics messages are produced by "patch" tool, if patching process is succeeded:

patching file adler32.c
patching file crc32.c
patching file deflate.c
patching file inflate.c
patching file inftrees.h
patching file trees.c

If something goes wrong, for example, if adler32.c file is previously changed (non original), the diagnostics messages are the following:

patching file adler32.c
Hunk #1 FAILED at 5.
patching file crc32.c
patching file deflate.c
patching file inflate.c
patching file inftrees.h
patching file trees.c

Configuration and Build Procedure

After successful patch, you may create makefile for building process. Basically, you need to

  • Add WITH_IPP definition to compiler command line;

  • Add $IPPROOT/include directory to the list of header files search for compiler;

  • Add Intel® IPP libraries to the list of ld input files.

With standard Zlib configure/make sequence it can be done using the following commands on Linux* (32-bit example):

# Build dynamic Zlib library with static Intel IPP linkage on Linux*
$ export CFLAGS="-m32 -DWITH_IPP -I$IPPROOT/include"
$ export LDFLAGS="$IPPROOT/lib/ia32/libippdc.a $IPPROOT/lib/ia32/libipps.a $IPPROOT/lib/ia32/libippcore.a"
$ ./configure
$ make shared

As on OS X* there is no separation between 32- and 64-bit libraries, you don’t need to specify different set of libraries for different architectures, and command list is as follows (32-bit example):

# Build dynamic Zlib library with static Intel IPP linkage on OS X*
$ export CFLAGS="-m32 -DWITH_IPP -I$IPPROOT/include"
$ export LDFLAGS="$IPPROOT/lib/libippdc.a $IPPROOT/lib/libipps.a $IPPROOT/lib/libippcore.a"
$ ./configure
$ make shared

Here, -m32 option specifies IA32 target CPU architecture. For Intel® 64 architecture the compiler option should be -m64.

The above commands assume that $IPPROOT environment variable points to head of Intel IPP location. $IPPROOT can be set manually, as

$ export IPPROOT=<composer_loc>/ipp

where <composer_loc> is location of Intel® Composer or Intel® Parallel Studio suite.

Another (and, better) way is to set up Composer/Parallel Studio environment using environment setup file

$ source <composer_loc>/bin/compilervars.sh <arch>

where <arch> is ia32 (for 32-bit tools), or intel64 for 64-bit tools. For example, for 64-bit tools from Intel® Parallel Studio 2016 package, the command line should be

$ source /opt/intel/compilers_and_libraries_2016/linux/bin/compilervars.sh intel64
Note
The conditional compilation statements, used for Zlib source code files modification, allow to build original version of Zlib from the same source code files. For that, you need to build Zlib library without modification of CFLAGS and LDFLAGS. If WITH_IPP definition doesn’t exist in compiler options, Zlib source code files are compiled as it was no patching.

Static and Dynamic Intel® IPP Libraries Linking

You can build libz dynamic shared object with both static or dynamic linking to Intel IPP libraries. Different linkage modes have their advantages and disadvantages. For example, static linking to Intel IPP provides target object (libz.so, or libz.dylib in our case) independence of environment, easy transportation from one computer to another. On the other hand, statically linked object has bigger size and can’t benefit from newer (updated) version of Intel IPP without re-linking.

The libz dynamic libraries, linked statically with Intel IPP, are self-sufficient. It means that when you build an application using these libraries, you don’t need to add Intel IPP libraries to the linker command line (unless your application uses Intel IPP apart of libz). All references to IPP functions are already resolved, and required Intel IPP functions code is inside libz dynamic library.

Build Zlib with Static Intel® IPP Libraries Linking

The linker flags specified by LDFLAGS environment variable

$ export LDFLAGS="$IPPROOT/lib/intel64/libippdc.a $IPPROOT/lib/intel64/libipps.a \
                  $IPPROOT/lib/intel64/libippcore.a"

make Linux* linker to use static linking to Intel IPP libraries (.a files). The independence of result dynamic library libz.so of Intel IPP libraries can be checked by Linux* "ldd" tool.

For example,

$ ldd libz.so
        linux-vdso.so.1 =>  (0x00007fff885fe000)
        libc.so.6 => /lib64/libc.so.6 (0x00007fb169e38000)
        /lib64/ld-linux-x86-64.so.2 (0x00007fb16a503000)

You can see that libz.so dynamic library depends on system dynamic libraries only. The size of resulting libz library in this case will be more than 700 KBytes.

On OS X* the similar tool is called "otool". For example on OS X*,

$ otool -L libz.dylib
libz.dylib:
        /usr/local/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.5)
        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)

To build some application with such kind of library is simple. For example,

$ cc -o zlib_test -Izlib/include zlib_test.c -L. -lz

Here, zlib/include is a directory where zlib header files exist (in most cases zlib.h and zconf.h are required), "-L." means that Linux* linker will be searching next libraries in the current directory, "-lz" means that linker will look for libz.so file (shared linking is default method on most Linux* systems).

To run built application on Linux* system, you need to modify LD_LIBRARY_PATH environment variable, which describes the search path for dynamic libraries:

$ export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
$ ./zlib_test

On OS X* systems the corresponding environment variable is DYLD_LIBRARY_PATH:

$ export DYLD_LIBRARY_PATH=.:$DYLD_LIBRARY_PATH
$ ./zlib_test

Build Zlib with Dynamic Intel® IPP Libraries Linking

Sometimes, you may want to build libz dynamic library with linkage to dynamic Intel IPP libraries. This is, for example, if you know that libz will be used on a computer, which will always have pre-installed and properly set dynamic Intel IPP libraries. Or, you may want to minimize file size of libz dynamic library, or, to decrease the summary amount of RAM size required for several application(s) which use libz.

In this case, the following set of commands will build libz.so library with dynamic linking to the Intel IPP libraries (64-bit example).

$ source /opt/intel/compilers_and_libraries_2016/linux/bin/compilervars.sh intel64
$ export CFLAGS="-m64 -DWITH_IPP -I$IPPROOT/include"
$ export LDFLAGS="-L$IPPROOT/lib/intel64 -lippdc -lipps -lippcore"
$ ./configure
$ make shared

Let’s check how libz.so is built:

$ ldd libz.so
        linux-vdso.so.1 =>  (0x00007fff347fe000)
        libc.so.6 => /lib64/libc.so.6 (0x00007f9210e35000)
        libippdc.so.9.0 => /opt/intel/compilers_and_libraries_2016.1.125/linux/ipp/lib/intel64/libippdc.so.9.0 (0x00007f9210c2f000)
        libipps.so.9.0 => /opt/intel/compilers_and_libraries_2016.1.125/linux/ipp/lib/intel64/libipps.so.9.0 (0x00007f92109ed000)
        libippcore.so.9.0 => /opt/intel/compilers_and_libraries_2016.1.125/linux/ipp/lib/intel64/libippcore.so.9.0 (0x00007f92107e1000)
        /lib64/ld-linux-x86-64.so.2 (0x00007f921143d000)
        libdl.so.2 => /lib64/libdl.so.2 (0x00007f92105dc000)
        libm.so.6 => /lib64/libm.so.6 (0x00007f92102da000)

On your computer actual library location name and addresses can be different, e.g. instead of …/compilers_and_libraries_2016.1.125… you may have different package number and location. The above "ldd" output shows that libz.so shared object is built dynamically with Intel IPP libippdc.so, libipps.so and libippcore.so dynamic libraries.

On OS X* system the corresponding set of command will be:

$ source /opt/intel/compilers_and_libraries_2016/mac/bin/compilervars.sh intel64
$ export CFLAGS="-m64 -DWITH_IPP -I$IPPROOT/include"
$ export LDFLAGS="-L$IPPROOT/lib -lippdc -lipps -lippcore"
$ ./configure
$ make shared
$ otool -L libz.dylib

On a target computer, before libz library is used, you need to properly set paths to Intel IPP dynamic libraries. In Linux* operating system it is done by modifying LD_LIBRARY_PATH environment variable. In OS X* operating system you will need to modify DYLD_LIBRARY_PATH.

Using Static libz.a Library to Build User Applications

During standard "configure/make" process the makefile creates libz.a static library with libz compiled functions. You may want to use this static library with your application instead of using libz shared object.

Static libz.a library contains unresolved external references to Intel IPP library functions, so, when you build your application with static libz.a library, you still need to solve the problem of linking to Intel IPP libraries.

In this case the question still exists, what Intel IPP library linking to use, static or dynamic.

For static Intel IPP linkage you must use the following link options

libz.a $IPPROOT/lib/<arch>/libippdc.a $IPPROOT/lib/<arch>/libipps.a $IPPROOT/lib/<arch>/libippcore.a

where <arch> is either ia32 or intel64 depending on what kind of application (32-bit or 64-bit) you are going to build.

On OS X* the corresponding linker options are

libz.a $IPPROOT/lib/libippdc.a $IPPROOT/lib/libipps.a $IPPROOT/lib/libippcore.a

For dynamic Intel IPP linkage the following options must be used

libz.a -L$IPPROOT/lib/<arch> -lippdc -lipps -lippcore

Or, on OS X*

libz.a -L$IPPROOT/lib -lippdc -lipps -lippcore

Downloading, Patching and Build on Windows*

Downloading of Zlib source code files for Windows* is done using the same URL addresses as for Linux*. However, the patching and build process on Windows* differ.

Unpacking Zlib Tarball

To get Zlib source code files on Windows* computer, you need

Patch

There is no standard system tools for patching on Windows, so you need to use 3-rd party tools. For example, http://gnuwin32.sourceforge.net/packages/patch.htm from Free Software Foundation.

With this tool you need to use the following command line options

> patch.exe -p1 --binary < <patch file location>

"--binary" sub-switch here is important to avoid confusion because of Linux*/Windows* "end-of-line" character difference.

Example for zlib-1.2.7.3 is below:

> tar.exe xvf zlib-1.2.7.3.tar.gz
> cd zlib-1.2.7.3
> patch.exe -p1 --binary < ..\zlib-1.2.7.3.patch
patching file adler32.c
patching file crc32.c
patching file deflate.c
patching file inflate.c
patching file inftrees.h
patching file trees.c

Build Zlib With Intel® IPP on Windows*

There is no "configure" tool for Zlib Windows* build. Instead, you may want to use "nmake" file Makefile.msc from "zlib\win32" directory. To do that, you need to start Microsoft* Visual Studio* command-line window according to target application architecture (win32 or x64) and to execute the following command from root of Zlib source code tree (below are 32-bit examples)

> nmake -f win32\Makefile.msc LOC="-DWITH_IPP -I\"%IPPROOT%\include\"" ^
       LDFLAGS="-nologo -incremental:no ^
       -opt:ref /LIBPATH:\"%IPPROOT%\lib\ia32_win\" ^
       ippdcmt.lib ippsmt.lib ippcoremt.lib"

for static linking of Intel IPP libraries, or

> nmake -f win32\Makefile.msc LOC="-DWITH_IPP -I\"%IPPROOT%\include\"" ^
        LDFLAGS="-nologo -incremental:no ^
        -opt:ref /LIBPATH:\"%IPPROOT%\lib\ia32_win\" ^
        ippdc.lib ipps.lib ippcore.lib"

for dynamic linking.

In the first case the "nmake" creates zlib1.dll file not depending on dynamic Intel IPP libraries. In the second, zlib1.dll depends on ippdc-x.y.dll, ipps-x.y.dll and ippcore-x.y.dll, where "x.y" major and minor version numbers of corresponding Intel IPP library.

Build User Application with Static zlib.lib library

Like in Linux*/OS X* case, you may want to build your application with zlib statically linked to the application. Zlib build procedure, along with zlib1.dll, creates static zlib library zlib.lib. It can be used with application object files to be built statically.

If you want Intel® IPP libray to be built statically into your application, you need to specify

"%IPPROOT%\lib\<arch>\ippdcmt.lib"  "%IPPROOT%\lib\<arch>\ippsmt.lib"  "%IPPROOT%\lib\<arch>\ippcoremt.lib"

input files in the command line to Microsoft* linker.

For dynamic Intel IPP library build, you need to choose other libraries from Intel IPP library directory:

"%IPPROOT%\lib\<arch>\ippdc.lib"  "%IPPROOT%\lib\<arch>\ipps.lib"  "%IPPROOT%\lib\<arch>\ippcore.lib"

These libraries are just references to Intel IPP dynamic libraries (DLLs).

Note
For Windows* build procedure it is important to use double quotes """ around %IPPROOT%, because by default Intel® IPP is installed in "Program Files(x86)" directory. Its name contains space and, without quotes around, this name can confuse Microsoft* compiler and/or linker.

How to Verify Zlib with Intel® Integrated Performance Primitives Library

For smoke testing or verification of the newly built library, you can use small tests/examples, which are supplied with Zlib distribution.

Verification on Linux* and OS X*

Makefile, generated by configure utility, can be used to test library build with Makefile’s test target.

Dynamic libz Library and Dynamic Tests

In general, command lines to build and test are (64-bit Linux example on zlib 1.2.8)

$ export CFLAGS="-m64 -DWITH_IPP -I$IPPROOT/include"
$ export LDFLAGS="$IPPROOT/lib/intel64/libippdc.a \
        $IPPROOT/lib/intel64/libipps.a $IPPROOT/lib/intel64/libippcore.a"
$ ./configure
$ make testshared
hello world
zlib version 1.2.8 = 0x1280, compile flags = 0xa9
uncompress(): hello, hello!
gzread(): hello, hello!
gzgets() after gzseek:  hello!
inflate(): hello, hello!
large_inflate(): OK
after inflateSync(): hello, hello!
inflate with dictionary: hello, hello!
                *** zlib shared test OK ***

Static libz Library and Static Tests

For static tests you need to use slightly different approach, because in original Zlib makefile LDFLAGS variable is not used for static build. TEST_LDFLAGS argument in "make" command line must be used instead.

So, the command lines should be (32-bit Linux* example)

$ export CFLAGS="-m32 -DWITH_IPP -I$IPPROOT/include"
$ ./configure
$ make teststatic TEST_LDFLAGS="libz.a $IPPROOT/lib/ia32/libippdc.a \
                     $IPPROOT/lib/ia32/libipps.a $IPPROOT/lib/ia32/libippcore.a"
hello world
zlib version 1.2.8 = 0x1280, compile flags = 0x55
uncompress(): hello, hello!
gzread(): hello, hello!
gzgets() after gzseek:  hello!
inflate(): hello, hello!
large_inflate(): OK
after inflateSync(): hello, hello!
inflate with dictionary: hello, hello!
                *** zlib test OK ***

Test libz on OS X*

Below are the same example command lines for OS X*

$ export CFLAGS="-m64 -DWITH_IPP -I$IPPROOT/include"
$ export LDFLAGS="$IPPROOT/lib/libippdc.a $IPPROOT/lib/libipps.a \
                  $IPPROOT/lib/libippcore.a"
$ ./configure
$ make testshared
hello world
zlib version 1.2.8 = 0x1280, compile flags = 0xa9
uncompress(): hello, hello!
gzread(): hello, hello!
gzgets() after gzseek:  hello!
inflate(): hello, hello!
large_inflate(): OK
after inflateSync(): hello, hello!
inflate with dictionary: hello, hello!
                *** zlib shared test OK ***

and

$ export CFLAGS="-m32 -DWITH_IPP -I$IPPROOT/include"
$ ./configure
$ make teststatic TEST_LDFLAGS="libz.a $IPPROOT/lib/libippdc.a \
                     $IPPROOT/lib/libipps.a $IPPROOT/lib/libippcore.a"
hello world
zlib version 1.2.8 = 0x1280, compile flags = 0x95
uncompress(): hello, hello!
gzread(): hello, hello!
gzgets() after gzseek:  hello!
inflate(): hello, hello!
large_inflate(): OK
after inflateSync(): hello, hello!
inflate with dictionary: hello, hello!
                *** zlib test OK ***

Verification on Windows*

Command line to build and test dynamic Zlib library on Windows* is

nmake -f win32\Makefile.msc LOC="-DWITH_IPP -I\"%IPPROOT%\include\"" ^
    LDFLAGS="-nologo -incremental :no -opt:ref ^
    /LIBPATH:\"%IPPROOT%\lib\ia32_win\" ^
    ippdcmt.lib ippsmt.lib ippcoremt.lib" testdll

Microsoft (R) Program Maintenance Utility Version 14.00.23506.0
Copyright (C) Microsoft Corporation.  All rights reserved.

        example_d
zlib version 1.2.5.3 = 0x1253, compile flags = 0x55
uncompress(): hello, hello!
gzread(): hello, hello!
gzgets() after gzseek:  hello!
inflate(): hello, hello!
large_inflate(): OK
after inflateSync(): hello, hello!
inflate with dictionary: hello, hello!
        echo hello world | minigzip_d | minigzip_d -d
hello world