rust: split crates into libceed-sys and libceed

[jedbrown]

• split crates
• document libceed-sys/src/lib.rs (briefly)
• update docs for versioned packages from crates.io
• set include/exclude keys for cargo package
• fix failing Rust CI
• dry-run publish

[jeremylt]

This issue indicates that packaging with symlinks should maybe work, but currently it does not actually work for us.

The entire c-src symlink is completely ignored without warning.

jeremy@Sinensis:~/Dev/libCEED/rust/libceed-sys$ cargo package --list
.cargo_vcs_info.json
Cargo.toml
Cargo.toml.orig
build.rs
src/lib.rs

[jedbrown]

Should be fixed now. The issue seems to have been discovering a Cargo.toml in that subdirectory.

[jeremylt]

Ah. Annoying.

[jeremylt]

The CI failure is with detection of Valgrind

  /home/runner/work/libCEED/libCEED/rust/libceed-sys/c-src/backends/memcheck/ceed-memcheck-qfunction.c:19:10: fatal error: 'valgrind/memcheck.h' file not found
  #include <valgrind/memcheck.h>
           ^~~~~~~~~~~~~~~~~~~~~
  1 error generated.
  make: *** [Makefile:489: /home/runner/work/libCEED/libCEED/target/debug/build/libceed-sys-d1ea22c6e1ad3f23/out/build/backends/memcheck/ceed-memcheck-qfunction.o] Error 1

Investigating

[jeremylt]

Ok, CI should be happy now and cargo package --dry-run works for libceed-sys. We'll need to first publish libceed-sys before we can get the dry run to work for the libceed crate though.

[jedbrown]

Anyone know off-hand how to make a README.md be used by docs.rs?

[YohannDudouit]

[package]
readme = "/path/to/readme/README.md"

?

[jedbrown]

Well, we currently use rST and even if we switch to md, it'll likely be the MyST dialect. But we currently have crate docs in src/lib.rs and I mildly prefer it there because we can test code snippets, while as far as I know, code snippets in README.md are not tested.

So I was thinking if docs.rs could put the README.md at the top, followed by the more detailed docs in src/lib.rs, we'd have an okay solution that didn't duplicate text. Is that what your suggestion does, or use it just being explicit about where crates.io should get its readme?

[jedbrown]

Closest I've found seems to be cargo-readme, which writes README.md from the src/lib.rs rustdoc comments. What do y'all think? Should we use it? (It becomes a release step because cargo doesn't do it automatically.)

[jeremylt]

Another possible use of #[cfg(doctest)] is to test doctests that are included in your README file without including it in your main documentation. For example, you could write this into your lib.rs to test your README as part of your doctests:

#![feature(external_doc)]

#[doc(include = "../README.md")]
#[cfg(doctest)]
pub struct ReadmeDoctests;

This will include your README as documentation on the hidden struct ReadmeDoctests, which will then be tested alongside the rest of your doctests.

What about this?

[jeremylt]

Here we go, found the page on it
https://doc.rust-lang.org/unstable-book/language-features/external-doc.html
It is an unstable feature and it's not clear to me if the documentation at the top of the lib file can be included in this way. We can tinker tomorrow though

[jedbrown]

Good find, and it works for module documentation, but from what I can tell, not for crate-level docs.

[jeremylt]

rust-lang/rust#83366

This might also be an option

[jedbrown]

I got it working, though I had to read this section a half-dozen times to catch the distinction between #[doc = ...] and #![doc = ...].

[jedbrown]

🎉 https://crates.io/crates/libceed

This PR is ready from my perspective. It's published as 0.8.0 (nominally distinct from libCEED C library version) and we can iron out any quirks before cutting 0.8.1 (and encouraging external users of the Rust interace). I will add notes on release procedure to #725 .

Cc: @ZackJorquera

[jeremylt]

Looks ready to me