mirror/netcdf-c
2
0
Fork 0
mirror of https://github.com/Unidata/netcdf-c.git synced 2024-12-27 08:49:16 +08:00
Code Issues Packages Projects Releases Wiki Activity
1ad0a53595
netcdf-c/libncpoco/README.md
Dennis Heimbigner 11fe00ea05 Add filter support to NCZarr 
Filter support has three goals:

1. Use the existing HDF5 filter implementations,
2. Allow filter metadata to be stored in the NumCodecs metadata format used by Zarr,
3. Allow filters to be used even when HDF5 is disabled

Detailed usage directions are define in docs/filters.md.

For now, the existing filter API is left in place. So filters
are defined using ''nc_def_var_filter'' using the HDF5 style
where the id and parameters are unsigned integers.

This is a big change since filters affect many parts of the code.

In the following, the terms "compressor" and "filter" and "codec" are generally
used synonomously.

### Filter-Related Changes:
* In order to support dynamic loading of shared filter libraries, a new library was added in the libncpoco directory; it helps to isolate dynamic loading across multiple platforms.
* Provide a json parsing library for use by plugins; this is created by merging libdispatch/ncjson.c with include/ncjson.h.
* Add a new _Codecs attribute to allow clients to see what codecs are being used; let ncdump -s print it out.
* Provide special headers to help support compilation of HDF5 filters when HDF5 is not enabled: netcdf_filter_hdf5_build.h and netcdf_filter_build.h.
* Add a number of new test to test the new nczarr filters.
* Let ncgen parse _Codecs attribute, although it is ignored.

### Plugin directory changes:
* Add support for the Blosc compressor; this is essential because it is the most common compressor used in Zarr datasets. This also necessitated adding a CMake FindBlosc.cmake file
* Add NCZarr support for the big-four filters provided by HDF5: shuffle, fletcher32, deflate (zlib), and szip
* Add a Codec defaulter (see docs/filters.md) for the big four filters.
* Make plugins work with windows by properly adding __declspec declaration.

### Misc. Non-Filter Changes
* Replace most uses of USE_NETCDF4 (deprecated) with USE_HDF5.
* Improve support for caching
* More fixes for path conversion code
* Fix misc. memory leaks
* Add new utility -- ncdump/ncpathcvt -- that does more or less the same thing as cygpath.
* Add a number of new test to test the non-filter fixes.
* Update the parsers
* Convert most instances of '#ifdef _MSC_VER' to '#ifdef _WIN32'
2021-09-02 17:04:26 -06:00

4.5 KiB
Raw Blame History

The cpoco Multi-Platform Dynamic-Loading Library

Description

The primary goal of the cpoco project is to provide a C language version of the poco multi-platform dynamic loading library. The poco libraries are written in C++.

The secondary goal of cpoco is to support dynamic loading of HDF5 filters by the netCDF C library.

Mutual Exclusion Support

Internally, cpoco (like poco) supports serialized access to the dynamic loading functions using mutual exclusion locks. For nix systems, this usually requires pthreads support.

In any case, it is possible to disable the use of mutual exclusion if you know you are operating in a single threaded environment: see the installation section below.

Implementataion Restrictions

Currently support is provided for the following systems.

  • libdl supporting operating systems: e.g. linux, os-x, cygwin.
  • Windows-32 api

Installation

Automake

Automake-based configuration is provided using ./configure is provided for systems supporting autoconf/automake.

Use this command to see the available options.

./configure --help

The most important options are these.

  • --disable-mutex -- disable using mutual exclusion (default is enabled)
  • --disable-pthread -- disable using pthreads (default is enabled if operating system provides it)
  • --enable-shared -- build a shared library (default is enabled)
  • --enable-static -- build a static library (default is enabled)
  • --prefix= -- defaults to /usr/local

Note that is --enable-shared is disabled, then the test program will not run because the test shared library (libcpt) cannot be built.

Use these commands to build, test, and install using autoconf.

# Invoke configure
./configure <options>
make all
# If testing is desired
make check
# Optional
make install

The are those shown by ./configure --help.

CMake

Cmake-based configuration is provided provided for systems supporting it. If building for windows, then this is the only option provided.

Use these commands to build using cmake.

# Create a build directory
rm -fr build
mkdir build
cd build
# Invoke cmake
cmake <flags> ..
cmake --build .
# If testing is desired
CTEST_OUTPUT_ON_FAILURE=1 cmake --build . --target test
# Optional
cmake --build . --target install

The are these:

  • -DENABLE_MUTEX -- use mutual exclusion (default is true)
  • -DENABLE_PTHREAD -- use pthreads (if available) (default is true)
  • -DCMAKE_INSTALL_PREFIX= -- installation directory (defaults to /usr/local or c:/Program Files)

Support

Author: Dennis Heimbigner
Organization: University Corporation for Atmospheric Research
Initial Release: 2015-9-28 Last Modified: 2018-03-27

Copyright: Copyright 2018, UCAR/Unidata; see COPYRIGHT file for copying and redistribution conditions. This code is Derived from the poco library (See Poco Information below).

Change Log

  1. (2016-09-28) Initial release.
  2. (2018-03-27) Updated to make fix some automake problems.

Poco Information

Poco License

Boost Software License - Version 1.0 - August 17th, 2003

Permission is hereby granted, free of charge, to any person or organization obtaining a copy of the software and accompanying documentation covered by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works of the Software, and to permit third-parties to whom the Software is furnished to do so, all subject to the following:

The copyright notices in the Software and this entire statement, including the above license grant, this restriction and the following disclaimer, must be included in all copies of the Software, in whole or in part, and all derivative works of the Software, unless such copies or derivative works are solely in the form of machine-executable object code generated by a source language processor.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.