1# libceed-sys: unsafe bindings to libCEED 2 3This is the documentation for the low level (unsafe) Rust bindings to the libCEED C interface. 4See the [libCEED user manual](https://libceed.org) for usage information. 5Note that most Rust users will prefer the higher level (safe) Rust interface in the [`libceed` crate](https://docs.rs/libceed). 6 7libCEED 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). 8While our focus is on high-order finite elements, the approach is mostly algebraic and thus applicable to other discretizations in factored form. 9 10## Usage 11 12To use low level libCEED bindings in a Rust package, the following `Cargo.toml` can be used. 13```toml 14[dependencies] 15libceed-sys = "0.12.0" 16``` 17 18For a development version of the libCEED Rust bindings, use the following `Cargo.toml`. 19```toml 20[dependencies] 21libceed-sys = { git = "https://github.com/CEED/libCEED", branch = "main" } 22``` 23 24Supported features: 25* `static` (default): link to static libceed.a 26* `system`: use libceed from a system directory (otherwise, install from source) 27 28## Development 29 30To develop libCEED, use `cargo build` in the `rust/libceed-sys` directory to install a local copy and build the bindings. 31 32If you need custom flags for the C project, we recommend using `make -C c-src configure` to cache arguments in `c-src/config.mk`. 33If that file exists during `cargo build` then edits will prompt recompilation of the bindings. 34 35### Shared libraries 36If 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 37 38```bash 39export LD_LIBRARY_PATH=$CEED_DIR/lib 40export PKG_CONFIG_PATH=$CEED_DIR/lib/pkgconfig 41``` 42 43#### Without system 44If 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. 45This might look like 46 47```bash 48export LD_LIBRARY_PATH=$CEED_DIR/target/debug/build/libceed-sys-d1ea22c6e1ad3f23/out/lib 49``` 50 51where the precise hash value is printed during `cargo build --verbose` or you can find it with `find target -name libceed.so`. 52This mode of development is more fragile than the default (which uses static libraries). 53 54Note 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. 55 56## License: BSD-2-Clause 57 58## Contributing 59 60The `libceed-sys` crate is developed within the [libCEED repository](https://github.com/CEED/libCEED). 61See the [contributing guidelines](https://libceed.org/en/latest/CONTRIBUTING/) for details. 62