media/mp4parse-rust/README.md

   1 This directory exists to provide the C++ interface to the mp4parse-rust code.
   2 The code itself is hosted at https://github.com/mozilla/mp4parse-rust and
   3 vendored into the /third_party/rust directory, so the only things here are the
   4 moz.build file which specifies how the dynamically generated bindings header
   5 should be generated and mp4parse.h, the header which consumers should include.
   6 It includes the dynamically-generated bindings header as well as any
   7 additional support code for FFI.
   8
   9 # Updating the version from the github repository
  10
  11 1. In /toolkit/library/rust/shared/Cargo.toml, Set the `rev` attribute of the
  12    `mp4parse_capi` dependency to the revision you want to use.
  13 2. Run `mach vendor rust` (`--force` may be necessary since the `mp4parse`
  14    crate's lib.rs is quite large).
  15 3. Verify the expected changes in /third_party/rust.
  16 4. Build, run try, etc.
  17
  18 NOTE: Git has no concept of checking out a subdirectory, so `cargo` will
  19 search the whole repository to find the crate. Because the `mp4parse_capi`
  20 depends on the `mp4parse` crate in the same repository via a relative path,
  21 both crates will be vendored into /third_party/rust and should be part of the
  22 same revision of mp4parse-rust.
  23
  24 # Developing changes to mp4parse-rust crates
  25
  26 Before committing changes to the github repository, it's a good idea to test
  27 them out in the context of mozilla-central. There are a number of ways to
  28 achieve this with various trade-offs, but here are the two I recommend. Both
  29 start the same way:
  30
  31 1. `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
  36 2. 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    ```
  41 3. 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.
  44 4. 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.
  48 5. Build and run the code or tests normally to exercise the code in
  49    /Users/your_username/src/mp4parse-rust.
  50
  51 This is a fast way to try experiment with the rust code, but because it exists
  52 outside the mozilla-central tree, it cannot be used with try.
  53
  54 ## For validation of local, committed changes
  55
  56 2. 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    ```
  61 3. 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.
  64 4. Unlike above, no changes to moz.build are necessary; if locally changed,
  65    make sure to revert.
  66 5. 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
  71 This is a more thorough way to test local changes to the rust code since try
  72 is available, but it's slower than the `path` dependency approach above
  73 because every change must be committed and copied into the mozilla-central
  74 tree with `mach vendor rust`.