netcdf-c/libncpoco/README.md

# 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](http://www.unidata.ucar.edu/netcdf/).

# 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](#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.
```bash
./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=<installation directory> -- 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.
```bash
# Invoke configure
./configure <options>
make all
# If testing is desired
make check
# Optional
make install
```
The <options> 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.
```bash
# 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 <flags> are these:

* -DENABLE_MUTEX -- use mutual exclusion (default is true)
* -DENABLE_PTHREAD -- use pthreads (if available) (default is true)
* -DCMAKE_INSTALL_PREFIX=<path> -- 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](#poco-information) below).

# Change Log

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

# Poco Information

* Base poco version: 1.7.5 (2016-08-29)
* Poco web page: http://pocoproject.org


## 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.
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-03 07:04:26 +08:00			`# 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](http://www.unidata.ucar.edu/netcdf/).`

			`# 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](#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.`
			```bash
			`./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=<installation directory> -- 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.`
			```bash
			`# Invoke configure`
			`./configure <options>`
			`make all`
			`# If testing is desired`
			`make check`
			`# Optional`
			`make install`
			```
			The <options> 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.`
			```bash
			`# 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 <flags> are these:`

			`* -DENABLE_MUTEX -- use mutual exclusion (default is true)`
			`* -DENABLE_PTHREAD -- use pthreads (if available) (default is true)`
			`* -DCMAKE_INSTALL_PREFIX=<path> -- 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](#poco-information) below).`

			`# Change Log`

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

			`# Poco Information`

			`* Base poco version: 1.7.5 (2016-08-29)`
			`* Poco web page: http://pocoproject.org`


			`## 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.`