Installation¶
zfp consists of three distinct parts: a compression library written in C,
a set of C++ header files that implement compressed arrays and corresponding
C wrappers, and a set of C and C++ examples. The main compression codec is
written in C and should conform to both the ISO C89 and C99 standards.
The C++ array classes are implemented entirely in header files and can be
included as is, but since they call the compression library, applications
must link with libzfp
.
On Linux, macOS, and MinGW, zfp is easiest compiled using gcc and gmake. CMake support is also available, e.g., for Windows builds. See below for instructions on GNU and CMake builds.
zfp has successfully been built and tested using these compilers:
- gcc versions 4.4.7, 4.7.3, 4.8.5, 4.9.4, 5.5.0, 6.1.0, 6.4.0, 7.1.0, 7.3.0, 8.1.0
- icc versions 15.0.6, 16.0.4, 17.0.2, 18.0.2, 19.0.0
- clang versions 3.9.1, 4.0.0, 5.0.0, 6.0.0
- MinGW version 5.3.0
- Visual Studio versions 14 (2015), 15 (2017)
zfp conforms to various language standards, including C89, C99, C++98, C++11, and C++14.
NOTE: zfp requires 64-bit compiler and operating system support.
GNU Builds¶
To compile zfp using gcc without OpenMP, type:
make
from the zfp root directory. This builds libzfp
as a static
library as well as utilities and example programs. To enable OpenMP
parallel compression, type:
make ZFP_WITH_OPENMP=1
CMake Builds¶
To build zfp using CMake on Linux or macOS, start a Unix shell and type:
mkdir build
cd build
cmake ..
make
To also build the examples, replace the cmake line with:
cmake -DBUILD_EXAMPLES=ON ..
By default, CMake builds will attempt to locate and use OpenMP. To disable OpenMP, type:
cmake -DZFP_WITH_OPENMP=OFF ..
To build zfp using Visual Studio on Windows, start a DOS shell, cd to the top-level zfp directory, and type:
mkdir build
cd build
cmake ..
cmake --build . --config Release
This builds zfp in release mode. Replace ‘Release’ with ‘Debug’ to build zfp in debug mode. See the instructions for Linux on how to change the cmake line to also build the example programs.
Testing¶
To test that zfp is working properly, type:
make test
or using CMake:
ctest
If the compilation or regression tests fail, it is possible that some of
the macros in the file Config
have to be adjusted. Also, the tests
may fail due to minute differences in the computed floating-point fields
being compressed, which will be indicated by checksum errors. If most
tests succeed and the failures result in byte sizes and error values
reasonably close to the expected values, then it is likely that the
compressor is working correctly.
Build Targets¶
To specify which components to build, set the macros below to 1
(GNU make) or ON
(CMake), e.g.,
make BUILD_UTILITIES=1 BUILD_EXAMPLES=0
or using CMake
cmake -DBUILD_UTILITIES=ON -DBUILD_EXAMPLES=OFF ..
Regardless of the settings below, libzfp
will always be built.
-
BUILD_CFP
¶ Build
libcfp
for C bindings to compressed arrays. Default: off.
-
BUILD_UTILITIES
¶ Build zfp command-line utility for compressing binary files. Default: on.
-
BUILD_EXAMPLES
¶ Build code examples. Default: off.
-
BUILD_TESTING
¶ Build testzfp and (when on the develop branch) unit tests. Default: on.
-
BUILD_SHARED_LIBS
¶ Build
libzfp.so
andlibcfp.so
shared objects. On macOS, theSOFLAGS
line in theConfig
file may have to be uncommented when compiling with GNU make. CMake default: on. GNU make default: off.
Compile-Time Macros¶
The behavior of zfp can be configured at compile time via a set of macros in the same manner that build targets are specified, e.g.,
cmake -DZFP_WITH_OPENMP=OFF ..
-
ZFP_INT64
¶
-
ZFP_INT64_SUFFIX
¶
-
ZFP_UINT64
¶
-
ZFP_UINT64_SUFFIX
¶ 64-bit signed and unsigned integer types and their literal suffixes. Platforms on which
long int
is 32 bits wide may requirelong long int
as type andll
as suffix. These macros are relevant only when compiling in C89 mode. When compiling in C99 mode, integer types are taken fromstdint.h
. Defaults:long int
,l
,unsigned long int
, andul
, respectively.
-
ZFP_WITH_OPENMP
¶ CMake and GNU make macro for enabling or disabling OpenMP support. CMake builds will by default enable OpenMP when available. Set this macro to 0 or OFF to disable OpenMP support. For GNU builds, OpenMP is disabled by default. Set this macro to 1 or ON to enable OpenMP support. See also OMPFLAGS in
Config
in case the compiler does not recognize-fopenmp
. NOTE: clang currently does not support OpenMP on macOS. CMake default: on. GNU make default: off.
-
ZFP_WITH_CUDA
¶ CMake macro for enabling or disabling CUDA support for GPU compression and decompression. When enabled, CUDA and a compatible host compiler must be installed. For a full list of compatible compilers, please consult the NVIDIA documentation. If a CUDA installation is in the user’s path, it will be automatically found by CMake. Alternatively, the CUDA binary directory can be specified using the
CUDA_BIN_DIR
environment variable. CMake default: off. GNU make default: off and ignored.
-
ZFP_WITH_ALIGNED_ALLOC
¶ Use aligned memory allocation in an attempt to align compressed blocks on hardware cache lines. Default: undefined/off.
-
ZFP_WITH_CACHE_TWOWAY
¶ Use a two-way skew-associative rather than direct-mapped cache. This incurs some overhead that may be offset by better cache utilization. Default: undefined/off.
-
ZFP_WITH_CACHE_FAST_HASH
¶ Use a simpler hash function for cache line lookup. This is faster but may lead to more collisions. Default: undefined/off.
-
ZFP_WITH_CACHE_PROFILE
¶ Enable cache profiling to gather and print statistics on cache hit and miss rates. Default: undefined/off.
-
BIT_STREAM_WORD_TYPE
¶ Unsigned integer type used for buffering bits. Wider types tend to give higher performance at the expense of lower bit rate granularity. For portability of compressed files between little and big endian platforms,
BIT_STREAM_WORD_TYPE
should be set touint8
. Default:uint64
.
-
ZFP_BIT_STREAM_WORD_SIZE
¶ CMake macro for indirectly setting
BIT_STREAM_WORD_TYPE
. Valid values are 8, 16, 32, 64. Default: 64.
-
BIT_STREAM_STRIDED
¶ Enable support for strided bit streams that allow for non-contiguous memory layouts, e.g., to enable progressive access. Default: undefined/off.
-
CFP_NAMESPACE
¶ Macro for renaming the outermost cfp namespace, e.g., to avoid name clashes. Default: cfp.