confusing documentation about '*-sys' crates?

[davepacheco]

I apologize in advance if I'm misunderstanding this (or if I've filed this in the wrong place!

Regarding *-sys packages, the Cargo book says:

Some Cargo packages that link to system libraries have a naming convention of having a -sys suffix. Any package named foo-sys should provide two major pieces of functionality:

• The library crate should link to the native library libfoo. This will often probe the current system for libfoo before resorting to building from source.
• The library crate should provide declarations for functions in libfoo, but not bindings or higher-level abstractions.

I'm confused about that second bullet. As I understand it, the crate should provide bindings and nothing else -- no higher-level abstractions. Is that right? I'm not sure what a "declaration" would even be in this context.

[Eh2406]

Yes, I believe that is correct. I think declaration refers to

#[link(name = "my_c_library")]
extern "C" {
    fn my_c_function(x: i32) -> bool;
}

from https://doc.rust-lang.org/std/keyword.extern.html

Do you have a suggestion for a clearer way to say it?

[ehuss]

Yea, I agree it is a bit confusing, since I define "bindings" as what @Eh2406 wrote, but the docs say the opposite. I would maybe just remove the word "bindings", and maybe tweak it to say "should provide declarations for types and functions in libfoo", since sys crates usually also include Rust definitions of C structs and enums.

[davepacheco]

Thanks for clarifying! Yeah, @ehuss's suggestion sounds clear to me -- the second bullet could say "The library crate should provide declarations for types and functions in libfoo, but not higher-level abstractions."

[Eh2406]

Sounds good, You up for making a PR with that change?

[davepacheco]

Sure thing!

[davepacheco]

PR #9871

[davepacheco]

Thanks y'all for taking a look! It's a nitty change but helps me and hopefully others too.