I am new to the WASM world. I tried to create a really simple rust lib that only contains add function and wants to compile it to the .wasm. I already know that the wasm-pack can achieve this. But why the cargo build --target wasm32-unknown-unknown --release can not?
// Cargo.toml
[package]
name = "hello-wasm"
version = "0.1.0"
edition = "2021"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
// lib.rs
pub fn add(left: usize, right: usize) -> usize {
left + right
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn it_works() {
let result = add(2, 2);
assert_eq!(result, 4);
}
}
The compiled target folder:
$ ls target/wasm32-unknown-unknown/release/
build/ deps/ examples/ incremental/ libhello_wasm.d libhello_wasm.rlib
Expected there is a file named hello-wasm.wasm.
With a lib.rs and no customization, you've defined a Rust library. By default, Cargo compiles libraries to .rlib files which can then be used as inputs when compiling crates that depend on this one.
In order to get a .wasm file, you must request a crate-type of cdylib in your configuration (and this is also standard when using wasm-pack):
[lib]
crate-type = ["cdylib"]
If you want the library to also be usable in tests and as a dependency, then you should specify the default mode "lib" too:
[lib]
crate-type = ["lib", "cdylib"]
(cdylib stands for "C dynamic library" — a WASM module is kind of like a dynamic library, and "C" should be understood as just meaning "native format, no Rust-specific conventions".)
Related
I'm trying to use Rust in an existing embedded C project on a M0+ micro-controller. I am using the Keil IDE to compile the code.
I can get a lib.a static library to generate, but when I try to compile it into my project I get an error saying that it can't link because
... wchart-16 clashes with wchart-32.
Because this is an existing project, I cannot change the size of wchar_t that is being used.
Is there a way to change the size of a wchar_t to use 16 bits in the compiled Rust library?
Files
lib.rs
#![no_std]
extern crate panic_halt;
#[no_mangle]
pub extern "C" fn rust_function() {
}
Cargo.toml
[package]
# package info is here
[dependencies]
panic-halt = "0.2.0"
[lib]
name = "app_interface"
crate-type = ["staticlib"] # Creates static lib
cargo\config
[target.thumbv7m-none-eabi]
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
rustflags = [
"-C", "link-arg=-Tlink.x",
]
[build]
target = "thumbv6m-none-eabi"
I have 4 files:
main.rs
mod bar;
fn main() {
let v = vec![1, 2, 3];
println!("Hello, world!");
}
lib.rs
pub mod foo;
pub mod bar;
foo.rs
pub fn say_foo() {
}
bar.rs
use crate::foo;
fn bar() {
foo::say_foo();
}
When I run cargo run I get an error saying:
error[E0432]: unresolved import `crate::foo`
--> src/bar.rs:1:5
|
1 | use crate::foo;
| ^^^^^^^^^^ no `foo` in the root
Could someone explain to me how to fix this? A bit more broadly: how does module lookup work when there's a main.rs and a lib.rs?
Edit: Adding mod foo to main.rs fixes the issue. But I don't understand this -- I was under the impression the lib.rs was the place that "exposed" all of my modules? Why do I have to declare the module in main.rs as well?
My Cargo.toml:
[package]
name = "hello-world"
version = "0.1.0"
authors = ["me#mgail.com>"]
edition = "2018"
# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[dependencies]
Let's start from the beginning. Look at the Package Layout chapter in The Cargo Book. As you can see, your package can contain lot of stuff:
a binary (something you can run) or multiple binaries,
a single library (shared code),
example(s),
benchmark(s),
integration tests.
Package layout
Not all of the possibilities are listed here, just the binary / library combinations.
A binary
This is an example of a package with single binary. Entry point is the main function in the src/main.rs.
Cargo.toml:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
src/main.rs:
fn main() {
println!("Hallo, Rust here!")
}
$ cargo run
Hallo, Rust here!
A library
This is an example of a package with a library. Libraries don't have entry points, you can't run them. They're used for functionality sharing.
Cargo.toml:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
src/lib.rs:
pub fn foo() {
println!("Hallo, Rust library here!")
}
$ cargo run
error: a bin target must be available for `cargo run`
Do you see anything in the Cargo.toml file about a binary or a library? No. The reason is that I've followed the Package Layout and the cargo knows where to look for things.
A binary and a library
This is an example of a package with a binary and a library.
Cargo.toml:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
src/lib.rs:
pub const GREETING: &'static str = "Hallo, Rust library here!";
src/main.rs:
use hallo::GREETING;
fn main() {
println!("{}", GREETING);
}
Same question, do you see anything in the Cargo.toml file about a binary or a library? No.
This package contains two things:
a binary (root src/main.rs, entry point src/main.rs::main),
a library (root src/lib.rs, shared code).
A library can be referenced from the binary via use hallo::... where the hallo is this package name (Cargo.toml -> [package] -> name).
Your problem
Cargo.toml:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
Same package layout
A library part
src/lib.rs:
pub mod bar;
pub mod foo;
src/foo.rs:
pub fn say_foo() {
println!("Foo");
}
src/bar.rs:
use crate::foo;
pub fn bar() {
foo::say_foo();
}
crate refers to src/lib.rs, because we're in the context of our library here.
Treat it as a standalone unit and refer to it via use hallo::...; from the outside world.
A binary part
src/main.rs:
use hallo::bar::bar;
fn main() {
bar();
}
Here we're just using our library.
Without a library
Same code, but lib.rs was renamed to utils.rs and (foo|bar).rs files were moved to the src/utils/ folder.
src/utils.rs:
pub mod bar;
pub mod foo;
src/utils/foo.rs:
pub fn say_foo() {
println!("Foo");
}
src/utils/bar.rs:
use super::foo;
// or use crate::utils::foo;
pub fn bar() {
foo::say_foo();
}
We can use crate here as well, but because we're in the context of our binary, the path differs.
src/main.rs:
use utils::bar::bar;
mod utils;
fn main() {
bar();
}
Here we just declared another module (utils) and we're using it.
Summary
Cargo.toml content:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
If there's a src/main.rs file, you're basically saying this:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
[[bin]]
name = "hallo"
src = "src/main.rs"
If there's a src/lib.rs file, you're basically saying this:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
[lib]
name = "hallo"
path = "src/lib.rs"
If there're both of them, you're basically saying this:
[package]
name = "hallo"
version = "0.1.0"
edition = "2018"
[[bin]]
name = "hallo"
path = "src/main.rs"
[lib]
name = "hallo"
path = "src/lib.rs"
Documentation
Package Layout
The Manifest Format
Managing Growing Projects with Packages, Crates, and Modules
In short the official Rust book has this to say:
If a package contains src/main.rs and src/lib.rs, it has two crates: a library and a binary, both with the same name as the package.
Furthermore the Rust reference says this:
crate resolves the path relative to the current crate
So there are actually two crates in your project, and to which crate the crate qualifier resolves to depends on where you call it.
Now in your code example, if you want things to compile you have to remove mod bar; from src/main.rs. Otherwise you'll be declaring that bar is a module within two crates.
After you remove that, then because in src/lib.rs you had:
pub mod foo;
pub mod bar;
bar would now be a module within src/lib.rs's crate, so the crate qualifier in bar.rs would then refer to src/lib.rs's hello-world crate, which is what you want.
One more thing, if you wanted to access items that are exposed in src/lib.rs from src/main.rs, you have to do as #zrzka said, which is to name the name of the crate that both src/lib.rs and src/main.rs share. For example, in your project which is named hello-world:
use hello_world::foo;
fn main() {
foo::say_foo();
}
is how you import the foo module declared in src/lib.rs into src/main.rs.
However it does appear that the importing behavior doesn't work the other way. I.e. if you declare some public module in src/main.rs, you can't import it into the src/lib.rs crate even when you specify the name of the crate. I couldn't find documentation describing this behavior but by testing it in Rust 1.37.0, it does appear to be the case.
The lib.rs and main.rs files are two independent entry points for your package.
When you use cargo run (or build the binary and run it explicitly), the entry point to be used is main.rs, and the crate keyword refer to the binary crate. It doesn't even have to know that there is something in lib.rs: the binary will treat the library as it would any other external crate, and it must be imported, through extern crate hello_world or, for example, use hello_world::foo.
When you import the library, however, the entry point is lib.rs, and the crate is the library crate. In this case, yes, all that you've added to lib.rs is exposed to the whole crate.
The usual worksflow in this case is to make the binary something like a thin wrapper around the library - in some extreme cases the main.rs would only contain something like
fn main() {
library::main();
}
and the whole logic (and all the project structure) goes into the library crate. One of the reasons is exactly what you've run into: the possible confusion whether this concrete module is imported in each crate in the package.
One more thing: mod defines a new module in your crate, whether a binary crate or library crate; while use only brings the module into the current scope.
In your example, use crate::foo in bar.rs tries to bring a module named foo under crate root into scope. But because there is no mod foo in main.rs, the foo module is not part of the binary crate.
I'm trying to link a Rust program with libsoundio. I'm using Windows and there's a GCC binary download available. I can link it like this if I put it in the same folder as my project:
#[link(name = ":libsoundio-1.1.0/i686/libsoundio.a")]
#[link(name = "ole32")]
extern {
fn soundio_version_string() -> *const c_char;
}
But I really want to specify #[link(name = "libsoundio")] or even #[link(name = "soundio")], and then provide a linker path somewhere else.
Where can I specify that path?
I tried the rustc-link-search suggestion as follows:
#[link(name = "libsoundio")]
#[link(name = "ole32")]
extern {
fn soundio_version_string() -> *const c_char;
}
And in .cargo/config:
[target.i686-pc-windows-gnu.libsoundio]
rustc-link-search = ["libsoundio-1.1.0/i686"]
rustc-link-lib = ["libsoundio.a"]
[target.x86_64-pc-windows-gnu.libsoundio]
rustc-link-search = ["libsoundio-1.1.0/x86_64"]
rustc-link-lib = ["libsoundio.a"]
But it still only passes "-l" "libsoundio" to gcc and fails with the same ld: cannot find -llibsoundio. Am I missing something really obvious? The docs seem to suggest this should work.
As stated in the documentation for a build script:
All the lines printed to stdout by a build script [... starting] with cargo: is interpreted directly by Cargo [...] rustc-link-search indicates the specified value should be passed to the compiler as a -L flag.
In your Cargo.toml:
[package]
name = "link-example"
version = "0.1.0"
authors = ["An Devloper <an.devloper#example.com>"]
build = "build.rs"
And your build.rs:
fn main() {
println!(r"cargo:rustc-link-search=C:\Rust\linka\libsoundio-1.1.0\i686");
}
Note that your build script can use all the power of Rust and can output different values depending on target platform (e.g. 32- and 64-bit).
Finally, your code:
extern crate libc;
use libc::c_char;
use std::ffi::CStr;
#[link(name = "soundio")]
extern {
fn soundio_version_string() -> *const c_char;
}
fn main() {
let v = unsafe { CStr::from_ptr(soundio_version_string()) };
println!("{:?}", v);
}
The proof is in the pudding:
$ cargo run
Finished debug [unoptimized + debuginfo] target(s) in 0.0 secs
Running `target\debug\linka.exe`
"1.0.3"
Ideally, you will create a soundio-sys package, using the convention for *-sys packages. That simply has a build script that links to the appropriate libraries and exposes the C methods. It will use the Cargo links key to uniquely identify the native library and prevent linking to it multiple times. Other libraries can then include this new crate and not worry about those linking details.
Another possible way is setting the RUSTFLAGS like:
RUSTFLAGS='-L my/lib/location' cargo build # or cargo run
I don't know if this is the most organized and recommended approach, but it worked for my simple project.
I found something that works OK: you can specify links in your Cargo.toml:
[package]
links = "libsoundio"
build = "build.rs"
This specifies that the project links to libsoundio. Now you can specify the search path and library name in the .cargo/config file:
[target.i686-pc-windows-gnu.libsoundio]
rustc-link-search = ["libsoundio-1.1.0/i686"]
rustc-link-lib = [":libsoundio.a"]
[target.x86_64-pc-windows-gnu.libsoundio]
rustc-link-search = ["libsoundio-1.1.0/x86_64"]
rustc-link-lib = [":libsoundio.a"]
(The : prefix tells GCC to use the actual filename and not to do all its idiotic lib-prepending and extension magic.)
You also need to create an empty build.rs:
fn main() {}
This file is never run, because the values in .cargo/config override its output, but for some reason Cargo still requires it - any time you use links = you have to have build =, even if it isn't used.
Finally in main.rs:
#[link(name = "libsoundio")]
#[link(name = "ole32")]
extern {
fn soundio_version_string() -> *const c_char;
}
As of the time of asking, if you have a bin and a lib in the same cargo project and would like to build the bin and lib with specific rustc cfg options it doesn't work.
You can build one or the other with rustc cfg options, but not both. And if you try and build the lib then the bin when the bin is compiled it recompiled the lib without the rustc options.
Is there a way to do both and if not why? Am I doomed to have to create my own build script anyways? If so, what's the point of having cargo?
EDIT
ok so maybe i was being a little dramatic
Background/Expansion
Say I had something like:
src/lib.rs
pub mod mylib {
#[cfg(not(dosomething))]
pub use self::without_cfg::dosomething;
#[cfg(dosomething)]
pub use self::with_cfg::dosomething;
mod with_cfg {
pub fn dosomething() {
println!("config option");
}
}
mod without_cfg {
pub fn dosomething() {
println!("no config option");
}
}
}
src/main.rs
extern crate modules;
use modules::mylib::dosomething;
fn main() {
dosomething();
}
So that if I compiled with the cfg option of dosomething I would get one version of a function, but if I didn't have the config I would get the "default" behavior or whatever.
Now if I try and compile with cargo rustc I can never get a version of the bin with the cfg dosomething set in the lib.
The closest I've come to being able to do it all in cargo is:
cargo rustc -v --lib -- --cfg dosomething
cargo rustc -v --bin [bin name] -- --cfg dosomething
which the first command will compile the lib with the cfg but the second command with recompile the lib without the cfg in order to create the bin.
the only workaround I've come up with is to:
cargo rustc -v --bin [bin name] -- --cfg dosomething
copy what it spits out for the command to compile such as:
rustc src/main.rs --crate-name [bin name] --crate-type bin -g --cfg dosomething --out-dir [/path/to/project]/target/debug --emit=dep-info,link -L dependency=[/path/to/project]/target/debug -L dependency=[/path/to/project]/target/debug/deps --extern modules=[/path/to/project]/target/debug/libmodules.rlib`
then run:
cargo rustc -v --lib -- --cfg dosomething
and finally copy and paste the rustc command from earlier in order to compile the bin with the lib having the cfg option set.
Is that the only way? Why can't I somehow specify which libs/bins get the rustc cfg options I want, even if its in the Cargo.toml? Or can I and I don't realize it?
For those that asked...
Cargo.toml:
[package]
name = "[bin name]"
version = "0.1.0"
authors = ["[Me] <[my email]>"]
[lib]
name = "modules"
path = "src/lib.rs"
P.S. Thank you to all those who have worked on rust and cargo, all in all I find it a pleasant environment to work in and LOVE the language. Keep up the good work.
If I understand you correctly, then Cargos features should help out here:
src/lib.rs
#[cfg(feature = "dosomething")]
pub use self::with_cfg::dosomething;
#[cfg(not(feature = "dosomething"))]
pub use self::without_cfg::dosomething;
#[cfg(feature = "dosomething")]
mod with_cfg {
pub fn dosomething() {
println!("config option");
}
}
#[cfg(not(feature = "dosomething"))]
mod without_cfg {
pub fn dosomething() {
println!("no config option");
}
}
src/main.rs
extern crate what;
use what::dosomething;
fn main() {
dosomething();
}
Cargo.toml
[package]
name = "what"
version = "0.1.0"
authors = ["An Devloper <an.devloper#example.com>"]
[features]
dosomething = []
Now, when I can compile or run in either mode:
$ cargo run
Compiling what v0.1.0 (file:///private/tmp/what)
Running `target/debug/what`
no config option
$ cargo run --features dosomething
Compiling what v0.1.0 (file:///private/tmp/what)
Running `target/debug/what`
config option
I would like to make a Rust package that contains both a reusable library (where most of the program is implemented), and also an executable that uses it.
Assuming I have not confused any semantics in the Rust module system, what should my Cargo.toml file look like?
Tok:tmp doug$ du -a
8 ./Cargo.toml
8 ./src/bin.rs
8 ./src/lib.rs
16 ./src
Cargo.toml:
[package]
name = "mything"
version = "0.0.1"
authors = ["me <me#gmail.com>"]
[lib]
name = "mylib"
path = "src/lib.rs"
[[bin]]
name = "mybin"
path = "src/bin.rs"
src/lib.rs:
pub fn test() {
println!("Test");
}
src/bin.rs:
extern crate mylib; // not needed since Rust edition 2018
use mylib::test;
pub fn main() {
test();
}
Simple
Create a src/main.rs that will be used as the defacto executable. You do not need to modify your Cargo.toml and this file will be compiled to a binary of the same name as the library.
The project contents:
% tree
.
├── Cargo.toml
└── src
├── lib.rs
└── main.rs
Cargo.toml
[package]
name = "example"
version = "0.1.0"
edition = "2018"
src/lib.rs
use std::error::Error;
pub fn really_complicated_code(a: u8, b: u8) -> Result<u8, Box<dyn Error>> {
Ok(a + b)
}
src/main.rs
fn main() {
println!(
"I'm using the library: {:?}",
example::really_complicated_code(1, 2)
);
}
And execute it:
% cargo run -q
I'm using the library: Ok(3)
Flexible
If you wish to control the name of the binary or have multiple binaries, you can create multiple binary source files in src/bin and the rest of your library sources in src. You can see an example in my project. You do not need to modify your Cargo.toml at all, and each source file in src/bin will be compiled to a binary of the same name.
The project contents:
% tree
.
├── Cargo.toml
└── src
├── bin
│ └── mybin.rs
└── lib.rs
Cargo.toml
[package]
name = "example"
version = "0.1.0"
edition = "2018"
src/lib.rs
use std::error::Error;
pub fn really_complicated_code(a: u8, b: u8) -> Result<u8, Box<dyn Error>> {
Ok(a + b)
}
src/bin/mybin.rs
fn main() {
println!(
"I'm using the library: {:?}",
example::really_complicated_code(1, 2)
);
}
And execute it:
% cargo run --bin mybin -q
I'm using the library: Ok(3)
See also:
How can I specify which crate `cargo run` runs by default in the root of a Cargo workspace?
An alternate solution is to not try to cram both things into one package. For slightly larger projects with a friendly executable, I've found it very nice to use a workspace.
Here, I create a binary project that includes a library inside of it, but there are many possible ways of organizing the code:
% tree the-binary
the-binary
├── Cargo.toml
├── src
│ └── main.rs
└── the-library
├── Cargo.toml
└── src
└── lib.rs
Cargo.toml
This uses the [workspace] key and depends on the library:
[package]
name = "the-binary"
version = "0.1.0"
edition = "2018"
[workspace]
[dependencies]
the-library = { path = "the-library" }
src/main.rs
fn main() {
println!(
"I'm using the library: {:?}",
the_library::really_complicated_code(1, 2)
);
}
the-library/Cargo.toml
[package]
name = "the-library"
version = "0.1.0"
edition = "2018"
the-library/src/lib.rs
use std::error::Error;
pub fn really_complicated_code(a: u8, b: u8) -> Result<u8, Box<dyn Error>> {
Ok(a + b)
}
And execute it:
% cargo run -q
I'm using the library: Ok(3)
There are two big benefits to this scheme:
The binary can now use dependencies that only apply to it. For example, you can include lots of crates to improve the user experience, such as command line parsers or terminal formatting. None of these will "infect" the library.
The workspace prevents redundant builds of each component. If we run cargo build in both the the-library and the-binary directory, the library will not be built both times — it's shared between both projects.
You can put lib.rs and main.rs to sources folder together. There is no conflict and cargo will build both things.
To resolve documentaion conflict add to your Cargo.toml:
[[bin]]
name = "main"
doc = false