Merge pull request #181 from aldanor/feature/doc-cfg

Experimental docs.rs changes

Author: aldanor

.github/workflows/ci.yml

@@ -37,6 +37,18 @@ jobs:
           command: ${{matrix.command}}
           args: "${{matrix.command == 'fmt' && '--all -- --check' || '-- -D warnings'}}"
 
+  doc: # This task should mirror the procedure on docs.rs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with: {submodules: true}
+      - name: Install Rust (${{matrix.rust}})
+        uses: actions-rs/toolchain@v1
+        with: {toolchain: nightly, profile: minimal, override: true}
+      - name: Document workspace
+        run: env RUSTDOCFLAGS="--cfg docsrs" cargo doc --features hdf5-sys/static,hdf5-sys/zlib,blosc,lzf
+
   brew:
     name: brew
     runs-on: macos-latest

Cargo.toml

@@ -16,6 +16,10 @@ default = []
 mpio = ["mpi-sys", "hdf5-sys/mpio"]
 lzf = ["lzf-sys", "errno"]
 blosc = ["blosc-sys"]
+# The features with version numbers such as 1.10.3, 1.12.0 are metafeatures
+# and is only available when the HDF5 library is at least this version.
+# Features have_direct and have_parallel are also metafeatures and dependent
+# on the HDF5 library which is linked against.
 
 [workspace]
 members = [".", "hdf5-types", "hdf5-derive", "hdf5-sys", "hdf5-src"]
@@ -47,3 +51,4 @@ tempfile = "3.2"
 
 [package.metadata.docs.rs]
 features = ["hdf5-sys/static", "hdf5-sys/zlib", "blosc", "lzf"]
+rustdoc-args = ["--cfg", "docsrs"]

build.rs

@@ -1,19 +1,21 @@
 use std::env;
 
 fn main() {
+    let print_feature = |key: &str| println!("cargo:rustc-cfg=feature=\"{}\"", key);
+    let print_cfg = |key: &str| println!("cargo:rustc-cfg={}", key);
     for (key, _) in env::vars() {
-        let key = match key.as_str() {
-            "DEP_HDF5_HAVE_DIRECT" => "h5_have_direct".into(),
-            "DEP_HDF5_HAVE_STDBOOL" => "h5_have_stdbool".into(),
-            "DEP_HDF5_HAVE_PARALLEL" => "h5_have_parallel".into(),
-            "DEP_HDF5_HAVE_THREADSAFE" => "h5_have_threadsafe".into(),
-            "DEP_HDF5_MSVC_DLL_INDIRECTION" => "h5_dll_indirection".into(),
+        match key.as_str() {
+            // public features
+            "DEP_HDF5_HAVE_DIRECT" => print_feature("have-direct"),
+            "DEP_HDF5_HAVE_PARALLEL" => print_feature("have-parallel"),
+            "DEP_HDF5_HAVE_THREADSAFE" => print_feature("have-threadsafe"),
+            // internal config flags
+            "DEP_HDF5_MSVC_DLL_INDIRECTION" => print_cfg("msvc_dll_indirection"),
+            // public version features
             key if key.starts_with("DEP_HDF5_VERSION_") => {
-                let version = key.trim_start_matches("DEP_HDF5_VERSION_");
-                format!("hdf5_{}", version)
+                print_feature(&key.trim_start_matches("DEP_HDF5_VERSION_").replace("_", "."));
             }
             _ => continue,
-        };
-        println!("cargo:rustc-cfg={}", key);
+        }
     }
 }

hdf5-sys/build.rs

@@ -616,23 +616,23 @@ impl Config {
         vs.extend((0..=7).map(|v| Version::new(1, 10, v))); // 1.10.[0-7]
         vs.push(Version::new(1, 12, 0)); // 1.12.0
         for v in vs.into_iter().filter(|&v| version >= v) {
-            println!("cargo:rustc-cfg=hdf5_{}_{}_{}", v.major, v.minor, v.micro);
+            println!("cargo:rustc-cfg=feature=\"{}.{}.{}\"", v.major, v.minor, v.micro);
             println!("cargo:version_{}_{}_{}=1", v.major, v.minor, v.micro);
         }
         if self.header.have_stdbool_h {
-            println!("cargo:rustc-cfg=h5_have_stdbool_h");
-            println!("cargo:have_stdbool=1");
+            println!("cargo:rustc-cfg=have_stdbool_h");
+            // there should be no need to export have_stdbool_h downstream
         }
         if self.header.have_direct {
-            println!("cargo:rustc-cfg=h5_have_direct");
+            println!("cargo:rustc-cfg=feature=\"have-direct\"");
             println!("cargo:have_direct=1");
         }
         if self.header.have_parallel {
-            println!("cargo:rustc-cfg=h5_have_parallel");
+            println!("cargo:rustc-cfg=feature=\"have-parallel\"");
             println!("cargo:have_parallel=1");
         }
         if self.header.have_threadsafe {
-            println!("cargo:rustc-cfg=h5_have_threadsafe");
+            println!("cargo:rustc-cfg=feature=\"have-threadsafe\"");
             println!("cargo:have_threadsafe=1");
         }
     }

hdf5-sys/src/h5.rs

@@ -12,9 +12,9 @@ pub type hsize_t = c_ulonglong;
 pub type hssize_t = c_longlong;
 pub type haddr_t = uint64_t;
 
-#[cfg(all(hdf5_1_10_0, h5_have_stdbool_h))]
+#[cfg(all(feature = "1.10.0", have_stdbool_h))]
 pub type hbool_t = u8;
-#[cfg(any(not(hdf5_1_10_0), not(h5_have_stdbool_h)))]
+#[cfg(any(not(feature = "1.10.0"), not(have_stdbool_h)))]
 pub type hbool_t = c_uint;
 
 #[repr(C)]
@@ -71,23 +71,23 @@ extern "C" {
     pub fn H5check_version(majnum: c_uint, minnum: c_uint, relnum: c_uint) -> herr_t;
 }
 
-#[cfg(hdf5_1_8_13)]
+#[cfg(feature = "1.8.13")]
 extern "C" {
     pub fn H5free_memory(mem: *mut c_void) -> herr_t;
 }
 
-#[cfg(hdf5_1_8_15)]
+#[cfg(feature = "1.8.15")]
 extern "C" {
     pub fn H5allocate_memory(size: size_t, clear: hbool_t) -> *mut c_void;
     pub fn H5resize_memory(mem: *mut c_void, size: size_t) -> *mut c_void;
 }
 
-#[cfg(hdf5_1_8_16)]
+#[cfg(feature = "1.8.16")]
 extern "C" {
     pub fn H5is_library_threadsafe(is_ts: *mut hbool_t) -> herr_t;
 }
 
-#[cfg(all(hdf5_1_10_7, not(hdf5_1_12_0)))]
+#[cfg(all(feature = "1.10.7", not(feature = "1.12.0")))]
 #[repr(C)]
 pub struct H5_alloc_stats_t {
     total_alloc_bytes: c_ulonglong,
@@ -99,7 +99,7 @@ pub struct H5_alloc_stats_t {
     peak_alloc_blocks_count: size_t,
 }
 
-#[cfg(all(hdf5_1_10_7, not(hdf5_1_12_0)))]
+#[cfg(all(feature = "1.10.7", not(feature = "1.12.0")))]
 extern "C" {
     pub fn H5get_alloc_stats(stats: *mut H5_alloc_stats_t) -> herr_t;
     pub fn H5get_free_list_sizes(

hdf5-sys/src/h5ac.rs

@@ -45,9 +45,9 @@ pub struct H5AC_cache_config_t {
     pub epochs_before_eviction: c_int,
     pub apply_empty_reserve: hbool_t,
     pub empty_reserve: c_double,
-    #[cfg(not(hdf5_1_10_0))]
+    #[cfg(not(feature = "1.10.0"))]
     pub dirty_bytes_threshold: c_int,
-    #[cfg(hdf5_1_10_0)]
+    #[cfg(feature = "1.10.0")]
     pub dirty_bytes_threshold: size_t,
     pub metadata_write_strategy: c_int,
 }
@@ -58,7 +58,7 @@ impl Default for H5AC_cache_config_t {
     }
 }
 
-#[cfg(hdf5_1_10_1)]
+#[cfg(feature = "1.10.1")]
 mod hdf5_1_10_1 {
     use super::*;
 
@@ -78,5 +78,5 @@ mod hdf5_1_10_1 {
     }
 }
 
-#[cfg(hdf5_1_10_1)]
+#[cfg(feature = "1.10.1")]
 pub use self::hdf5_1_10_1::*;

hdf5-sys/src/h5d.rs

@@ -16,7 +16,7 @@ pub const H5D_CHUNK_CACHE_NBYTES_DEFAULT: size_t = !0;
 
 pub const H5D_CHUNK_CACHE_W0_DEFAULT: c_float = -1.0;
 
-#[cfg(not(hdf5_1_10_0))]
+#[cfg(not(feature = "1.10.0"))]
 #[repr(C)]
 #[derive(Copy, Clone, PartialEq, PartialOrd, Debug)]
 pub enum H5D_layout_t {
@@ -134,15 +134,15 @@ pub type H5D_operator_t = Option<
     ) -> herr_t,
 >;
 
-#[cfg(hdf5_1_8_11)]
+#[cfg(feature = "1.8.11")]
 pub type H5D_scatter_func_t = Option<
     extern "C" fn(
         src_buf: *mut *const c_void,
         src_buf_bytes_used: *mut size_t,
         op_data: *mut c_void,
     ) -> herr_t,
 >;
-#[cfg(hdf5_1_8_11)]
+#[cfg(feature = "1.8.11")]
 pub type H5D_gather_func_t = Option<
     extern "C" fn(
         dst_buf: *const c_void,
@@ -180,7 +180,7 @@ extern "C" {
         buf: *mut c_void, type_id: hid_t, space_id: hid_t, op: H5D_operator_t,
         operator_data: *mut c_void,
     ) -> herr_t;
-    #[cfg_attr(hdf5_1_12_0, deprecated(note = "deprecated in HDF5 1.12.0, use H5Treclaim"))]
+    #[cfg_attr(feature = "1.12.0", deprecated(note = "deprecated in HDF5 1.12.0, use H5Treclaim"))]
     pub fn H5Dvlen_reclaim(
         type_id: hid_t, space_id: hid_t, plist_id: hid_t, buf: *mut c_void,
     ) -> herr_t;
@@ -201,7 +201,7 @@ extern "C" {
     pub fn H5Dopen1(file_id: hid_t, name: *const c_char) -> hid_t;
 }
 
-#[cfg(hdf5_1_8_11)]
+#[cfg(feature = "1.8.11")]
 extern "C" {
     pub fn H5Dscatter(
         op: H5D_scatter_func_t, op_data: *mut c_void, type_id: hid_t, dst_space_id: hid_t,
@@ -213,7 +213,7 @@ extern "C" {
     ) -> herr_t;
 }
 
-#[cfg(hdf5_1_10_0)]
+#[cfg(feature = "1.10.0")]
 mod hdf5_1_10_0 {
     use super::*;
 
@@ -260,10 +260,10 @@ mod hdf5_1_10_0 {
     }
 }
 
-#[cfg(hdf5_1_10_0)]
+#[cfg(feature = "1.10.0")]
 pub use self::hdf5_1_10_0::*;
 
-#[cfg(hdf5_1_10_3)]
+#[cfg(feature = "1.10.3")]
 extern "C" {
     pub fn H5Dread_chunk(
         dset_id: hid_t, dxpl_id: hid_t, offset: *const hsize_t, filters: *mut u32, buf: *mut c_void,
@@ -274,7 +274,7 @@ extern "C" {
     ) -> herr_t;
 }
 
-#[cfg(hdf5_1_10_5)]
+#[cfg(feature = "1.10.5")]
 extern "C" {
     pub fn H5Dget_chunk_info(
         dset_id: hid_t, fspace_id: hid_t, index: hsize_t, offset: *mut hsize_t,