1# libceed-sys: unsafe bindings to libCEED 2 3This is the documentation for the low level (unsafe) Rust bindings to the libCEED C 4interface. See the [libCEED user manual](https://libceed.org) for usage 5information. Note that most Rust users will prefer the higher level (safe) Rust 6interface in the [`libceed` crate](https://docs.rs/libceed). 7 8libCEED is a low-level API for for the efficient high-order discretization methods 9developed by the ECP co-design Center for Efficient Exascale Discretizations (CEED). 10While our focus is on high-order finite elements, the approach is mostly algebraic 11and thus applicable to other discretizations in factored form. 12 13## Usage 14 15To use low level libCEED bindings in a Rust package, the following `Cargo.toml` 16can be used. 17```toml 18[dependencies] 19libceed-sys = "0.9.0" 20``` 21 22For a development version of the libCEED Rust bindings, use the following `Cargo.toml`. 23```toml 24[dependencies] 25libceed-sys = { git = "https://github.com/CEED/libCEED", branch = "main" } 26``` 27 28Supported features: 29* `static` (default): link to static libceed.a 30* `system`: use libceed from a system directory (otherwise, install from source) 31 32## Development 33 34To develop libCEED, use `cargo build` in the `rust/libceed-sys` directory to 35install a local copy and build the bindings. 36 37If you need custom flags for the C project, we recommend using `make -C c-src 38configure` to cache arguments in `c-src/config.mk`. If that file exists during 39`cargo build` then edits will prompt recompilation of the bindings. 40 41### Shared libraries 42If one is developing libCEED C source and testing multiple language bindings at 43once, a few seconds can be cut out of the edit/compile/test loop by disabling 44the `static` feature and using 45 46```bash 47export LD_LIBRARY_PATH=$CEED_DIR/lib 48export PKG_CONFIG_PATH=$CEED_DIR/lib/pkgconfig 49``` 50 51#### Without system 52If you disable the `static` feature and are not using a system version from a 53standard path/somewhere that can be found by pkg-config, then you'll need to set 54`LD_LIBRARY_PATH` to the appropriate target directory for doctests to be able to 55find it. This might look like 56 57```bash 58export LD_LIBRARY_PATH=$CEED_DIR/target/debug/build/libceed-sys-d1ea22c6e1ad3f23/out/lib 59``` 60 61where the precise hash value is printed during `cargo build --verbose` or you 62can find it with `find target -name libceed.so`. This mode of development is 63more fragile than the default (which uses static libraries). 64 65Note that the `LD_LIBRARY_PATH` workarounds will become unnecessary if [this 66issue](https://github.com/rust-lang/cargo/issues/1592) is resolved -- it's 67currently closed, but the problem still exists. 68 69## License: BSD-2-Clause 70 71## Contributing 72 73The `libceed-sys` crate is developed within the [libCEED 74repository](https://github.com/CEED/libCEED). See the [contributing 75guidelines](https://libceed.org/en/latest/CONTRIBUTING/) for details. 76