Merge pull request #2530 from Unidata/v4.9.1-wellspring.wif

Merge subset of v4.9.1 files back into main development branch

CMakeLists.txt

@@ -31,7 +31,7 @@ set(PACKAGE "netCDF" CACHE STRING "")
 
 SET(NC_VERSION_MAJOR 4)
 SET(NC_VERSION_MINOR 9)
-SET(NC_VERSION_PATCH 1)
+SET(NC_VERSION_PATCH 2)
 SET(NC_VERSION_NOTE "-development")
 SET(netCDF_VERSION ${NC_VERSION_MAJOR}.${NC_VERSION_MINOR}.${NC_VERSION_PATCH}${NC_VERSION_NOTE})
 SET(VERSION ${netCDF_VERSION})

RELEASE_NOTES.md

@@ -7,6 +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 20, 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, `netcdf-c/docs/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).

configure.ac

@@ -10,7 +10,7 @@
 AC_PREREQ([2.59])
 
 # Initialize with name, version, and support email address.
-AC_INIT([netCDF],[4.9.1-development],[support-netcdf@unidata.ucar.edu],[netcdf-c])
+AC_INIT([netCDF],[4.9.2-development],[support-netcdf@unidata.ucar.edu],[netcdf-c])
 
 ##
 # Prefer an empty CFLAGS variable instead of the default -g -O2.
@@ -21,15 +21,15 @@ AC_INIT([netCDF],[4.9.1-development],[support-netcdf@unidata.ucar.edu],[netcdf-c
 
 AC_SUBST([NC_VERSION_MAJOR]) NC_VERSION_MAJOR=4
 AC_SUBST([NC_VERSION_MINOR]) NC_VERSION_MINOR=9
-AC_SUBST([NC_VERSION_PATCH]) NC_VERSION_PATCH=1
+AC_SUBST([NC_VERSION_PATCH]) NC_VERSION_PATCH=2
 AC_SUBST([NC_VERSION_NOTE]) NC_VERSION_NOTE="-development"
 
 ##
 # These linker flags specify libtool version info.
 # See http://www.gnu.org/software/libtool/manual/libtool.html#Libtool-versioning
 # for information regarding incrementing `-version-info`.
 # These values should match those in CMakeLists.txt
-AC_SUBST([netCDF_SO_VERSION]) netCDF_SO_VERSION=20:0:1
+AC_SUBST([netCDF_SO_VERSION]) netCDF_SO_VERSION=21:0:2
 
 #####
 # Set some variables used to generate a libnetcdf.settings file,

dap4_test/Makefile.am

@@ -5,6 +5,7 @@
 
 # Put together AM_CPPFLAGS and AM_LDFLAGS.
 include $(top_srcdir)/lib_flags.am
+LDADD = ${top_builddir}/liblib/libnetcdf.la
 
 # Un comment to use a more verbose test driver
 #SH_LOG_DRIVER = $(SHELL) $(top_srcdir)/test-driver-verbose
@@ -15,7 +16,7 @@ include $(top_srcdir)/lib_flags.am
 # Note which tests depend on other tests. Necessary for make -j check.
 TEST_EXTENSIONS = .sh
 
-LDADD = ${top_builddir}/liblib/libnetcdf.la
+
 AM_CPPFLAGS += -I$(top_srcdir)/liblib
 AM_CPPFLAGS += -I$(top_srcdir)/libdap4
 AM_CPPFLAGS += -DTOPSRCDIR=${abs_top_srcdir}

dap4_test/d4test_common.sh

@@ -17,14 +17,14 @@ fi
 
 # Define input paths
 WD=`pwd`
-cd ${srcdir}/daptestfiles; DAPTESTFILES=`pwd` ; cd ${WD}
-cd ${srcdir}/dmrtestfiles; DMRTESTFILES=`pwd` ; cd ${WD}
-cd ${srcdir}/cdltestfiles; CDLTESTFILES=`pwd` ; cd ${WD}
-cd ${srcdir}/baseline; BASELINE=`pwd` ; cd ${WD}
-cd ${srcdir}/baselineraw; BASELINERAW=`pwd` ; cd ${WD}
-cd ${srcdir}/baselineremote; BASELINEREM=`pwd` ; cd ${WD}
-cd ${srcdir}/baselinehyrax; BASELINEH=`pwd` ; cd ${WD}
-cd ${builddir}/baselinethredds; BASELINETH=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/daptestfiles; DAPTESTFILES=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/dmrtestfiles; DMRTESTFILES=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/cdltestfiles; CDLTESTFILES=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/baseline; BASELINE=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/baselineraw; BASELINERAW=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/baselineremote; BASELINEREM=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/baselinehyrax; BASELINEH=`pwd` ; cd ${WD}
+cd ${top_srcdir}/dap4_test/baselinethredds; BASELINETH=`pwd` ; cd ${WD}
 
 setresultdir() {
 rm -fr ${builddir}/$1

dap4_test/test_data.sh

@@ -5,7 +5,7 @@ if test "x$srcdir" = x ; then srcdir=`pwd`; fi
 
 set -e
 
-. ${srcdir}/d4test_common.sh
+. ${top_srcdir}/dap4_test/d4test_common.sh
 
 echo "test_data.sh:"
 

docs/Doxyfile.developer

@@ -38,7 +38,7 @@ PROJECT_NAME           = netCDF-C
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 4.9.1-development
+PROJECT_NUMBER         = 4.9.2-development
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

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 \

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.
 
 ~~~~

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.  
+

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
 ------------------------------

ncgen/ncgen.1

@@ -205,7 +205,7 @@ Use NC_DISKLESS mode to create the file totally in memory
 before persisting it to disk.
 .IP "\fB-W\fP \fRmaxwholevarsize\fP"
 Set wholevarsizem where if total number of elements is less than maxwholevarsize
-then updata a variable using a single nc_put_var. Requires
+then update a variable using a single nc_put_var. Requires
 that the variable has no unlimited dimensions.
 .IP "\fB-x\fP"
 Don't initialize data with fill values.  This can speed up creation of

nczarr_test/CMakeLists.txt

@@ -35,7 +35,8 @@ FILE(REMOVE ${CMAKE_CURRENT_BINARY_DIR}/run_unknown.1)
 
 FILE(GLOB COPY_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.sh
 ${CMAKE_CURRENT_SOURCE_DIR}/ref*.cdl
-${CMAKE_CURRENT_SOURCE_DIR}/ref*.txt)
+${CMAKE_CURRENT_SOURCE_DIR}/ref*.txt
+${CMAKE_CURRENT_SOURCE_DIR}/ref*.zmap)
 
 FILE(COPY ${COPY_FILES} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/ FILE_PERMISSIONS OWNER_WRITE OWNER_READ OWNER_EXECUTE)
 

nczarr_test/Makefile.am

@@ -212,7 +212,7 @@ clean-local:
 	rm -fr rcmiscdir ref_power_901_constants.file 
 
 
-DISTCLEANFILES = findplugin.sh test_quantize.c run_specific_filters.sh run_filterinstall.sh
+DISTCLEANFILES = findplugin.sh test_quantize.c run_specific_filters.sh run_filterinstall.sh run_unknown.sh test_filter_avail.c
 
 # If valgrind is present, add valgrind targets.
 @VALGRIND_CHECK_RULES@

nczarr_test/ref_jsonconvention.zmap

@@ -1,4 +1,4 @@
-[0] /.zattrs : (354) |{"globalfloat": 1, "globalfloatvec": [1,2], "globalchar": "abc", "globalillegal": "[ [ 1.0, 0.0, 0.0 ], [ 0.0, 1.0, 0.0 ], [ 0.0, 0.0, 1.0 ", "_NCProperties": "version=2,netcdf=4.9.1-development,nczarr=2.0.0", "_nczarr_attr": {"types": {"globalfloat": "<f8", "globalfloatvec": "<f8", "globalchar": ">S1", "globalillegal": ">S1", "_NCProperties": ">S1"}}}|
+[0] /.zattrs : (354) |{"globalfloat": 1, "globalfloatvec": [1,2], "globalchar": "abc", "globalillegal": "[ [ 1.0, 0.0, 0.0 ], [ 0.0, 1.0, 0.0 ], [ 0.0, 0.0, 1.0 ", "_NCProperties": "version=2,netcdf=4.9.2-development,nczarr=2.0.0", "_nczarr_attr": {"types": {"globalfloat": "<f8", "globalfloatvec": "<f8", "globalchar": ">S1", "globalillegal": ">S1", "_NCProperties": ">S1"}}}|
 [1] /.zgroup : (129) |{"zarr_format": 2, "_nczarr_superblock": {"version": "2.0.0"}, "_nczarr_group": {"dims": {"d1": 1}, "vars": ["v"], "groups": []}}|
 [3] /v/.zarray : (202) |{"zarr_format": 2, "shape": [1], "dtype": "<i4", "chunks": [1], "fill_value": -2147483647, "order": "C", "compressor": null, "filters": null, "_nczarr_array": {"dimrefs": ["/d1"], "storage": "chunked"}}|
 [4] /v/.zattrs : (296) |{"varjson1": {"key1": [1,2,3], "key2": {"key3": "abc"}}, "varjson2": [[1.0,0.0,0.0],[0.0,1.0,0.0],[0.0,0.0,1.0]], "varvec1": "1.0, 0.0, 0.0", "varvec2": [0.,0.,1.], "_ARRAY_DIMENSIONS": ["d1"], "_nczarr_attr": {"types": {"varjson1": ">S1", "varjson2": ">S1", "varvec1": ">S1", "varvec2": ">S1"}}}|

nczarr_test/run_scalar.sh

@@ -3,7 +3,7 @@
 if test "x$srcdir" = x ; then srcdir=`pwd`; fi 
 . ../test_common.sh
 
-. "$srcdir/test_nczarr.sh"
+. "$top_srcdir/nczarr_test/test_nczarr.sh"
 
 # This shell script tests support for the NC_STRING type
 
@@ -34,9 +34,9 @@ deletemap $zext $nczarrfile
 
 # Create alternate ref files
 echo "*** create pure zarr file"
-${NCGEN} -4 -b -o "$zarrurl" $srcdir/ref_scalar.cdl
+${NCGEN} -4 -b -o "$zarrurl" $top_srcdir/nczarr_test/ref_scalar.cdl
 echo "*** create nczarr file"
-${NCGEN} -4 -b -o "$nczarrurl" $srcdir/ref_scalar.cdl
+${NCGEN} -4 -b -o "$nczarrurl" $top_srcdir/nczarr_test/ref_scalar.cdl
 
 echo "*** read purezarr"
 ${NCDUMP} -n ref_scalar $zarrurl > tmp_scalar_zarr0_${zext}.cdl
@@ -46,11 +46,11 @@ ${NCDUMP} -n ref_scalar $nczarrurl > tmp_scalar_nczarr_${zext}.cdl
 ${ZMD} -h $nczarrurl > tmp_scalar_nczarr_${zext}.txt
 
 echo "*** verify"
-diff -bw ref_scalar.cdl tmp_scalar_nczarr_${zext}.cdl
+diff -bw $top_srcdir/nczarr_test/ref_scalar.cdl tmp_scalar_nczarr_${zext}.cdl
 
 # Fixup
 zarrscalar tmp_scalar_zarr0_${zext}.cdl tmp_scalar_zarr_${zext}.cdl
-diff -bw ref_scalar.cdl tmp_scalar_zarr_${zext}.cdl
+diff -bw $top_srcdir/nczarr_test/ref_scalar.cdl tmp_scalar_zarr_${zext}.cdl
 }
 
 testcase file