diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 7702e3a02e..753b582877 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -16,6 +16,7 @@ This file contains a high-level description of this package's evolution. Release #### Changes +* [Enhancement][Documentation] Add Plugins Quick Start Guide. See [GitHub #2524](https://github.com/Unidata/netcdf-c/pull/2524) for more information. * [Enhancement] Add new entries in `netcdf_meta.h`, `NC_HAS_BLOSC` and `NC_HAS_BZ2`. See [Github #2511](https://github.com/Unidata/netcdf-c/issues/2511) and [Github #2512](https://github.com/Unidata/netcdf-c/issues/2512) for more information. * [Enhancement] Add new options to `nc-config`: `--has-multifilters`, `--has-stdfilters`, `--has-quantize`, `--plugindir`. See [Github #2509](https://github.com/Unidata/netcdf-c/pull/2509) for more information. * [Bug Fix] Fix some errors detected in PR 2497. [PR #2497](https://github.com/Unidata/netcdf-c/pull/2497) . See [Github #2503](https://github.com/Unidata/netcdf-c/pull/2503). diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 6900f274c9..60308ab345 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -814,12 +814,12 @@ INPUT = @abs_top_srcdir@/docs/mainpage.dox \ @abs_top_srcdir@/docs/all-error-codes.md \ @abs_top_srcdir@/docs/inmemory.md \ @abs_top_srcdir@/docs/filters.md \ + @abs_top_srcdir@/docs/filter_quickstart.md \ @abs_top_srcdir@/docs/byterange.dox \ @abs_top_srcdir@/docs/nczarr.md \ @abs_top_srcdir@/docs/notes.md \ @abs_top_srcdir@/docs/building-with-cmake.md \ @abs_top_srcdir@/docs/FAQ.md \ - @abs_top_srcdir@/docs/known_problems.md \ @abs_top_srcdir@/docs/COPYRIGHT.md \ @abs_top_srcdir@/docs/credits.md \ @abs_top_srcdir@/docs/tutorial.dox \ diff --git a/docs/all-error-codes.md b/docs/all-error-codes.md index 97bd421477..b80301d160 100644 --- a/docs/all-error-codes.md +++ b/docs/all-error-codes.md @@ -77,7 +77,7 @@ may occur. # NetCDF-4 Error Codes {#nc4-error-codes} NetCDF-4 uses all error codes from NetCDF-3 (see section [NetCDF-3 Error -Codes](#NetCDF_002d3-Error-Codes)). The following additional error codes +Codes](#nc3-error-codes)). The following additional error codes were added for new errors unique to netCDF-4. ~~~~ diff --git a/docs/filter_quickstart.md b/docs/filter_quickstart.md new file mode 100644 index 0000000000..f60a3392cb --- /dev/null +++ b/docs/filter_quickstart.md @@ -0,0 +1,48 @@ +NetCDF-4 Filter QuickStart +============================== + +\tableofcontents + + + +NetCDF-4 Filter QuickStart {#nc_filters_quickstart} +============================== + +> For full **Filters** documentation, see \ref filters. + +**The `libnetcdf.so` library cannot talk to plugin libraries directly. Instead, it requires an "interface" library, which acts as a go-between. The interface libraries are built by the netCDF libraries, when the underlying plugin libraries are detected during configure/build.** + +Building and Installing the Interface Libraries {#nc_filters_qs_building} +---------------------------------- + +When configuring netcdf via either the `configure` script or via `cmake`, you'll need to specify the location to install the interface libraries, as follows: + +* configure: `--with-plugin-dir=` +* cmake: `-DPLUGIN_INSTALL_DIR=` + +After compiling and installing `libnetcdf`, the interface libraries for those filters detected will be installed in the user-specified ``. + + +Using the Interface Libraries at Run-time {#nc_filters_qs_runtime} +--------------------------------- + +For historical reasons, `libnetcdf` uses the environmental variable `HDF5_PLUGIN_PATH` to local the interface libraries at run-time. + + +Example Workflow (blosc) {#nc_filters_qs_workflow_example} +-------------------------------------------------- + +From scratch, the steps to get this to work are as follows, and assumes `libhdf5` was installed. + +1. Install the filter library, and the associate development headers. +2. Configure netCDF with `--enable-plugins` and `--with-plugin-dir=$HOME/netcdf-plugins` +3. Ensure `blosc` is specified in the generated `libnetcdf.settings` file. +4. Run make, make install. + +Once built and installed, set the environmental variable `HDF5_PLUGIN_PATH=$HOME/netcdf-plugins`. + +The reason this works is because: + +1. NetCDF builds the interface library. +2. `ncdump` knows where to find the interface library because `HDF5_PLUGIN_PATH` is set. + diff --git a/docs/known_problems.md b/docs/known_problems.md index 07318f2f79..624da8c57d 100644 --- a/docs/known_problems.md +++ b/docs/known_problems.md @@ -3,9 +3,7 @@ Known Problems with netCDF 4.3.0 -------------------------------- - -- [clang compiler (default on OSX 10.9 Mavericks) detects error - building ncgen3](#clang-ncgen3) +cd Known Problems with netCDF 4.2 ------------------------------