rust: split crates into libceed-sys and libceed

.github/workflows/rust-documentation.yml

@@ -24,9 +24,7 @@ jobs:
         toolchain: stable
     - name: Build documentation
       run: |
-        cd rust
-        cargo doc --all --no-deps
-        cd ..
+        cargo doc --package libceed-sys --package libceed --no-deps
         touch ./target/doc/.nojekyll
         echo "<meta http-equiv=refresh content=0;url=libceed/index.html>" > ./target/doc/index.html
     - name: Deploy documentation

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
-        "rust",
+        "rust/libceed",
+        "rust/libceed-sys",
         "examples/rust/ex1-volume",
         "examples/rust/ex2-surface",
 ]

doc/sphinx/source/ffi.rst

@@ -9,7 +9,7 @@ documentation <http://ceed.exascaleproject.org/libCEED-julia-docs/dev/>`_.
 
 Usage of the Python interface is illustrated through a sequence of `Jupyter
 Notebook tutorials
-<https://github.com/CEED/libCEED/tree/main/examples/tutorials>`_. More
+<https://github.com/CEED/libCEED/tree/main/examples/python>`_. More
 information on the Python interface is available in the `SciPy paper
 <https://doi.org/10.25080/Majora-342d178e-00c>`_.
 

examples/rust/ex1-volume/Cargo.toml

@@ -8,5 +8,5 @@ edition = "2018"
 
 [dependencies]
 structopt = { version = "0.3", default-features = false }
-libceed = { path = "../../../rust" }
+libceed = { path = "../../../rust/libceed" }
 mesh = { path = "../mesh" }

examples/rust/ex2-surface/Cargo.toml

@@ -8,5 +8,5 @@ edition = "2018"
 
 [dependencies]
 structopt = { version = "0.3", default-features = false }
-libceed = { path = "../../../rust" }
+libceed = { path = "../../../rust/libceed" }
 mesh = { path = "../mesh" }

examples/rust/mesh/Cargo.toml

@@ -7,4 +7,4 @@ authors = [
 edition = "2018"
 
 [dependencies]
-libceed = { path = "../../../rust" }
+libceed = { path = "../../../rust/libceed" }

rust/libceed-sys/Cargo.toml

@@ -0,0 +1,37 @@
+[package]
+authors = [
+    "Jed Brown <jed@jedbrown.org>",
+    "Yohann Dudouit <dudouit1@llnl.gov>",
+    "Jeremy L Thompson <thompson.jeremy.luke@gmail.com>",
+]
+build = "build.rs"
+name = "libceed-sys"
+version = "0.8.0"
+links = "libceed-sys"
+edition = "2018"
+license = "BSD-2-Clause"
+repository = "https://github.com/CEED/libCEED"
+documentation = "https://libceed.readthedocs.io/en/latest/"
+description = """
+Low-level bindings for libCEED library.
+"""
+keywords = ["libceed", "exascale", "high-order"]
+categories = ["science"]
+include = [
+    "build.rs",
+    "README.md",
+    "src/**",
+    "c-src/**",
+]
+
+[features]
+default = ["static"]
+static = []
+system = []
+
+[build-dependencies]
+bindgen = "0.58.1"
+pkg-config = "0.3.19"
+
+[dev-dependencies]
+version-sync = "0.9.2"

rust/libceed-sys/README.md

@@ -0,0 +1,75 @@
+# libceed-sys: unsafe bindings to libCEED
+
+This is the documentation for the low level (unsafe) Rust bindings to the libCEED C
+interface. See the [libCEED user manual](https://libceed.readthedocs.io) for usage
+information. Note that most Rust users will prefer the higher level (safe) Rust
+interface in the [`libceed` crate](https://docs.rs/libceed).
+
+libCEED is a low-level API for for the efficient high-order discretization methods
+developed by the ECP co-design Center for Efficient Exascale Discretizations (CEED).
+While our focus is on high-order finite elements, the approach is mostly algebraic
+and thus applicable to other discretizations in factored form.
+
+## Usage
+
+To use low level libCEED bindings in a Rust package, the following `Cargo.toml`
+can be used.
+```toml
+[dependencies]
+libceed-sys = "0.8.0"
+```
+
+For a development version of the libCEED Rust bindings, use the following `Cargo.toml`.
+```toml
+[dependencies]
+libceed-sys = { git = "https://github.com/CEED/libCEED", branch = "main" }
+```
+
+Supported features:
+* `static` (default): link to static libceed.a
+* `system`: use libceed from a system directory (otherwise, install from source)
+
+## Development
+
+To develop libCEED, use `cargo build` in the `rust/libceed-sys` directory to
+install a local copy and build the bindings.
+
+If you need custom flags for the C project, we recommend using `make -C c-src
+configure` to cache arguments in `c-src/config.mk`. If that file exists during
+`cargo build` then edits will prompt recompilation of the bindings.
+
+### Shared libraries
+If one is developing libCEED C source and testing multiple language bindings at
+once, a few seconds can be cut out of the edit/compile/test loop by disabling
+the `static` feature and using
+
+```bash
+export LD_LIBRARY_PATH=$CEED_DIR/lib
+export PKG_CONFIG_PATH=$CEED_DIR/lib/pkgconfig
+```
+
+#### Without system
+If you disable the `static` feature and are not using a system version from a
+standard path/somewhere that can be found by pkg-config, then you'll need to set
+`LD_LIBRARY_PATH` to the appropriate target directory for doctests to be able to
+find it. This might look like
+
+```bash
+export LD_LIBRARY_PATH=$CEED_DIR/target/debug/build/libceed-sys-d1ea22c6e1ad3f23/out/lib
+```
+
+where the precise hash value is printed during `cargo build --verbose` or you
+can find it with `find target -name libceed.so`. This mode of development is
+more fragile than the default (which uses static libraries).
+
+Note that the `LD_LIBRARY_PATH` workarounds will become unnecessary if [this
+issue](https://github.com/rust-lang/cargo/issues/1592) is resolved -- it's
+currently closed, but the problem still exists.
+
+## License: BSD-2-Clause
+
+## Contributing
+
+The `libceed-sys` crate is developed within the [libCEED
+repository](https://github.com/CEED/libCEED). See the [contributing
+guidelines](https://libceed.readthedocs.io/en/latest/CONTRIBUTING/) for details.

rust/build.rs → rust/libceed-sys/build.rs

@@ -1,7 +1,7 @@
 extern crate bindgen;
 extern crate pkg_config;
 
-use std::path::PathBuf;
+use std::path::{Path, PathBuf};
 use std::process::Command;
 
 fn main() {
@@ -17,8 +17,16 @@ fn main() {
         let mut make = Command::new("make");
         make.arg("install")
             .arg(format!("prefix={}", out_dir.to_string_lossy()))
+            .arg(format!(
+                "OBJDIR={}",
+                out_dir.join("build").to_string_lossy()
+            ))
+            .arg(format!(
+                "LIBDIR={}",
+                out_dir.join("build").join("lib").to_string_lossy()
+            ))
             .env("MAKEFLAGS", makeflags)
-            .current_dir("..");
+            .current_dir("c-src");
         if statik {
             make.arg("STATIC=1");
         }
@@ -37,17 +45,29 @@ fn main() {
         .unwrap();
 
     // Tell cargo to invalidate the built crate whenever the wrapper changes
-    println!("cargo:rerun-if-changed=../include/ceed/ceed.h");
-    println!("cargo:rerun-if-changed=../Makefile");
-    println!("cargo:rerun-if-changed=../config.mk");
+    println!("cargo:rerun-if-changed=c-src/include/ceed/ceed.h");
+    println!("cargo:rerun-if-changed=c-src/Makefile");
+    if Path::new("c-src/config.mk").is_file() {
+        println!("cargo:rerun-if-changed=c-src/config.mk");
+    }
 
     // The bindgen::Builder is the main entry point
     // to bindgen, and lets you build up options for
     // the resulting bindings.
     let bindings = bindgen::Builder::default()
         // The input header we would like to generate
         // bindings for.
-        .header("../include/ceed/ceed.h")
+        .header("c-src/include/ceed/ceed.h")
+        .allowlist_function("Ceed.*")
+        .allowlist_type("Ceed.*")
+        .allowlist_var("Ceed.*")
+        .allowlist_var("CEED_.*")
+        // Don't chase recursive definitions of these system types
+        .opaque_type("FILE")
+        .opaque_type("va_list")
+        // Accessing directly here, but perhaps should use libc crate
+        .allowlist_function("fclose")
+        .allowlist_function("open_memstream")
         // Tell cargo to not mangle the function names
         .trust_clang_mangling(false)
         // Tell cargo to invalidate the built crate whenever any of the

rust/libceed-sys/c-src/Makefile

@@ -0,0 +1 @@
+../../../Makefile

rust/libceed-sys/c-src/backends

@@ -0,0 +1 @@
+../../../backends

rust/libceed-sys/c-src/ceed.pc.template

@@ -0,0 +1 @@
+../../../ceed.pc.template

rust/libceed-sys/c-src/common.mk

@@ -0,0 +1 @@
+../../../common.mk

rust/libceed-sys/c-src/gallery

@@ -0,0 +1 @@
+../../../gallery

rust/libceed-sys/c-src/include

@@ -0,0 +1 @@
+../../../include

rust/libceed-sys/c-src/interface

@@ -0,0 +1 @@
+../../../interface

rust/libceed-sys/src/lib.rs

@@ -0,0 +1,30 @@
+// Copyright (c) 2017, Lawrence Livermore National Security, LLC. Produced at
+// the Lawrence Livermore National Laboratory. LLNL-CODE-734707. All Rights
+// reserved. See files LICENSE and NOTICE for details.
+//
+// This file is part of CEED, a collection of benchmarks, miniapps, software
+// libraries and APIs for efficient high-order finite element and spectral
+// element discretizations for exascale applications. For more information and
+// source code availability see http://github.com/ceed.
+//
+// The CEED research is supported by the Exascale Computing Project 17-SC-20-SC,
+// a collaborative effort of two U.S. Department of Energy organizations (Office
+// of Science and the National Nuclear Security Administration) responsible for
+// the planning and preparation of a capable exascale ecosystem, including
+// software, applications, hardware, advanced system engineering and early
+// testbed platforms, in support of the nation's exascale computing imperative
+
+#![doc = include_str!("../README.md")]
+
+/**
+Bindings generated from libCEED's C headers using bindgen.
+
+See `build.rs` to customize the process and refer to the [libCEED API
+docs](https://libceed.readthedocs.io/en/latest/api/) for usage.
+*/
+pub mod bind_ceed {
+    #![allow(non_upper_case_globals)]
+    #![allow(non_camel_case_types)]
+    #![allow(dead_code)]
+    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+}

rust/libceed-sys/tests/register.rs

@@ -0,0 +1,8 @@
+/// Basic smoke test to confirm that the library is callable.
+#[test]
+fn test_import() {
+    use libceed_sys::bind_ceed;
+    unsafe {
+        bind_ceed::CeedRegisterAll();
+    }
+}

rust/libceed-sys/tests/version-numbers.rs

@@ -0,0 +1,18 @@
+use std::path::{Path, PathBuf};
+
+fn get_rel_path(rel: impl AsRef<Path>) -> PathBuf {
+    let path = std::env::current_dir().unwrap();
+    if path.ends_with("rust/libceed-sys") {
+        rel.as_ref().to_path_buf()
+    } else {
+        Path::new("rust/libceed-sys").join(rel)
+    }
+}
+
+#[test]
+fn test_doc_version() {
+    version_sync::assert_contains_regex!(
+        get_rel_path("README.md").to_str().unwrap(),
+        "{name} = \"{version}\""
+    );
+}

rust/libceed/.gitignore

@@ -0,0 +1,2 @@
+target
+Cargo.lock

rust/libceed/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+authors = [
+    "Jed Brown <jed@jedbrown.org>",
+    "Yohann Dudouit <dudouit1@llnl.gov>",
+    "Jeremy L Thompson <thompson.jeremy.luke@gmail.com>",
+]
+name = "libceed"
+version = "0.8.0"
+edition = "2018"
+license = "BSD-2-Clause"
+repository = "https://github.com/CEED/libCEED"
+documentation = "https://libceed.readthedocs.io/en/latest/"
+description = """
+High-level interface for libCEED - the efficient high-order discretization library developed by the ECP co-design center CEED.
+"""
+keywords = ["libceed", "exascale", "high-order"]
+categories = ["science"]
+
+[dependencies]
+libceed-sys = { version = "0.8", path = "../libceed-sys" }
+
+[dev-dependencies]
+version-sync = "0.9.2"