Merge pull request #169 from magnusuMET/netcdfreqsdocs

Add docs on installing netcdf

Author: magnusuMET

.typos.toml

@@ -5,4 +5,5 @@ extend-exclude = ["netcdf-src/source", "netcdf-sys"]
 extend-ignore-identifiers-re = [
   "Dout",
   "is_ambigous", # Remove when deprecated item is removed
+  "typ",
 ]

README.md

@@ -31,13 +31,14 @@ All variable data is read into a contiguous buffer, or into an [ndarray](https:/
 
 ## Building
 
-This crate depends on `libnetcdf`, but a static build from source is also supported, which can be enabled using the `static` feature.
+This crate depends on the C library [`netcdf-c`](https://www.unidata.ucar.edu/netcdf/) which must be installed on the machine, along with libraries such as `hdf5` which `netcdf-c` depends on. For some platforms you might have to set the environment variable `NETCDF_DIR` which needs to point at the installation of `netcdf-c` you wish to use.
 
-The crate is built on several platforms using github actions, and is currently known to build form from source on all major platforms (linux, macos, windows (gnu+msvc)), and through the package installers `conda` and `apt`.
+An alternative to using the system libraries is to enable `static` feature of this crate (`cargo add netcdf --features static`), which compiles `libnetcdf` from source. The `static` feature requires `cmake`, a `c++` compiler and more to be installed on the build machine.
 
-If during compilation there is an error in building the `hdf5` crate, consider using the `static` feature which will include a compatible version of both `netcdf` and `hdf5`. This is likely to be an issue [upstream](https://github.com/aldanor/hdf5-rust/issues/262).
+The crate is built on several platforms using github actions, and is currently known to build form from source on all major platforms (linux, macos, windows (gnu+msvc)), and through the package installers `conda` and `apt`. Please see the github workflows for tips on how to install `netcdf`.
 
-### Building without `libnetcdf` or building statically
+
+### Building `libnetcdf` statically
 1. `git clone https://github.com/georust/netcdf`
 2. `git submodule update --init --recursive`
 3. `cargo build --features static`

netcdf-sys/build.rs

@@ -172,16 +172,18 @@ fn from_utf8_to_trimmed_string(bytes: &[u8]) -> String {
 }
 
 impl NcInfo {
-    fn guess() -> Self {
-        todo!()
-    }
-    fn from_path(path: &Path) -> Self {
-        Self {
+    fn from_path(path: &Path) -> Option<Self> {
+        let includedir = path.join("include");
+        if !includedir.exists() {
+            return None;
+        }
+
+        Some(Self {
             version: None,
             includedir: path.join("include"),
             libdir: path.join("lib"),
             libname: "netcdf".to_owned(),
-        }
+        })
     }
     fn gather_from_ncconfig(search_path: Option<&Path>) -> Option<Self> {
         let path = if let Some(search_path) = search_path {
@@ -232,6 +234,40 @@ fn _check_consistent_version_linked() {
     todo!()
 }
 
+fn determine_ncinfo() -> NcInfo {
+    let nc_dir = std::env::var_os("NETCDF_DIR")
+        .or_else(|| std::env::var_os("NetCDF_DIR"))
+        .map(PathBuf::from);
+
+    if let Some(nc_dir) = nc_dir.as_ref() {
+        #[allow(unused_mut)]
+        if let Some(info) = NcInfo::gather_from_ncconfig(Some(nc_dir)) {
+            return info;
+        }
+        if let Some(info) = NcInfo::from_path(nc_dir) {
+            return info;
+        }
+        #[cfg(windows)]
+        {
+            // Conda requires Library prefix
+            let nc_dir = nc_dir.join("Library");
+            if let Some(info) = NcInfo::gather_from_ncconfig(Some(&nc_dir)) {
+                return info;
+            }
+            if let Some(info) = NcInfo::from_path(&nc_dir) {
+                return info;
+            }
+        }
+    }
+
+    if let Some(info) = NcInfo::gather_from_ncconfig(None) {
+        return info;
+    }
+
+    panic!("A system version of libnetcdf could not be found. Consider installing to some default location, use the environment variable NETCDF_DIR (remember to restart the shell), or prefer building the static version of libnetcdf by enabling the `static` feature on `netcdf-sys` or `netcdf`"
+            );
+}
+
 fn main() {
     println!("cargo::rerun-if-changed=build.rs");
 
@@ -240,26 +276,19 @@ fn main() {
         let netcdf_lib = std::env::var("DEP_NETCDFSRC_LIB").unwrap();
         let netcdf_path = PathBuf::from(std::env::var_os("DEP_NETCDFSRC_SEARCH").unwrap());
 
-        info = NcInfo::gather_from_ncconfig(Some(&netcdf_path.join("..")))
-            .unwrap_or_else(|| NcInfo::from_path(&netcdf_path.join("..")));
+        let mut linfo = NcInfo::gather_from_ncconfig(Some(&netcdf_path.join("..")));
+        if linfo.is_none() {
+            linfo = NcInfo::from_path(&netcdf_path.join(".."))
+        }
+
+        info = linfo.expect("The library path should be determined by this point");
 
         println!("cargo::rustc-link-search=native={}", netcdf_path.display());
         println!("cargo::rustc-link-lib=static={netcdf_lib}");
     } else {
         println!("cargo::rerun-if-env-changed=NETCDF_DIR");
 
-        let nc_dir = std::env::var_os("NETCDF_DIR")
-            .or_else(|| std::env::var_os("NetCDF_DIR"))
-            .map(PathBuf::from);
-
-        #[cfg(windows)]
-        let nc_dir = nc_dir.map(|d| d.join("Library"));
-
-        info = if let Some(nc_dir) = nc_dir.as_ref() {
-            NcInfo::gather_from_ncconfig(Some(nc_dir)).unwrap_or_else(|| NcInfo::from_path(nc_dir))
-        } else {
-            NcInfo::gather_from_ncconfig(None).unwrap_or_else(NcInfo::guess)
-        };
+        info = determine_ncinfo();
 
         println!("cargo::rustc-link-search={}", info.libdir.display());
         println!("cargo::rustc-link-lib={}", &info.libname);

netcdf/src/lib.rs

@@ -14,7 +14,14 @@
 //!
 //! For more information see:
 //! * [The official introduction to `netCDF`](https://docs.unidata.ucar.edu/nug/current/netcdf_introduction.html)
-//! * [The `netCDF-c` repository](https://github.com/Unidata/netcdf-c)
+//! * [The `NetCDF-c` repository](https://github.com/Unidata/netcdf-c)
+//!
+//! # Installing netcdf-c
+//!
+//! This crate depends on [Unidata NetCDF-c](https://github.com/Unidata/netcdf-c) and dependencies
+//! of this library (such as hdf5).
+//! An alternative to the system libraries is to use the bundled sources of netcdf by using the `static` feature of this crate. This will require build utilities such as `cmake`, `c++` compiler and more.
+//!
 //!
 //! # Examples
 //!

netcdf/src/variable.rs

@@ -19,7 +19,7 @@ use crate::utils::{checked_with_lock, with_lock};
 ///
 /// This type is used for retrieving data from a variable.
 /// Metadata on the `netCDF`-level can be retrieved using e.g.
-/// [`fill_value`](Self::fill_value), [`endinanness`](Self::endianness).
+/// [`fill_value`](Self::fill_value), [`endianness`](Self::endianness).
 /// Use [`attributes`](Self::attribute) to get additional metadata assigned
 /// by the data producer. This crate will not apply any of the transformations
 /// given by such attributes (e.g. `add_offset` and `scale_factor` are NOT considered).