README.md - mozsearch

This directory exists to provide the C++ interface to the mp4parse-rust code.

The code itself is hosted at https://github.com/mozilla/mp4parse-rust and

vendored into the /third_party/rust directory, so the only things here are the

moz.build file which specifies how the dynamically generated bindings header

should be generated and mp4parse.h, the header which consumers should include.

It includes the dynamically-generated bindings header as well as any

additional support code for FFI.

# Updating the version from the github repository

1. In /toolkit/library/rust/shared/Cargo.toml, Set the `rev` attribute of the

   `mp4parse_capi` dependency to the revision you want to use.

2. Run `mach vendor rust` (`--force` may be necessary since the `mp4parse`

   crate's lib.rs is quite large).

3. Verify the expected changes in /third_party/rust.

4. Build, run try, etc.

NOTE: Git has no concept of checking out a subdirectory, so `cargo` will

search the whole repository to find the crate. Because the `mp4parse_capi`

depends on the `mp4parse` crate in the same repository via a relative path,

both crates will be vendored into /third_party/rust and should be part of the

same revision of mp4parse-rust.

# Developing changes to mp4parse-rust crates

Before committing changes to the github repository, it's a good idea to test

them out in the context of mozilla-central. There are a number of ways to

achieve this with various trade-offs, but here are the two I recommend. Both

start the same way:

1. `git clone https://github.com/mozilla/mp4parse-rust` somewhere outside

   mozilla-central. For example: /Users/your_username/src/mp4parse-rust.

## For rapid iteration on local, uncommitted changes

2. In /toolkit/library/rust/shared/Cargo.toml, change the `mp4parse_capi`

   dependency to

```

   mp4parse_capi = { path = "/Users/your_username/src/mp4parse-rust/mp4parse_capi" }

```

3. Run `mach vendor rust`; the code in third_party/rust/mp4parse_capi and

   third_party/rust/mp4parse will be removed, indicating the code in your

   local checkout is being used instead.

4. In the moz.build in this directory, in `ffi_generated.inputs`, change

   '/third_party/rust/mp4parse_capi' to

   '//Users/your_username/src/mp4parse-rust/mp4parse_capi'. Note the

   double-slash, it's required to reference paths outside mozilla-central.

5. Build and run the code or tests normally to exercise the code in

   /Users/your_username/src/mp4parse-rust.

This is a fast way to try experiment with the rust code, but because it exists

outside the mozilla-central tree, it cannot be used with try.

## For validation of local, committed changes

2. In /toolkit/library/rust/shared/Cargo.toml, change the `mp4parse_capi`

   dependency to

```

   mp4parse_capi = { git = "file:///Users/your_username/src/mp4parse-rust" }

```

3. Run `mach vendor rust`; the local, committed code will be copied into

   third_party/rust/mp4parse_capi and third_party/rust/mp4parse. Confirm the

   diff is what you expect.

4. Unlike above, no changes to moz.build are necessary; if locally changed,

   make sure to revert.

5. Build and run the code or tests normally to exercise the code in

   /Users/your_username/src/mp4parse-rust. This can include try runs, but if

   you make any additional changes, you must be sure to commit them in your

   local git checkout of mp4parse-rust and re-run `mach vendor rust`.

This is a more thorough way to test local changes to the rust code since try

is available, but it's slower than the `path` dependency approach above

because every change must be committed and copied into the mozilla-central

tree with `mach vendor rust`.