Merge branch 'v4.9.1-wellspring.wif' into v4.9.1-rc1-release.wif

Unidata · Oct 19, 2022 · 4cae0c5 · 4cae0c5
2 parents 0ecd1d9 + f2471be
commit 4cae0c5
Show file tree

Hide file tree

Showing 5 changed files with 60 additions and 6 deletions.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -7,8 +7,16 @@ This file contains a high-level description of this package's evolution. Release
 
 ## 4.9.1 - T.B.D.
 
-### 4.9.1 - Release Candidate 1 - October 18, 2022
+### 4.9.1 - Release Candidate 1 - October 19, 2022
 
+#### Known Issues
+
+* A test in the `main` branch of `netcdf-cxx4` is broken by this rc; this will bear further investigation, but not being treated as a roadblock for the release candidate.
+* The new document, `filter_quickstart.md` is in rough-draft form.
+
+#### 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
@@ -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
@@ -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
@@ -0,0 +1,48 @@
+NetCDF-4 Filter QuickStart
+==============================
+
+\tableofcontents
+
+<!-- double header is needed to workaround doxygen bug -->
+
+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=<absolutely directory>`
+* cmake: `-DPLUGIN_INSTALL_DIR=<absolutely directory>`
+
+After compiling and installing `libnetcdf`, the interface libraries for those filters detected will be installed in the user-specified `<absolute directory>`.
+
+
+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
@@ -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
 ------------------------------