More documentation, please

lu-zero / cdylib-link-lines

Helper to build correctly cdylibs

MIT License

14 stars 5 forks source link

More documentation, please #7

Open nwalfield opened 2 years ago

nwalfield commented 2 years ago

The package has very little documentation. I had to read the source code to understand how to use shared_object_link_args. It would be good if that contained an example. Also, it would be good if the metabuild described what it does. Something like: "based on the platform and the Cargo.toml figures out an appropriate soname, etc., and then emits cargo:rustc-cdylib-link-arg, which rustc passes to the linker", would already be quite helpful.

lu-zero commented 2 years ago

I'd merge any PR that improves it. cdylib-link-lines had most of its use-cases covered by cargo-c, so it had been a bit neglected.

nwalfield commented 2 years ago

cargo-c is way too heavy weight for my needs. When I tried it, it pulled in 189 dependencies, IIRC. I think this mostly has to do with its header file generation, which I don't need, and its pkg-config generation, which didn't work for me.

lu-zero commented 2 years ago

The pkg-config generation should work, and possibly it could be spun off in a stand alone crate if needed. cargo-c is heavy since it needs to use the full cargo, but, on the other hand you pay for it only once for any library you want to create :)

What did not work for you?

nwalfield commented 2 years ago

I documented some of the issues I encountered here.

cargo-c has 199 dependencies, and its not in Debian.
Libs.private was wrong. Instead of inlining the libraries, there should be a Requires.private on nettle.
Setting the Requires.private key in the package.metadata.capi.pkg_config table didn't work for me.
Changes to Cargo.toml(?) were not reliably being integrated into the generated file unless I first did cargo clean.
IIRC, no foo-uninstalled.pc was generated.

lu-zero commented 2 years ago

I documented some of the issues I encountered here.
* cargo-c has 199 dependencies, and its not in Debian.

That's something to be discussed with Debian I'm afraid.

* `Libs.private` was wrong.  Instead of inlining the libraries, there should be a `Requires.private` on `nettle`.

This may be hairy if rustc is providing the link line with nettle. See https://github.com/lu-zero/cargo-c/issues/242

* Setting the `Requires.private` key in the `package.metadata.capi.pkg_config` table didn't work for me.

requires_private is the entry to use, as documented in the README, probably adding an alias to accept . might be a good idea though.

* Changes to `Cargo.toml`(?) were not reliably being integrated into the generated file unless I first did `cargo clean`.

You probably tripped on https://github.com/lu-zero/cargo-c/issues/208

* IIRC, no foo-uninstalled.pc was generated.

There is now, maybe not when you tried it :)

nwalfield commented 2 years ago

cargo-c has 199 dependencies, and its not in Debian. That's something to be discussed with Debian I'm afraid.

I'm not against depending on other software, but 199 dependencies are a lot especially when the functionality I require doesn't actually need them.

lu-zero commented 7 months ago

Just to keep this up to date: cargo-c is in debian since a while.