Since there are plenty of blogposts about what people would like to have or will implement in rust in 2019 here is mine.
I spent the last few weeks of my spare time making a C-api for rav1e called crav1e, overall the experience had been a mixed bag and there is large space for improvement.
Ideally I’d like to have by the end of the year something along the lines of:
$ cargo install-library --prefix=/usr --libdir=/usr/lib64 --destdir=/staging/place
So that it would:
– build a valid cdylib+staticlib
– produce a correct header
– produce a correct pkg-config file
– install all of it in the right paths
All of this requiring a quite basic build.rs and, probably, an applet.
What is it all about?
Building and installing properly shared libraries is quite hard, even more on multiple platforms.
Right now cargo has quite limited install capabilities with some work pending on extending it and has an open issue and a patch.
Distributions that, probably way too early since the rust-ABI is not stable nor being stabilized yet, are experimenting in building everything as shared library also have those problems.
Why it is important
rust is a pretty good language and has a fairly simple way to interact in both direction with any other language that can produce or consume C-ABI-compatible object code.
This is already quite useful if you want to build a small static archive and link it in your larger application and/or library.
An example of this use-case is librsvg.
Such heterogeneous environment warrant for a modicum of additional machinery and complication.
But if your whole library is written in rust, it is a fairly annoying amount of boilerplate that you would rather avoid.
Current status
If you want to provide C-bindings to your crates you do not have a single perfect solution right now.
What works well already
Currently building the library itself works fine and it is really straightforward:
- It is quite easy to mark data types and functions to be C-compatible:
#[repr(C)]
pub struct Foo {
a: Bar,
...
}
#[no_mangle]
pub unsafe extern "C" fn make_foo() -> *mut Foo {
...
}
[lib]
name = "rav1e"
crate-type = ["staticlib"]
- cbindgen can produce a usable
C-headerfrom a crate using few lines ofbuild.rsor a stand-alone applet and atomlconfiguration file.
extern crate cbindgen;
fn main() {
let crate_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
let header_path: std::path::PathBuf = ["include", "rav1e.h"].iter().collect();
cbindgen::generate(crate_dir).unwrap().write_to_file(header_path);
println!("cargo:rerun-if-changed=src/lib.rs");
println!("cargo:rerun-if-changed=cbindgen.toml");
}
header = "// SPDX-License-Identifier: MIT"
sys_includes = ["stddef.h"]
include_guard = "RAV1E_H"
tab_width = 4
style = "Type"
language = "C"
[parse]
parse_deps = true
include = ['rav1e']
expand = ['rav1e']
[export]
prefix = "Ra"
item_types = ["enums", "structs", "unions", "typedefs", "opaque", "functions"]
[enum]
rename_variants = "ScreamingSnakeCase"
prefix_with_name = true
Now issuing cargo build --release will get you a .h in the include/ dir and a .a library in target/release, so far it is simple enough.
What sort of works
Once have a static library, you need an external mean to track what are its dependencies.
Back in the old ages there were libtool archives (.la), now we have pkg-config files providing more information and in a format that is way easier to parse and use.
rustc has --print native-static-libs to produce the additional libraries to link, BUT prints it to stderr and only as a side-effect of the actual build process.
My, fairly ugly, hack had been adding a dummy empty subcrate just to produce the link-line using
cargo rustc -- --print native-static-libs 2>&1| grep native-static-libs | cut -d ':' -f 3
And then generate the .pc file from a template.
This is anything but straightforward and because how cargo rustc works, you may end up adding an empty subcrate just to extract this information quickly.
What is missing
Once you have your library, your header and your pkg-config file, you probably would like to install the library somehow and/or make a package out of it.
cargo install does not currently cover it. It works only for binaries and just binaries alone. It will hopefully change, but right now you just have to pick the external build system you are happy with and hack your way to integrate the steps mentioned above.
For crav1e I ended up hacking a quite crude Makefile.
And with that at least a pure-rust static library can be built and installed with the common:
make DESTDIR=/staging/place prefix=/usr libdir=/usr/lib64
Dynamic libraries
Given rustc and cargo have the cdylib crate type, one would assume we could just add the type, modify our build-system contraption a little and go our merry way.
Sadly not. A dynamic library (or shared object) requires in most of the common platform some additional metadata to guide the runtime linker.
The current widespread practice is to use tools such as patchelf or install_name_tool, but it is quite brittle and might require tools.
My plans for the 2019
rustc has a mean to pass the information to the compile-time linker but there is no proper way to pass it in cargo, I already tried to provide a solution, but I’ll have to go through the rfc route to make sure there is community consensus and the feature is properly documented.
Since kind of metadata is platform-specific so would be better to have this information produced and passed on by something external to the main cargo. Having it as applet or a build.rs dependency makes easier to support more platforms little by little and have overrides without having to go through a main cargo update.
The applet could also take care of properly create the .pc file and installing since it would have access to all the required information.
Some efforts could be also put on streamlining the process of extracting the library link line for the static data and spare some roundtrips.
I guess that’s all for what I’d really like to have next year in rust and I’m confident I’ll have time to deliver myself π