109752d44SJed Brown# libceed-sys: unsafe bindings to libCEED 209752d44SJed Brown 317be3a41SJeremy L ThompsonThis is the documentation for the low level (unsafe) Rust bindings to the libCEED C interface. 417be3a41SJeremy L ThompsonSee the [libCEED user manual](https://libceed.org) for usage information. 517be3a41SJeremy L ThompsonNote that most Rust users will prefer the higher level (safe) Rust interface in the [`libceed` crate](https://docs.rs/libceed). 609752d44SJed Brown 717be3a41SJeremy L ThompsonlibCEED 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). 817be3a41SJeremy L ThompsonWhile our focus is on high-order finite elements, the approach is mostly algebraic and thus applicable to other discretizations in factored form. 909752d44SJed Brown 1009752d44SJed Brown## Usage 1109752d44SJed Brown 1217be3a41SJeremy L ThompsonTo use low level libCEED bindings in a Rust package, the following `Cargo.toml` can be used. 1309752d44SJed Brown```toml 1409752d44SJed Brown[dependencies] 15*4018a20aSJeremy L Thompsonlibceed-sys = "0.12.0" 1609752d44SJed Brown``` 1709752d44SJed Brown 1809752d44SJed BrownFor a development version of the libCEED Rust bindings, use the following `Cargo.toml`. 1909752d44SJed Brown```toml 2009752d44SJed Brown[dependencies] 2109752d44SJed Brownlibceed-sys = { git = "https://github.com/CEED/libCEED", branch = "main" } 2209752d44SJed Brown``` 2309752d44SJed Brown 2409752d44SJed BrownSupported features: 2509752d44SJed Brown* `static` (default): link to static libceed.a 2609752d44SJed Brown* `system`: use libceed from a system directory (otherwise, install from source) 2709752d44SJed Brown 2809752d44SJed Brown## Development 2909752d44SJed Brown 3017be3a41SJeremy L ThompsonTo develop libCEED, use `cargo build` in the `rust/libceed-sys` directory to install a local copy and build the bindings. 3109752d44SJed Brown 3217be3a41SJeremy L ThompsonIf you need custom flags for the C project, we recommend using `make -C c-src configure` to cache arguments in `c-src/config.mk`. 3317be3a41SJeremy L ThompsonIf that file exists during `cargo build` then edits will prompt recompilation of the bindings. 3409752d44SJed Brown 3509752d44SJed Brown### Shared libraries 3617be3a41SJeremy L ThompsonIf 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 3709752d44SJed Brown 3809752d44SJed Brown```bash 3909752d44SJed Brownexport LD_LIBRARY_PATH=$CEED_DIR/lib 4009752d44SJed Brownexport PKG_CONFIG_PATH=$CEED_DIR/lib/pkgconfig 4109752d44SJed Brown``` 4209752d44SJed Brown 4309752d44SJed Brown#### Without system 4417be3a41SJeremy L ThompsonIf 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. 4517be3a41SJeremy L ThompsonThis might look like 4609752d44SJed Brown 4709752d44SJed Brown```bash 4809752d44SJed Brownexport LD_LIBRARY_PATH=$CEED_DIR/target/debug/build/libceed-sys-d1ea22c6e1ad3f23/out/lib 4909752d44SJed Brown``` 5009752d44SJed Brown 5117be3a41SJeremy L Thompsonwhere the precise hash value is printed during `cargo build --verbose` or you can find it with `find target -name libceed.so`. 5217be3a41SJeremy L ThompsonThis mode of development is more fragile than the default (which uses static libraries). 5309752d44SJed Brown 5417be3a41SJeremy L ThompsonNote 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. 5509752d44SJed Brown 5609752d44SJed Brown## License: BSD-2-Clause 5709752d44SJed Brown 5809752d44SJed Brown## Contributing 5909752d44SJed Brown 6017be3a41SJeremy L ThompsonThe `libceed-sys` crate is developed within the [libCEED repository](https://github.com/CEED/libCEED). 6117be3a41SJeremy L ThompsonSee the [contributing guidelines](https://libceed.org/en/latest/CONTRIBUTING/) for details. 62