diff options
Diffstat (limited to 'vcpkg/scripts/azure-pipelines/owners-db/README.md')
| -rw-r--r-- | vcpkg/scripts/azure-pipelines/owners-db/README.md | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/vcpkg/scripts/azure-pipelines/owners-db/README.md b/vcpkg/scripts/azure-pipelines/owners-db/README.md new file mode 100644 index 0000000..023058e --- /dev/null +++ b/vcpkg/scripts/azure-pipelines/owners-db/README.md @@ -0,0 +1,96 @@ +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 +``` |