Rustc-link-lib static library

1

Hello,

I am trying to understand rustc-link-lib with a static library.

Why does this work:

println!("cargo:rustc-link-lib=sqlite3");

This file is libsqlite3.a.

What happens if I have libsqlite3.so and libsqlite3.a ?

Thank you very much in advance for any help.

2

this is essentially passing a -lsqlite3 flag to the linker, the behavior of which is actually linker dependent. for msvc on windows, it will look for a library file named sqlite3.lib.

for most platforms, the default behavior is to link against the static library first if it exists. if you want to ensure the static library is used, it can be explicitly specified:

println!("cargo:rustc-link-lib=static=sqlite3");
3

Thank you for your help.

Unfortunately this doesn't work

It says:

could not find native static library `sqlite3`, perhaps an -L flag is missing?
4

Are you sure you have a libsqlite3.a file installed on your system somewhere inside /usr?

5

I hope it answers your question.

This works:

println!("cargo:rustc-link-search={}", BUILD_DIR);
println!("cargo:rustc-link-lib=sqlite3");

while this doesn't:

println!("cargo:rustc-link-search={}", BUILD_DIR);
println!("cargo:rustc-link-lib=static=sqlite3");

So, by setting rustc-link-search I presume that I'm telling it where the static library should be placed. But it doesn't seem to work.

6

basically there are two possibilities: the library file name is wrong, or the search directory path is wrong.

for the first problem, how did you build the library? can you double check the libsqlite3.a file is a valid static library?

I would suggest you use the cc crate to build the library, if you have to build it from source yourself. a better solution would be just use the sqlite3 crate (or sqlite3-sys, or even sqlite3-src).

for the second, how did you calculated BUILD_DIR? if you build the library in the build script, you should put the artifact inside the directory as specified by cargo in the OUT_DIR environment variable. also, is BUILD_DIR a relative path or absolute path?

maybe your BUILD_DIR is wrong but the first case "happens" to work because your host system has a libsqlite3.so installed. in other words, it might seem to work but didn't do what you expected.

at last, you can always check the full linker command line by setting the --print link-args compiler flag, for example:

$ RUSTFLAGS='--print link-args' cargo build
7

Thank you it really helped me.

I have no idea what went wrong.

I replaced every relative path (starting from the build.rs directory) with an absolute path. It now works.

Thank you very much.

8

you are supposed to calculate the absolute paths using the CARGO_MANIFEST_DIR environment variable. e.g.

// do NOT use relative path like this:
println!("cargo::rustc-link-search=libraries");
// NOR this:
println!("cargo::rustc-link-search=./libraries");

// instead, DO this:
let dir = env::var("CARGO_MANIFEST_DIR").unwrap();
println!("cargo::rustc-link-search={}/libraries", dir);
// or this:
let dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
println!("cargo::rustc-link-search={}", dir.join("libraries").display());

note, this directory is the current working directory cargo sets when executing the per-package build script, but it is NOT specified as the working directory when cargo invokes the compiler.

I can't find the exact documentation, but from my experience, the working directory for the compiler is the workspace directory, which is NOT per-package.

this means if you use relative paths (relative to CARGO_MANIFEST_DIR) in your build script, it will only work when you compile the crate standalone and your crate is not a member of a multi-package workspace. specifically, it will NOT work when the crate is used as a dependency by other crates.

9

Thank you for your explanation.

I did not know about the CARGO_MANIFEST_DIR. Thank you for sharing.