DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81
.. _rust:

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 <https://dxr.mozilla.org/mozilla-central/source/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 <https://dxr.mozilla.org/mozilla-central/source/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 <https://dxr.mozilla.org/mozilla-central/source/toolkit/library/rust/shared/lib.rs>`_
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:

.. code-block:: python


Where *crate_name* matches the name from the ``[package]`` section of your
``Cargo.toml``. You can refer to `the moz.build file <https://dxr.mozilla.org/mozilla-central/rev/3f4c3a3cabaf94958834d3a8935adfb4a887942d/toolkit/library/rust/moz.build#7>`_ and `the Cargo.toml file <https://dxr.mozilla.org/mozilla-central/rev/3f4c3a3cabaf94958834d3a8935adfb4a887942d/toolkit/library/rust/Cargo.toml>`_ 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.