From 6754be12238f55f98afc855b6b4460c37c7bf264 Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Mon, 3 Oct 2022 15:40:51 -0600 Subject: [PATCH 1/8] Add blank filter quickstart guide file. --- docs/filter_quickstart.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/filter_quickstart.md diff --git a/docs/filter_quickstart.md b/docs/filter_quickstart.md new file mode 100644 index 0000000000..e69de29bb2 From 62f39e2eb3f130d709a5fb78d14c1ed07f529ee3 Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Mon, 3 Oct 2022 17:49:19 -0600 Subject: [PATCH 2/8] Updated release notes. --- RELEASE_NOTES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 035877eabc..b570daa2cd 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -7,6 +7,7 @@ This file contains a high-level description of this package's evolution. Release ## 4.9.1 - T.B.D. +* [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). From a0184d7678dc41527432385d4f718b4d42d72fce Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Wed, 5 Oct 2022 13:31:49 -0600 Subject: [PATCH 3/8] Working towards writing the quick start for plugins and integrating it into doxygen. --- docs/Doxyfile.in | 2 +- docs/all-error-codes.md | 2 +- docs/filter_quickstart.md | 9 +++++++++ docs/known_problems.md | 4 +--- 4 files changed, 12 insertions(+), 5 deletions(-) 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 index e69de29bb2..4073be02ec 100644 --- a/docs/filter_quickstart.md +++ b/docs/filter_quickstart.md @@ -0,0 +1,9 @@ +NetCDF-4 Filter QuickStart +============================== + + + +NetCDF-4 Filter QuickStart {#nc_filters_quickstart} +============================== + +For full Filters documentation, see \ref filters. \ No newline at end of file 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 ------------------------------ From 4eb601dbac8894a3d3f3899b7506569d98870389 Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Wed, 5 Oct 2022 15:28:50 -0600 Subject: [PATCH 4/8] Roughed in initial quickstart --- docs/filter_quickstart.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/filter_quickstart.md b/docs/filter_quickstart.md index 4073be02ec..72c25b2b94 100644 --- a/docs/filter_quickstart.md +++ b/docs/filter_quickstart.md @@ -1,9 +1,31 @@ NetCDF-4 Filter QuickStart ============================== +\tableofcontents + NetCDF-4 Filter QuickStart {#nc_filters_quickstart} ============================== -For full Filters documentation, see \ref filters. \ No newline at end of file +> For full **Filters** documentation, see \ref filters. + +Overview {#nc_filters_qs_overview} +------------------------------- + +The `libnetcdf.so` library cannot talk to plugin libraries directly. Instead, it requires an "interface" library, which acts as a go-between. This interface library is built by the netCDF library, if `blosc` is detected at configure/build time. + +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. + From 1ba435edd855529a1d3c998323161e75cc4a0309 Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Thu, 6 Oct 2022 15:34:08 -0600 Subject: [PATCH 5/8] Working on filter quickstart document. --- docs/filter_quickstart.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/filter_quickstart.md b/docs/filter_quickstart.md index 72c25b2b94..cc8bce519a 100644 --- a/docs/filter_quickstart.md +++ b/docs/filter_quickstart.md @@ -10,10 +10,20 @@ NetCDF-4 Filter QuickStart {#nc_filters_quickstart} > For full **Filters** documentation, see \ref filters. -Overview {#nc_filters_qs_overview} -------------------------------- -The `libnetcdf.so` library cannot talk to plugin libraries directly. Instead, it requires an "interface" library, which acts as a go-between. This interface library is built by the netCDF library, if `blosc` is detected at configure/build time. +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 {#nc_filters_qs_building} +---------------------------------- + + +Run-time {#nc_filters_qs_runtime} +--------------------------------- + + + +Example Workflow {#nc_filters_qs_workflow_example} +-------------------------------------------------- From scratch, the steps to get this to work are as follows, and assumes `libhdf5` was installed. From d28922a2f5ad79596668026550bbcf892c605828 Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Tue, 11 Oct 2022 11:15:06 -0600 Subject: [PATCH 6/8] Continuing to flesh out the quick-start guide. --- docs/filter_quickstart.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/filter_quickstart.md b/docs/filter_quickstart.md index cc8bce519a..198f6a9846 100644 --- a/docs/filter_quickstart.md +++ b/docs/filter_quickstart.md @@ -1,4 +1,4 @@ -NetCDF-4 Filter QuickStart +2NetCDF-4 Filter QuickStart ============================== \tableofcontents @@ -10,19 +10,26 @@ 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.** -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 {#nc_filters_qs_building} +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 ``. + -Run-time {#nc_filters_qs_runtime} +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 {#nc_filters_qs_workflow_example} +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. From 8f1d1034fb35d46e3317f1e669627df8274d0f00 Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Tue, 11 Oct 2022 16:17:29 -0600 Subject: [PATCH 7/8] Further editing. --- docs/filter_quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/filter_quickstart.md b/docs/filter_quickstart.md index 198f6a9846..f60a3392cb 100644 --- a/docs/filter_quickstart.md +++ b/docs/filter_quickstart.md @@ -1,4 +1,4 @@ -2NetCDF-4 Filter QuickStart +NetCDF-4 Filter QuickStart ============================== \tableofcontents From c4fd240f39c47f2b2d21fbca840a3770b15526da Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Wed, 19 Oct 2022 12:22:38 -0600 Subject: [PATCH 8/8] Updated RELEASE_NOTES --- RELEASE_NOTES.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 98ab749789..7702e3a02e 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -7,7 +7,14 @@ 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] 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.