================================
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:

.. code-block:: sh

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

to interact with it.


Template ``moz.yaml`` file
==========================

.. literalinclude:: template.yaml
  :language: YAML

Common Vendoring Operations
===========================


Update to the latest upstream revision:

.. code-block:: 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:

.. code-block:: sh

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

Vendor a specific revision:

.. code-block:: 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:

.. code-block:: 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}']