1This directory exists to provide the C++ interface to the mp4parse-rust code.
2The code itself is hosted at https://github.com/mozilla/mp4parse-rust and
3vendored into the /third_party/rust directory, so the only things here are the
4moz.build file which specifies how the dynamically generated bindings header
5should be generated and mp4parse.h, the header which consumers should include.
6It includes the dynamically-generated bindings header as well as any
7additional support code for FFI.
8
9# Updating the version from the github repository
10
111. In /toolkit/library/rust/shared/Cargo.toml, Set the `rev` attribute of the
12   `mp4parse_capi` dependency to the revision you want to use.
132. Run `mach vendor rust` (`--build-peers-said-large-imports-were-ok` may be
14   necessary since the `mp4parse` crate's lib.rs is quite large).
153. Verify the expected changes in /third_party/rust.
164. Build, run try, etc.
17
18NOTE: Git has no concept of checking out a subdirectory, so `cargo` will
19search the whole repository to find the crate. Because the `mp4parse_capi`
20depends on the `mp4parse` crate in the same repository via a relative path,
21both crates will be vendored into /third_party/rust and should be part of the
22same revision of mp4parse-rust.
23
24# Developing changes to mp4parse-rust crates
25
26Before committing changes to the github repository, it's a good idea to test
27them out in the context of mozilla-central. There are a number of ways to
28achieve this with various trade-offs, but here are the two I recommend. Both
29start the same way:
30
311. `git clone https://github.com/mozilla/mp4parse-rust` somewhere outside
32   mozilla-central. For example: /Users/your_username/src/mp4parse-rust.
33
34## For rapid iteration on local, uncommitted changes
35
362. In /toolkit/library/rust/shared/Cargo.toml, change the `mp4parse_capi`
37   dependency to
38   ```
39   mp4parse_capi = { path = "/Users/your_username/src/mp4parse-rust/mp4parse_capi" }
40   ```
413. Run `mach vendor rust`; the code in third_party/rust/mp4parse_capi and
42   third_party/rust/mp4parse will be removed, indicating the code in your
43   local checkout is being used instead.
444. In the moz.build in this directory, in `ffi_generated.inputs`, change
45   '/third_party/rust/mp4parse_capi' to
46   '//Users/your_username/src/mp4parse-rust/mp4parse_capi'. Note the
47   double-slash, it's required to reference paths outside mozilla-central.
485. Build and run the code or tests normally to exercise the code in
49   /Users/your_username/src/mp4parse-rust.
50
51This is a fast way to try experiment with the rust code, but because it exists
52outside the mozilla-central tree, it cannot be used with try.
53
54## For validation of local, committed changes
55
562. In /toolkit/library/rust/shared/Cargo.toml, change the `mp4parse_capi`
57   dependency to
58   ```
59   mp4parse_capi = { git = "file:///Users/your_username/src/mp4parse-rust" }
60   ```
613. Run `mach vendor rust`; the local, committed code will be copied into
62   third_party/rust/mp4parse_capi and third_party/rust/mp4parse. Confirm the
63   diff is what you expect.
644. Unlike above, no changes to moz.build are necessary; if locally changed,
65   make sure to revert.
665. Build and run the code or tests normally to exercise the code in
67   /Users/your_username/src/mp4parse-rust. This can include try runs, but if
68   you make any additional changes, you must be sure to commit them in your
69   local git checkout of mp4parse-rust and re-run `mach vendor rust`.
70
71This is a more thorough way to test local changes to the rust code since try
72is available, but it's slower than the `path` dependency approach above
73because every change must be committed and copied into the mozilla-central
74tree with `mach vendor rust`.
75