vcpkg/scripts/azure-pipelines/owners-db

Owners DB helpers

Summary

This directory contains two small Node.js CLI helpers used by the Azure Pipelines owners-db step to build two plain-text database files used by downstream tooling:

• file_script.ts — builds databases from a local info directory (used in CI runs where vcpkg is installed locally).
• file_script_from_cache.ts — builds databases by downloading package ZIPs from a binary cache (used in PR runs that can consult prebuilt artifacts).

Both scripts produce the same output file formats described below:

• VCPKGDatabase.txt — a newline-separated list of entries of the form port:triplet:/path/inside/package.
• VCPKGHeadersDatabase.txt — a newline-separated list of entries of the form port:triplet:relative/header/path

These files are emitted to --out-dir (default scripts/list_files).

Usage

file_script.ts (local info-dir mode)

file_script.ts --info-dir <path-to-info-dir> [--out-dir <path>]

Behavior and input format:

• --info-dir <path> should point at a directory containing vcpkg-generated .list files (the same layout created by vcpkg under installed/<triplet>/vcpkg/info/).

• Each file in that directory is expected to follow the filename convention used by vcpkg info files. The script parses the filename by splitting on underscores and constructs a package identifier using the first and third components:

  <...>.list --> package id = <package>:<triplet>

• Each .list file is plain text with one relative file path per line. Lines that are empty, or which end in / are ignored. If a line contains any prefix before a /, the script strips the prefix and uses only the path starting at the first /.

Examples of lines processed from .list files:

• share/zlib/include/zlib.h -> entry zlib:x64-windows:/share/zlib/include/zlib.h
• someprefix/share/zlib/include/zlib.h -> same as above (prefix before first / is dropped)

file_script_from_cache.ts (PR cache mode)

file_script_from_cache.ts --pr-hashes <pr-hashes.json> --blob-base-url <blob-base-url> [--target-branch <branch>] [--out-dir <path>]

Required inputs:

• --pr-hashes <pr-hashes.json> is a JSON file produced by the vcpkg tooling that lists changed ports and their ABIs. The script expects a top-level JSON array of objects where each object contains at least the following fields:

  { "name": "", "triplet": "", "state": "", "abi": "" }

  Important: in this script the abi field is expected to be the 64-hex SHA string used to name the ZIP blob in the binary cache (the script validates abi against /^[a-f0-9]{64}$/).

• --blob-base-url <blob-base-url> should be a URL that points to a binary cache container and include any required SAS token (for example: https://<account>.blob.core.windows.net/cache?<sas>). The script will insert /<sha>.zip into that base URL to download the package ZIP for each port/abi pair and then enumerate files inside each ZIP.

Output file formats

Both scripts write two files into the chosen --out-dir (default scripts/list_files):

• VCPKGDatabase.txt

  • Each line has the form: <port>:<triplet>:<filepath>
  • <filepath> begins with a leading / when sourced from .list files or ZIP entries; it is the path inside the package (for example /share/zlib/include/zlib.h).

• VCPKGHeadersDatabase.txt

  • Each line has the form: <port>:<triplet>:<relative/header/path>
  • Only files whose path starts with /include/ are recorded here and the /include/ prefix is removed from the path. For example, an entry for /include/zlib.h will produce zlib:x64-windows:zlib.h.

Exit codes and errors

• Both scripts print an error and exit non-zero on fatal problems (invalid arguments, invalid pr-hashes.json, or failed git diff in the cache variant).
• file_script_from_cache.ts will attempt to download each expected ZIP; failures to download or process a single package are reported as warnings and the script continues — missing entries will simply be absent from the output.

Examples

Local info-dir:

npx ts-node ./file_script.ts --info-dir /mnt/vcpkg-ci/installed/vcpkg/info --out-dir ./scripts/list_files

PR cache mode (pipeline example using BCACHE_SAS_TOKEN set as a secret variable):

# pipeline constructs the URL from the secret token and passes it to the script
blob="https://vcpkgbinarycachewus.blob.core.windows.net/cache?${BCACHE_SAS_TOKEN}"
npx --yes ts-node ./file_script_from_cache.ts --pr-hashes /path/to/pr-hashes.json --blob-base-url "$blob" --target-branch origin/master --out-dir ./scripts/list_files