# Vendoring Third Party Components

The firefox source tree vendors many third party dependencies. The build system
provides a normalized way to keep track of:

1. The upstream source license, location and revision

2. (Optionally) The upstream source modification, including

   1. Mozilla-specific patches
   2. Custom update actions, such as excluding some files, moving files around
      etc.

This is done through a descriptive `moz.yaml` file added to the third
party sources, and the use of:

```sh
./mach vendor [options] ./path/to/moz.yaml
```

to interact with it.

## Template `moz.yaml` file

```{literalinclude} template.yaml
:language: text
```

## Common Vendoring Operations

Update to the latest upstream revision:

```sh
./mach vendor /path/to/moz.yaml
```

Check for latest revision, returning no output if it is up-to-date, and a
version identifier if it needs to be updated:

```sh
./mach vendor /path/to/moz.yaml --check-for-update
```

Vendor a specific revision:

```sh
./mach vendor /path/to/moz.yaml -r $REVISION --force
```

In the presence of patches, two steps are needed:

1. Vendor without applying patches (patches are applied *after*
   `update-actions`) through `--patch-mode none`
2. Apply patches on updated sources through `--patch-mode only`

In the absence of patches, a single step is needed, and no extra argument is
required.

## Vendoring Actions

Vendoring actions in the `moz.yaml` file can be configured to run either before
or after patches are applied using separate sections:

- Actions in `update-actions` run **before** patches are applied
- Actions in `post-patch-actions` run **after** patches are applied

This separation is useful when you need to run scripts that depend on Mozilla-specific
patches being applied first, such as:

- Code generation scripts that need patched configuration files
- Build system updates that depend on patched build definitions
- Processing steps that require Mozilla-specific modifications to be in place

Example:

```yaml
# Actions that run before patches are applied
update-actions:
  - action: run-script
    script: '{yaml_dir}/pre_patch_script.sh'
    cwd: '{yaml_dir}'

# Actions that run after patches are applied
post-patch-actions:
  - action: run-script
    script: '{yaml_dir}/post_patch_script.sh'
    cwd: '{yaml_dir}'
    args: ['{revision}']
```
