netcdf-c/test_common.in
Dennis Heimbigner efdec07f3d Extend the netcdf API to support programmatic changes to the plugin search path
Replaces PR https://github.com/Unidata/netcdf-c/pull/3024
         and PR https://github.com/Unidata/netcdf-c/pull/3033

re: https://github.com/Unidata/netcdf-c/issues/2753

As suggested by Ed Hartnett, This PR extends the netcdf.h API to support programmatic control over the search path used to locate plugins.

I created several different APIs, but finally settled on the following API as being the simplest possible. It does have the disadvantage that it requires use of a global lock (not implemented) if used in a threaded environment.

Specifically, note that modifying the plugin path must be done "atomically". That is, in a multi-threaded environment, it is important that the sequence of actions involved in setting up the plugin path must be done by a single processor or in some other way as to guarantee that two or more processors are not simultaneously accessing the plugin path get/set operations.

As an example, assume there exists a mutex lock called PLUGINLOCK. Then any processor accessing the plugin paths should operate as follows:
````
lock(PLUGINLOCK);
nc_plugin_path_get(...);
<rebuild plugin path>
nc_plugin_path_set(...);
unlock(PLUGINLOCK);
````
## Internal Architecture

It is assumed here that there only needs to be a single set of plugin path directories that is shared by all filter code and is independent of any file descriptor; it is global in other words. This means, for example, that the path list for NCZarr and for HDF5 will always be the same.

However internally, processing the set of plugin paths depends on the particular NC_FORMATX value (NC_FORMATX_NC_HDF5 and NC_FORMATX_NCZARR, currently). So the *nc_plugin_path_set* function, will take the paths it is given and propagate them to each of the NC_FORMATX dispatchers to store in a way that is appropriate to the given dispatcher.

There is a complication with respect to the *nc_plugin_path_get* function. It is possible for users to bypass the netcdf API and modify the HDF5 plugin paths directly. This can result in an inconsistent plugin path between the value used by HDF5 and the global value used by netcdf-c. Since there is no obvious fix for this, we warn the user of this possibility and otherwise ignore it.

## Test Changes
* New tests<br>
    a. unit_test/run_pluginpaths.sh -- was created to test this new capability.<br>
    b. A new test utility has been added as *unit_test/run_dfaltpluginpath.sh* to test the default plugin path list.
* New test support utilities<br>
    a. unit_test/ncpluginpath.c -- report current state of the plugin path<br>
    b. unit_test/tst_pluginpaths.c -- test program to support run_pluginpaths.sh

## Documentation
* A new file -- docs/pluginpath.md -- provides documentation of the new API. It includes some
  material taken fro filters.md.

## Other Major Changes
1. Cleanup the whole plugin path decision tree. This is described in the *docs/pluginpath.md* document and summarized in Addendum 2 below.
2. I noticed that the ncdump/testpathcvt.sh had been disabled, so fixed and re-enabled it. This necessitated some significant changes to dpathmgr.c.

## Misc. Changes
1. Add some path manipulation utilities to netcf_aux.h
2. Fix some minor bugs in netcdf_json.h
3. Convert netcdf_json.h and netcdf_proplist.h to BUILT_SOURCE.
4. Add NETCDF_ENABLE_HDF5 as synonym for USE_HDF5
5. Fix some size_t <-> int conversion warnings.
6. Encountered and fixed the Windows \r\n problem in tst_pluginpaths.c.
7. Cleanup some minor CMakeLists.txt problems.
8. Provide an implementation of echo -n since it appears to not be
   available on all platforms.
9. Add a property list mechanism to pass environmental information to filters.
10. Cleanup Doxyfile.in
11. Fixed a memory leak in libdap2; surprised that I did not find this earlier.

## Addendum 1: Proposed API

The API makes use of a counted vector of strings representing the sequence of directories in the path. The relevant type definition is as follows.
````
typedef struct NCPluginList {size_t ndirs; char** dirs;} NCPluginList;
````

The API proposed in this PR looks like this (from netcdf-c/include/netcdf_filter.h).

* ````int nc_plugin_path_ndirs(size_t* ndirsp);````
    Arguments: *ndirsp* -- store the number of directories in this memory.

    This function returns the number of directories in the sequence if internal directories of the internal plugin path list.

* ````int nc_plugin_path_get(NCPluginList* dirs);````
    Arguments:  *dirs* -- counted vector for storing the sequence of directies in the internal path list.

    This function returns the current sequence of directories from the internal plugin path list. Since this function does not modify the plugin path, it does not need to be locked; it is only when used to get the path to be modified that locking is required.  If the value of *dirs.dirs* is NULL (the normal case), then memory is allocated to hold the vector of directories. Otherwise, use the memory of *dirs.dirs* to hold the vector of directories.

* ````int nc_plugin_path_set(const NCPluginList* dirs);````
    Arguments: *dirs* -- counted vector for providing the new sequence of directories in the internal path list.

    This function empties the current internal path sequence and replaces it with the sequence of directories argument. Using an *ndirs* argument of 0 will clear the set of plugin paths.

## Addendum 2: Build-Time and Run-Time Constants.

### Build-Time Constants
<table style="border:2px solid black;border-collapse:collapse">
<tr style="outline: thin solid;" align="center"><td colspan="4">Table showing the build-time computation of NETCDF_PLUGIN_INSTALL_DIR and NETCDF_PLUGIN_SEARCH_PATH.</td>
<tr style="outline: thin solid" ><th>--with-plugin-dir<th>--prefix<th>NETCDF_PLUGIN_INSTALL_DIR<th>NETCDF_PLUGIN_SEARCH_PATH
<tr style="outline: thin solid" ><td>undefined<td>undefined<td>undefined<td>PLATFORMDEFALT
<tr style="outline: thin solid" ><td>undefined<td>&lt;abspath-prefix&gt;<td>&lt;abspath-prefix&gt;/hdf5/lib/plugin<td>&lt;abspath-prefix&gt;/hdf5/lib/plugin&lt;SEP&gt;PLATFORMDEFALT
<tr style="outline: thin solid" ><td>&lt;abspath-plugins&gt;<td>N.A.<td>&lt;abspath-plugins&gt;<td>&lt;abspath-plugins&gt;&lt;SEP&gt;PLATFORMDEFALT
</table>

<table style="border:2px solid black;border-collapse:collapse">
<tr style="outline: thin solid" align="center"><td colspan="2">Table showing the computation of the initial global plugin path</td>
<tr style="outline: thin solid"><th>HDF5_PLUGIN_PATH<th>Initial global plugin path
<tr style="outline: thin solid"><td>undefined<td>NETCDF_PLUGIN_SEARCH_PATH
<tr style="outline: thin solid"><td>&lt;path1;...pathn&gt;<td>&lt;path1;...pathn&gt;
</table>
2024-10-18 19:23:59 -06:00

237 lines
8.0 KiB
Plaintext

# Copyright 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
# 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,
# 2015, 2016, 2017, 2018
# University Corporation for Atmospheric Research/Unidata.
# See netcdf-c/COPYRIGHT file for more info.
# Load only once
if test "x$TEST_COMMON_SH" = x ; then
export TEST_COMMON_SH=1
# Define various global constants
# Define various build and install paths
abs_top_srcdir=@abs_top_srcdir@
abs_top_builddir=@abs_top_builddir@
TOPSRCDIR="${abs_top_srcdir}"
TOPBUILDDIR="${abs_top_builddir}"
FP_ISCMAKE=@ISCMAKE@
FP_ISMSVC=@ISMSVC@
FP_WINVERMAJOR=@WINVERMAJOR@
FP_WINVERBUILD=@WINVERBUILD@
FP_ISCYGWIN=@ISCYGWIN@
FP_ISMINGW=@ISMINGW@
FP_ISMSYS=@ISMSYS@
FP_ISOSX=@ISOSX@
FP_ISREGEDIT=@ISREGEDIT@
FP_USEPLUGINS=@USEPLUGINS@
# Feature flags
FEATURE_HDF5=@HAS_HDF5@
FEATURE_PARALLEL=@HAS_PARALLEL@
# Define selected features of the build
FEATURE_HDF5=@HAS_HDF5@
FEATURE_FILTERTESTS=@DO_FILTER_TESTS@
FEATURE_BYTERANGE=@HAS_BYTERANGE@
FEATURE_ROS3=@HAS_HDF5_ROS3@
FEATURE_S3_AWS=@HAS_S3_AWS@
FEATURE_S3_INTERNAL=@HAS_S3_INTERNAL@
FEATURE_S3=@HAS_S3@
FEATURE_NCZARR=@HAS_NCZARR@
FEATURE_S3TESTS=@NETCDF_ENABLE_S3_TESTING@
FEATURE_NCZARR_ZIP=@HAS_NCZARR_ZIP@
FEATURE_LARGE_TESTS=@DO_LARGE_TESTS@
FEATURE_PLUGIN_INSTALL_DIR="@NETCDF_PLUGIN_INSTALL_DIR@"
FEATURE_PLUGIN_SEARCH_PATH="@NETCDF_PLUGIN_SEARCH_PATH@"
# Thredds-test server is currently disabled
#FEATURE_THREDDSTEST=1
# This is the Unidata S3 test bucket
# All S3 tests should use this to store intermediate results.
S3TESTBUCKET=@S3TESTBUCKET@
# This is the s3 path within the Unidata bucket;
# All S3 tests should use this to store intermediate results.
S3TESTSUBTREE=@S3TESTSUBTREE@
TESTUID=@TESTUID@
set -e
# Figure out various locations in the src/build tree.
# This is relatively fragile code and is essentially
# specific to netcdf-c. It does, however, have the virtue
# of isolating all this nonsense into one place.
# This will get somewhat simplified (I hope) when
# we move to a separate test_utilities directory
# This code is intended to provide constants
# for accessing various objects in the src/build
# tree(s) across multiple ways of building netcdf-c.
# Currently, the following build situations are supported.
# 1. Autoconf with make check: the src and build trees are the same
# 2. Autoconf with make distcheck: the src and build trees are distinct
# 3. Cmake on a *nix platform using e.g. gcc:
# the src and build trees are distinct.
# 4. Cmake on windows using cygwin or msys.
# The src and build trees are distinct.
#
# For now, an explicit build using the Visual C(++) compiler
# is not supported. The big issue is the handling of executables
# and the notion of a VS configuration/build type like Debug or Release.
# When using VS, executables are placed in a subdirectory of the
# build directory. That subdirectory is named by the configuration type.
# Thus one finds ncdump.exe in $top_builddir/ncdump/Debug instead of
# $top_builddir/ncdump. An additional issue is the extension of an
# executable: .exe vs nothing. This code attempts to figure out which is used.
#
# For possible future fixes, a placeholder is left in place in the
# following code named VS. If it were set to the build type, then,
# in theory, this code would work with Visual C. It is disabled for now.
#
# The goal, then, of this common code is to set up some useful
#constants for use in test shell scripts.
# 1. srcdir - absolute path to the source dir (e.g. ${top_srcdir}/ncgen)
# 2. top_srcdir - absolute path to the root of the source
# 3. top_builddir - absolute path to the root of the build directory;
# may be same as top_srcdir (e.g. #1).
# 4. builddir - absolute path of th the directory into which generated
# stuff (.nc, .cdl, etc) is stored.
# 5. execdir - absolute path of the directory into which executables are
# placed. For all but the VS case, execdir == builddir.
#
# The following are defined to support inter-directory references.
# 6. NCDUMP - absolute path to the ncdump.exe executable
# 7. NCCOPY - absolute path to the nccopy.exe executable
# 8. NCGEN - absolute path to ncgen.exe
# 9. NCGEN3 - absolute path to ncgen3.exe
#10. NCPATHCVT - absolute path to ncpathcvt.exe
# Allow global set -x mechanism for debugging.
if test "x$SETX" = x1 ; then set -x ; fi
# On MINGW, bash and other POSIX utilities use a mounted root directory,
# but executables compiled for Windows do not recognise the mount point.
# Here we ensure that Windows paths are used in tests of Windows executables.
system=`uname`
if test "x${system##MINGW*}" = x; then
alias pwd='pwd -W'
fi
# We assume that TOPSRCDIR and TOPBUILDDIR are defined
# At the top of this shell script
top_srcdir="$TOPSRCDIR"
top_builddir="$TOPBUILDDIR"
# Currently not used, but left as a Visual Studio placeholder.
# VS=Debug
# Set when using gdb
#DL=".libs/"
# srcdir may or may not be defined, but if not, then create it
if test "x$srcdir" = x ; then
# we need to figure out our directory
# pick off the last component as the relative name of this directory
srcdir=`pwd`
if test "x$srcdir" != "x$top_srcdir" ; then
current=`basename $srcdir`
srcdir="${top_srcdir}/$current"
fi
fi
# We also assume we are executing in builddir
builddir=`pwd`
# execdir is usually an alias for builddir
execdir="${builddir}"
# pick off the last component as the relative name of this directory
thisdir=`basename $srcdir`
WD=`pwd`
# Absolutize paths of interest
cd $srcdir; srcdir=`pwd` ; cd $WD
cd $top_srcdir; top_srcdir=`pwd` ; cd $WD
cd $builddir; builddir=`pwd` ; cd $WD
cd $top_builddir; top_builddir=`pwd` ; cd $WD
cd $execdir; execdir=`pwd` ; cd $WD
# For sun os
export srcdir top_srcdir builddir top_builddir execdir
# Figure out executable extension (probably a better way)
if test -e "${top_builddir}/ncdump${VS}/ncdump.exe" ; then
ext=".exe"
else
ext=""
fi
# We need to locate certain executables (and other things),
# capture absolute paths, and make visible
export NCDUMP="${abs_top_builddir}/ncdump${VS}/${DL}ncdump${ext}"
export NCCOPY="${abs_top_builddir}/ncdump${VS}/${DL}nccopy${ext}"
export NCGEN="${abs_top_builddir}/ncgen${VS}/${DL}ncgen${ext}"
export NCGEN3="${abs_top_builddir}/ncgen3${VS}/${DL}ncgen3${ext}"
export NCPATHCVT="${abs_top_builddir}/ncdump${VS}/${DL}ncpathcvt${ext}"
# Temporary hacks (until we have a test_utils directory)
# to locate certain specific test files
ncgen3c0="${abs_top_srcdir}/ncgen3/c0.cdl"
ncgenc0="${abs_top_srcdir}/ncgen/c0.cdl"
ncgenc04="${abs_top_srcdir}/ncgen/c0_4.cdl"
# Set LC_ALL
if test "x$FP_ISMSVC" = xyes || test "x$FP_ISCYGWIN" = xyes; then export LC_ALL="en_US.utf8"; fi
# Set HOME
if test "x$FP_ISMSVC" = xyes || test "x$FP_MINGW" = xyes; then
if test "x$HOME" = x ; then
HOME=`echo $USERPROFILE |tr '\\\' '/'`
export HOME
fi
fi
# OS/X and windows apparently have no echo -n option, so fake it
echon() {
${execdir}/../ncdump/echon -n $@
}
# Test for filter availability
avail() {
if test yes = `${execdir}/../ncdump/ncfilteravail $1` ; then return 0 ; else echo "filter $1 not available" ; return 1; fi
}
# Make sure we are in builddir (not execdir)
cd $builddir
# Parallel make can cause inter-test interference (mostly because of historical naming issues).
# As a protection against this, the isolate() function supports the creation of an
# isolation directory in which created products are stored.
# Cleanup can be accomplished by deleting the whole isolation directory.
# The name of the isolation directory is by convention "testdir_<random>".
# The isolation dir is created within the ${builddir} directory.
# The <random> is a generated 32 bit unsigned random integer to make the chance
# of collision very small.
# Process ID was not used because of the small but real chance of collision.
isolate() {
if test "x$ISOPATH" = x ; then
ISOTESTSET="${builddir}/testset_"
if test "x$NOISOPATH" = x ; then ISOTESTSET="${ISOTESTSET}${TESTUID}"; fi
ISODIR="$1"
ISOPATH="${ISOTESTSET}/$ISODIR"
rm -fr $ISOPATH
mkdir -p $ISOPATH
fi
}
fi #TEST_COMMON_SH