An Introduction to Google's depot_tools and gclient

1. depot_tools

depot_tools is a collection of utilities for managing Chromium source code and the Chromium development workflow. depot_tools includes gclient; WebRTC and Chromium development both depend on them. Build tools such as gn and ninja used for WebRTC are also in this repository.

Installation and setup are described here.

Tool list—most are rarely used, but useful to know:

• gclient: Meta-checkout tool for Subversion and git checkouts. Works on Linux, OS X, and Windows; supports svn and git.

• gcl: Rietveld code review tool for Subversion. Runs presubmit scripts.

• git-cl: Rietveld code review tool for git. Runs presubmit scripts.

• svn [Windows only]: Subversion client for Chromium development.

• drover: Quickly revert svn commits.

• cpplint.py: Checks C++ style compliance.

• pylint: Checks Python style compliance.

• presubmit_support.py: Runs PRESUBMIT.py checks.

• repo: The repo tool.

• wtf: Shows active git branches in a Chromium OS checkout.

• weekly: Shows git checkout logs for a developer since a given date.

• git-gs: Wrapper around git grep for relevant source types.

• zsh-goodies: Completions for zsh users.

2. gclient

gclient is a cross-platform git repository management tool written in Python. It is similar to git submodules and manages modular dependencies. Multiple git repositories can form a solution, so one repository can be shared across solutions.

gclient's core job is to fetch all git repositories defined in a solution's DEPS file into the right directories. It also adds helpers such as Hooks.

2.1. Concepts

• Solution: A repository containing a DEPS file that lists all dependencies for that solution;
• roll_deps: A gclient helper to update dependency versions in DEPS;
• Gerrit/Rietveld: Code review systems integrated with git/svn;
• Hooks: Scripts gclient runs after syncing code;
• .gclient: File created by gclient config, recording solutions to fetch;
• DEPS: File gclient uses to manage project dependencies;
• CL: Change List, similar to git diff and pack;
• LKGR: Last Known Good Revision, a git tag for the latest fully tested version;
• managed: Legacy gclient mode, not recommended; helped developers unfamiliar with git;
• inlcude_rules: Specifies which directories/files under the current tree may be included by other code;
• specific_include_rules: Same as include_rules but supports wildcards;

2.2. .gclient File

This is effectively a Python script. A solution looks like:

solutions = [
  {
    "name": "src",
    "url": "https://webrtc.googlesource.com/src.git",
    "deps_file": "DEPS",
    "managed": False,
    "custom_deps": {},
  },
]
target_os = ["ios", "mac"]

Key fields:

• solutions: Array of projects to fetch, as described above.
• target_os: Optional array of target operating systems for platform-specific dependencies.
• deps_file: Each project may include an optional DEPS file, described below.
• name: Checkout path.
• url: Remote repository to clone.
• custom_deps: (Optional) Override deps and deps_os in child DEPS files. Useful when you want writable checkouts instead of read-only dependencies.
• custom_vars: (Optional) Override variables defined in child DEPS vars.

2.3. DEPS File

WebRTC's DEPS file is at src/DEPS -> view here {: .prompt-info }

DEPS specifies project dependencies. It is also a Python script, roughly like:

deps = {
  # TODO(kjellander): Move this to be Android-only.
  'src/base':
    'https://chromium.googlesource.com/chromium/src/base@aa6dbe6d6a68e6503360a7e0e18b8464c56fc159',
  'src/build':
    'https://chromium.googlesource.com/chromium/src/build@5bce81deee6d30ac58c45f6cd53e859c62780687',
  'src/buildtools':
    'https://chromium.googlesource.com/chromium/src/buildtools@94d7b86a83537f8a7db7dccb0bf885739f7a81aa',
  # Gradle 6.6.1. Used for testing Android Studio project generation for WebRTC.
  'src/examples/androidtests/third_party/gradle': {
    'url': 'https://chromium.googlesource.com/external/github.com/gradle/gradle.git@f2d1fb54a951d8b11d25748e4711bec8d128d7e3',
    'condition': 'checkout_android',
  },
  'src/ios': {
    'url': 'https://chromium.googlesource.com/chromium/src/ios@9e33110a5d6d22342302264579598e42c4623ebb',
    'condition': 'checkout_ios',
  },
  'src/testing':
    'https://chromium.googlesource.com/chromium/src/testing@a1b47952f3737c536f14a74ff70bc12ed2c1ac7d',
  'src/third_party':
    'https://chromium.googlesource.com/chromium/src/third_party@91945cadc24feea7b44e1682d17844b6ab508d6d',
}

hooks = [
  {
    # This clobbers when necessary (based on get_landmines.py). It should be
    # an early hook but it will need to be run after syncing Chromium and
    # setting up the links, so the script actually exists.
    'name': 'landmines',
    'pattern': '.',
    'action': [
        'python3',
        'src/build/landmines.py',
        '--landmine-scripts',
        'src/tools_webrtc/get_landmines.py',
        '--src-dir',
        'src',
    ],
  },
  ]

Variables you can define:

• deps: Dictionary of sub-dependencies and their repositories.
• hooks: Hooks run after sync; see gclient runhooks.

2.4. Common gclient Commands

2.4.1. gclient config

Creates the .gclient file and initializes the solution to fetch, including repository URL and checkout location. The first step when fetching WebRTC also creates .gclient, for example:

solutions = [
  {
    "name": "src",
    "url": "https://webrtc.googlesource.com/src.git",
    "deps_file": "DEPS",
    "managed": False,
    "custom_deps": {},
  },
]
target_os = ["ios", "mac"]

2.4.2. gclient sync

Syncs all repositories in the solution. Common flags:

• -f, --force: force update unchanged modules;

• --with_branch_heads: clone branch_heads refspecs in addition to default refspecs;

• --with_tags: clone git tags in addition to default refspecs;

• --no-history: do not fetch git commit history;

• --revision <version>: check out a specific version;

• --nohooks: do not run hooks after sync.

2.4.3. gclient runhooks

Runs hooks manually. Use this when you synced with --nohooks and want to execute DEPS hooks later.

2.4.4. gclient fetch

Equivalent to running git fetch in every repository.

2.4.5. gclient diff

Equivalent to running git diff in every repository.

2.4.6. gclient status

Equivalent to running git status in every repository.

Run gclient --help for more commands.