rust.rst (8761B)
1 .. _rust: 2 3 ============================== 4 Including Rust Code in Firefox 5 ============================== 6 7 This page explains how to add, build, link, and vendor Rust crates. 8 9 The `code documentation <../../writing-rust-code>`_ explains how to write and 10 work with Rust code in Firefox. The 11 `test documentation <../../testing-rust-code>`_ explains how to test and debug 12 Rust code in Firefox. 13 14 Linking Rust crates into libxul 15 =============================== 16 17 Rust crates that you want to link into libxul should be listed in the 18 ``dependencies`` section of 19 `toolkit/library/rust/shared/Cargo.toml <https://searchfox.org/mozilla-central/source/toolkit/library/rust/shared/Cargo.toml>`_. 20 You must also add an ``extern crate`` reference to 21 `toolkit/library/rust/shared/lib.rs <https://searchfox.org/mozilla-central/source/toolkit/library/rust/shared/lib.rs>`_. 22 This ensures that the Rust code will be linked properly into libxul as well 23 as the copy of libxul used for gtests. (Even though Rust 2018 mostly doesn't 24 require ``extern crate`` declarations, these ones are necessary because the 25 gkrust setup is non-typical.) 26 27 After adding your crate, execute ``cargo update -p gkrust-shared`` to update 28 the ``Cargo.lock`` file. You will also need to do this any time you change the 29 dependencies in a ``Cargo.toml`` file. If you don't, you will get a build error 30 saying **"error: the lock file /home/njn/moz/mc3/Cargo.lock needs to be updated 31 but --frozen was passed to prevent this"**. 32 33 By default, all Cargo packages in the mozilla-central repository are part of 34 the same 35 `workspace <https://searchfox.org/mozilla-central/source/toolkit/library/rust/shared/lib.rs>`_ 36 and will share the ``Cargo.lock`` file and ``target`` directory in the root of 37 the repository. You can change this behavior by adding a path to the 38 ``exclude`` list in the top-level ``Cargo.toml`` file. You may want to do 39 this if your package's development workflow includes dev-dependencies that 40 aren't needed by general Firefox developers or test infrastructure. 41 42 The actual build mechanism is as follows. The build system generates a special 43 'Rust unified library' crate, compiles that to a static library 44 (``libgkrust.a``), and links that into libxul, so all public symbols will be 45 available to C++ code. Building a static library that is linked into a dynamic 46 library is easier than building dynamic libraries directly, and it also avoids 47 some subtle issues around how mozalloc works that make the Rust dynamic library 48 path a little wonky. 49 50 Linking Rust crates into something else 51 ======================================= 52 53 To link Rust code into libraries other than libxul, create a directory with a 54 ``Cargo.toml`` file for your crate, and a ``moz.build`` file that contains: 55 56 .. code-block:: python 57 58 RustLibrary('crate_name') 59 60 where ``crate_name`` matches the name from the ``[package]`` section of your 61 ``Cargo.toml``. You can refer to `the moz.build file <https://searchfox.org/mozilla-central/rev/603b9fded7a11ff213c0f415198cd637b7c86614/toolkit/library/rust/moz.build#9>`_ and `the Cargo.toml file <https://searchfox.org/mozilla-central/rev/603b9fded7a11ff213c0f415198cd637b7c86614/toolkit/library/rust/Cargo.toml>`_ that are used for libxul. 62 63 You can then add ``USE_LIBS += ['crate_name']`` to the ``moz.build`` file 64 that defines the binary as you would with any other library in the tree. 65 66 .. important:: 67 68 You cannot link a Rust crate into an intermediate library that will be 69 eventually linked into libxul. The build system enforces that only a single 70 ``RustLibrary`` may be linked into a binary. If you need to do this, you 71 will have to add a ``RustLibrary`` to link to any standalone binaries that 72 link the intermediate library, and also add the Rust crate to the libxul 73 dependencies as in `linking Rust Crates into libxul`_. 74 75 Conditional compilation 76 ======================== 77 78 Edit `tool/library/rust/gkrust-features.mozbuild 79 <https://searchfox.org/mozilla-central/source/toolkit/library/rust/gkrust-features.mozbuild>`_ 80 to expose build flags as Cargo features. 81 82 Standalone Rust programs 83 ======================== 84 85 It is also possible to build standalone Rust programs. First, put the Rust 86 program (including the ``Cargo.toml`` file and the ``src`` directory) in its 87 own directory, and add an empty ``moz.build`` file to the same directory. 88 89 Then, if the standalone Rust program must run on the compile target (e.g. 90 because it's shipped with Firefox) then add this rule to the ``moz.build`` 91 file: 92 93 .. code-block:: python 94 95 RUST_PROGRAMS = ['prog_name'] 96 97 where *prog_name* is the name of the executable as specified in the 98 ``Cargo.toml`` (and probably also matches the name of the directory). 99 100 Otherwise, if the standalone Rust program must run on the compile host (e.g. 101 because it's used to build Firefox but not shipped with Firefox) then do the 102 same thing, but use ``HOST_RUST_PROGRAMS`` instead of ``RUST_PROGRAMS``. 103 104 Where should I put my crate? 105 ============================ 106 107 If your crate's canonical home is mozilla-central, you can put it next to the 108 related code in the appropriate directory. 109 110 If your crate is mirrored into mozilla-central from another repository, and 111 will not be actively developed in mozilla-central, you can simply list it 112 as a ``crates.io``-style dependency with a version number, and let it be 113 vendored into the ``third_party/rust`` directory. 114 115 If your crate is mirrored into mozilla-central from another repository, but 116 will be actively developed in both locations, you should send mail to the 117 dev-builds mailing list to start a discussion on how to meet your needs. 118 119 Third-party crate dependencies 120 ============================== 121 122 Third-party dependencies for in-tree Rust crates are *vendored* into the 123 ``third_party/rust`` directory of mozilla-central. This means that a copy of 124 each third-party crate's code is committed into mozilla-central. As a result, 125 building Firefox does not involve downloading any third-party crates. 126 127 If you add a dependency on a new crate you must run ``mach vendor rust`` to 128 vendor the dependencies into that directory. (Note that ``mach vendor rust`` 129 `may not work as well on Windows <https://bugzilla.mozilla.org/show_bug.cgi?id=1938341>`_ 130 as on other platforms.) 131 132 When it comes to checking the suitability of third-party code for inclusion 133 into mozilla-central, keep the following in mind. 134 135 - ``mach vendor rust`` will check that the licenses of all crates are suitable. 136 - ``mach vendor rust`` will run ``cargo vet`` to ensure that the crates have been audited. If not, 137 you will have to audit them using ``mach cargo vet`` to check that the code looks reasonable 138 (especially unsafe code) and that there are reasonable tests. All vendored crates must be audited. 139 - Third-party crate tests aren't run, which means that large test fixtures will 140 bloat mozilla-central. Consider working with upstream to mark those test 141 fixtures with ``[package] exclude = ...`` as described 142 `here <https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields>`_. 143 - If you specify a dependency on a branch, pin it to a specific revision, 144 otherwise other people will get unexpected changes when they run ``./mach 145 vendor rust`` any time the branch gets updated. See `bug 1612619 146 <https://bugzil.la/1612619>`_ for a case where such a problem was fixed. 147 - Other than that, there is no formal sign-off procedure, but one may be added 148 in the future. 149 150 Note that all dependencies will be vendored, even ones that aren't used due to 151 disabled features. It's possible that multiple versions of a crate will end up 152 vendored into mozilla-central. 153 154 Patching third-party crates 155 =========================== 156 157 Sometimes you might want to temporarily patch a third-party crate, for local 158 builds or for a try push. 159 160 To do this, first add an entry to the ``[patch.crates-io]`` section of the 161 top-level ``Cargo.toml`` that points to the crate within ``third_party``. For 162 example 163 164 .. code-block:: toml 165 166 bitflags = { path = "third_party/rust/bitflags" } 167 168 Next, run ``cargo update -p $CRATE_NAME --precise $VERSION``, where 169 ``$CRATE_NAME`` is the name of the patched crate, and ``$VERSION`` is its 170 version number. This will update the ``Cargo.lock`` file. 171 172 Then, make the local changes to the crate. 173 174 Finally, make sure you don't accidentally land the changes to the crate or the 175 ``Cargo.lock`` file. 176 177 For an example of a more complex workflow involving a third-party crate, see 178 `mp4parse-rust/README.md <https://searchfox.org/mozilla-central/source/media/mp4parse-rust/README.md>`_. 179 It describes the workflow for a crate that is hosted on GitHub, and for which 180 changes are made via GitHub pull requests, but all pull requests must also be 181 tested within mozilla-central before being merged.