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