"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/build/docs/rust.rst" (17 Sep 2019, 4029 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field.

Including Rust Code in Firefox

The build system has support for building and linking Rust crates. Rust code is built using cargo in the typical way, so it is straightforward to take an existing Rust crate and integrate it into Firefox.

Linking Rust Crates into libxul

Rust crates that you want to link into libxul should be listed in the dependencies section of toolkit/library/rust/shared/Cargo.toml. After adding your crate, execute cargo update -p gkrust-shared to update the Cargo.lock file. You'll also need to add an extern crate reference to toolkit/library/rust/shared/lib.rs. This ensures that the Rust code will be linked properly into libxul as well as the copy of libxul used for gtests.

By default, all Cargo packages in the mozilla-central repository are part of the same workspace and will share the Cargo.lock file and target directory in the root of the repository. You can change this behavior by adding a path to the excludes list in the top-level Cargo.toml file. You may want to do this if your package's development workflow includes dev-dependencies that aren't needed by general Firefox developers or test infrastructure.

Linking Rust Crates into something else

There currently is not any Rust code being linked into binaries other than libxul. If you would like to do so, you'll need to create a directory with a Cargo.toml file for your crate, and a moz.build file that contains:

RustLibrary('crate_name')

Where crate_name matches the name from the [package] section of your Cargo.toml. You can refer to the moz.build file and the Cargo.toml file that are used for libxul.

You can then add USE_LIBS += ['crate_name'] to the moz.build file that defines the binary as you would with any other library in the tree.

Important

You cannot link a Rust crate into an intermediate library that will wind up being linked into libxul. The build system enforces that only a single RustLibrary may be linked into a binary. If you need to do this, you will have to add a RustLibrary to link to any standalone binaries that link the intermediate library, and also add the Rust crate to the libxul dependencies as in linking Rust Crates into libxul.

Where Should I put my Crate?

If your crate's canonical home is mozilla-central, you can put it next to the other code in the module it belongs to.

If your crate is mirrored into mozilla-central from another repository, and will not be actively developed in mozilla-central, you can simply list it as a crates.io-style dependency with a version number, and let it be vendored into the third_party/rust directory.

If your crate is mirrored into mozilla-central from another repository, but will be actively developed in both locations, you should send mail to the dev-builds mailing list to start a discussion on how to meet your needs.

Crate dependencies

All dependencies for in-tree Rust crates are vendored into the third_party/rust directory. Currently if you add a dependency on a new crate you must run mach vendor rust to vendor the dependencies into that directory. In the future we hope to make it so that you only need to vendor the dependencies in order to build your changes in a CI push.