mirror of https://github.com/microsoft/vcpkg.git
97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
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)
|
|
|
|
```text
|
|
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:
|
|
|
|
<package>_<...>_<triplet>.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)
|
|
|
|
```text
|
|
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": "<port-name>",
|
|
"triplet": "<triplet>",
|
|
"state": "<state>",
|
|
"abi": "<sha>"
|
|
}
|
|
|
|
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:
|
|
|
|
```sh
|
|
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):
|
|
|
|
```sh
|
|
# 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
|
|
```
|