Merge pull request #2531 from WardF/filter_quickstart_guide.wif

Add draft filter quickstart guide

Author: WardF

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

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