109752d44SJed Brown# libceed-sys: unsafe bindings to libCEED 209752d44SJed Brown 309752d44SJed BrownThis is the documentation for the low level (unsafe) Rust bindings to the libCEED C 413964f07SJed Browninterface. See the [libCEED user manual](https://libceed.org) for usage 509752d44SJed Browninformation. Note that most Rust users will prefer the higher level (safe) Rust 609752d44SJed Browninterface in the [`libceed` crate](https://docs.rs/libceed). 709752d44SJed Brown 809752d44SJed BrownlibCEED is a low-level API for for the efficient high-order discretization methods 909752d44SJed Browndeveloped by the ECP co-design Center for Efficient Exascale Discretizations (CEED). 1009752d44SJed BrownWhile our focus is on high-order finite elements, the approach is mostly algebraic 1109752d44SJed Brownand thus applicable to other discretizations in factored form. 1209752d44SJed Brown 1309752d44SJed Brown## Usage 1409752d44SJed Brown 1509752d44SJed BrownTo use low level libCEED bindings in a Rust package, the following `Cargo.toml` 1609752d44SJed Browncan be used. 1709752d44SJed Brown```toml 1809752d44SJed Brown[dependencies] 19*667e613fSJeremy L Thompsonlibceed-sys = "0.10.0" 2009752d44SJed Brown``` 2109752d44SJed Brown 2209752d44SJed BrownFor a development version of the libCEED Rust bindings, use the following `Cargo.toml`. 2309752d44SJed Brown```toml 2409752d44SJed Brown[dependencies] 2509752d44SJed Brownlibceed-sys = { git = "https://github.com/CEED/libCEED", branch = "main" } 2609752d44SJed Brown``` 2709752d44SJed Brown 2809752d44SJed BrownSupported features: 2909752d44SJed Brown* `static` (default): link to static libceed.a 3009752d44SJed Brown* `system`: use libceed from a system directory (otherwise, install from source) 3109752d44SJed Brown 3209752d44SJed Brown## Development 3309752d44SJed Brown 3409752d44SJed BrownTo develop libCEED, use `cargo build` in the `rust/libceed-sys` directory to 3509752d44SJed Browninstall a local copy and build the bindings. 3609752d44SJed Brown 3709752d44SJed BrownIf you need custom flags for the C project, we recommend using `make -C c-src 3809752d44SJed Brownconfigure` to cache arguments in `c-src/config.mk`. If that file exists during 3909752d44SJed Brown`cargo build` then edits will prompt recompilation of the bindings. 4009752d44SJed Brown 4109752d44SJed Brown### Shared libraries 4209752d44SJed BrownIf one is developing libCEED C source and testing multiple language bindings at 4309752d44SJed Brownonce, a few seconds can be cut out of the edit/compile/test loop by disabling 4409752d44SJed Brownthe `static` feature and using 4509752d44SJed Brown 4609752d44SJed Brown```bash 4709752d44SJed Brownexport LD_LIBRARY_PATH=$CEED_DIR/lib 4809752d44SJed Brownexport PKG_CONFIG_PATH=$CEED_DIR/lib/pkgconfig 4909752d44SJed Brown``` 5009752d44SJed Brown 5109752d44SJed Brown#### Without system 5209752d44SJed BrownIf you disable the `static` feature and are not using a system version from a 5309752d44SJed Brownstandard path/somewhere that can be found by pkg-config, then you'll need to set 5409752d44SJed Brown`LD_LIBRARY_PATH` to the appropriate target directory for doctests to be able to 5509752d44SJed Brownfind it. This might look like 5609752d44SJed Brown 5709752d44SJed Brown```bash 5809752d44SJed Brownexport LD_LIBRARY_PATH=$CEED_DIR/target/debug/build/libceed-sys-d1ea22c6e1ad3f23/out/lib 5909752d44SJed Brown``` 6009752d44SJed Brown 6109752d44SJed Brownwhere the precise hash value is printed during `cargo build --verbose` or you 6209752d44SJed Browncan find it with `find target -name libceed.so`. This mode of development is 6309752d44SJed Brownmore fragile than the default (which uses static libraries). 6409752d44SJed Brown 6509752d44SJed BrownNote that the `LD_LIBRARY_PATH` workarounds will become unnecessary if [this 6609752d44SJed Brownissue](https://github.com/rust-lang/cargo/issues/1592) is resolved -- it's 6709752d44SJed Browncurrently closed, but the problem still exists. 6809752d44SJed Brown 6909752d44SJed Brown## License: BSD-2-Clause 7009752d44SJed Brown 7109752d44SJed Brown## Contributing 7209752d44SJed Brown 7309752d44SJed BrownThe `libceed-sys` crate is developed within the [libCEED 7409752d44SJed Brownrepository](https://github.com/CEED/libCEED). See the [contributing 7513964f07SJed Brownguidelines](https://libceed.org/en/latest/CONTRIBUTING/) for details. 76