vcpkg: reduce el tamaño de la caché binaria sin confundir el ABI
Guía práctica para usar la compresión ZIP de vcpkg en una caché aislada, entender la precedencia de configuración y medir tamaño y tiempo sin cambiar el ABI del paquete.
3 de noviembre de 2026 · Leopoldo Benavente Cadena · 6 min de lectura
Una caché binaria de vcpkg evita reconstruir dependencias de C++ cuando el paquete y la configuración coinciden. En CI, el coste no es solo compilar: también cuenta empaquetar los archivos, subir los ZIP y restaurarlos en el siguiente runner. La opción de compresión fue introducida por la herramienta 2026-09-26; la release vigente al corte es 2026-10-29 y contiene correcciones posteriores, no una nueva semántica documentada para ese ajuste. Por eso no convierte un nivel de compresión en una mejora universal.
Antes de cambiar una pipeline conviene separar dos cosas. El registry contiene ports y metadatos de recetas; la caché binaria contiene resultados construidos para un triplet, compilador, flags y scripts concretos. El registry 2026.10.16 y la herramienta vigente 2026-10-29 son releases distintos; la compresión fue introducida en la herramienta 2026-09-26. Actualizar uno no implica cambiar el otro ni obliga a regenerar toda la caché.
Qué cambia y qué no
La documentación oficial ofrece --binary-cache-compression-level=<0-9> y la variable VCPKG_BINARY_CACHE_COMPRESSION_LEVEL. El nivel 0 guarda sin compresión, 1 solicita la compresión más rápida y 9 la máxima. La opción de línea de comandos tiene precedencia sobre la variable; si no se proporciona ninguna, se conserva el valor predeterminado de la herramienta.
| Configuración | Resultado esperado | Alcance |
|---|---|---|
| Ninguna opción ni variable | Usa el nivel predeterminado del empaquetador | ZIP de la caché binaria |
VCPKG_BINARY_CACHE_COMPRESSION_LEVEL=1 |
Pide compresión rápida | ZIP de la caché binaria |
--binary-cache-compression-level=1 |
Pide nivel 1 y gana a la variable | ZIP de la caché binaria |
| Nivel inválido o vacío | La inicialización de la caché se rechaza | Corregir la configuración antes de medir |
| Backend NuGet | El cambio descrito no afecta su empaquetado | Revisar su propia configuración |
Microsoft documenta también que el ajuste no cambia los package ABIs y no impide restaurar archivos existentes. Eso no significa que cualquier artefacto sirva para cualquier compilador, triplet o manifest: la caché sigue siendo sensible a la configuración de la build. Tampoco significa que las actualizaciones de ports del registry sean ABI compatibles entre sí.
Cómo aislar la prueba
Haz la comparación con una copia de un manifest pequeño o de un repositorio de laboratorio. No apuntes a la caché compartida del runner. En PowerShell, crea dos carpetas nuevas bajo el directorio temporal del usuario:
$lab = Join-Path $env:TEMP ("vcpkg-cache-lab-" + [guid]::NewGuid())
$cacheFast = Join-Path $lab "cache-level-1"
$cacheDefault = Join-Path $lab "cache-default"
New-Item -ItemType Directory -Force $cacheFast, $cacheDefault | Out-NullEntra en una copia del proyecto que ya tiene un vcpkg.json y un triplet fijado. El comando siguiente configura solo este proceso y esta carpeta de laboratorio:
$env:VCPKG_BINARY_SOURCES = "clear;files,$cacheFast,readwrite"
$env:VCPKG_BINARY_CACHE_COMPRESSION_LEVEL = "1"
vcpkg version
Measure-Command { vcpkg install }
Get-ChildItem $cacheFast -Recurse -File -Filter *.zip |
Measure-Object -Property Length -SumEl manifest, baseline, triplet y compilador deben ser idénticos en la comparación. Para la segunda ejecución usa una carpeta nueva y deja sin definir la variable de compresión o establece explícitamente la política que quieras contrastar:
$env:VCPKG_BINARY_SOURCES = "clear;files,$cacheDefault,readwrite"
Remove-Item Env:VCPKG_BINARY_CACHE_COMPRESSION_LEVEL -ErrorAction SilentlyContinue
Measure-Command { vcpkg install }
Get-ChildItem $cacheDefault -Recurse -File -Filter *.zip |
Measure-Object -Property Length -SumEl ejemplo usa Remove-Item únicamente sobre la variable de entorno del proceso, no sobre archivos. Las carpetas de caché son temporales y exclusivas de la prueba; conserva sus datos o elimínalas manualmente cuando ya no necesites la evidencia. No reutilices una caché global para “calentar” una de las mediciones: contaminaría la comparación.
Registra el tiempo que devuelve Measure-Command, la suma de bytes y el número de ZIP de cada carpeta. Después repite una instalación que pueda restaurar desde cada caché, siempre en una copia equivalente del proyecto. No conviertas los números de tu máquina en un benchmark universal: el tamaño y el tiempo dependen de los artefactos, disco, red, CPU, compresión y provider.
Precedencia y fuentes de caché
La variable VCPKG_BINARY_SOURCES y la opción --binarysource=<source> controlan dónde busca y dónde escribe vcpkg. La documentación evalúa primero el entorno y después la línea de comandos; clear puede eliminar las fuentes anteriores de esa ejecución. Para una prueba local, el provider files es suficiente:
$env:VCPKG_BINARY_SOURCES = "clear;files,$cacheFast,readwrite"
vcpkg install --binary-cache-compression-level=1Si el runner ya exporta una fuente remota, la configuración de laboratorio debe hacerla explícita y separada. No pegues credenciales en el manifest ni en el artículo. El mensaje raíz de un fallo de subida suele ser más útil que culpar al port: conserva el diagnóstico estandarizado de la herramienta, confirma el provider y comprueba si el error pertenece a la red, permisos, autenticación o al artefacto.
La opción de compresión se puede contrastar con la variable para comprobar su precedencia:
$env:VCPKG_BINARY_CACHE_COMPRESSION_LEVEL = "9"
vcpkg install --binary-cache-compression-level=1Esta ejecución debe quedar en una caché de laboratorio. La expectativa documentada es que la CLI use 1; no deduzcas ese resultado mirando solo la variable, y no mezcles el experimento con una restauración que ya tenga artefactos creados por otra configuración.
Una política sencilla para CI
Si el cuello de botella dominante es subir ZIP y la CPU está disponible, prueba un nivel bajo como 1 en una fuente separada. Si el tiempo de empaquetado o compilación es el problema, conserva el valor predeterminado hasta medir. El nivel 9 puede reducir bytes en algunos artefactos, pero puede aumentar el tiempo de compresión; no hay una proporción fija que se pueda prometer antes de observar tus paquetes.
Fija en la evidencia el commit o baseline del registry, versión de vcpkg-tool, triplet, compilador, flags, modo de enlace, provider de caché y configuración de compresión. Si cambia cualquiera de ellos, trata la medición como otra comparación. La restauración exitosa confirma que ese artefacto sirve en ese contexto; no prueba por sí sola reproducibilidad, seguridad del almacenamiento ni compatibilidad con otra toolchain.
El release de registry 2026.10.16 también informa de 2.877 ports, 41 nuevos y 806 actualizados respecto al release de julio. Es contexto del catálogo, no una razón para reconstruir dependencias sin revisar el manifest. El beneficio de la compresión puede evaluarse sin convertir la actualización del registry en una migración obligatoria.
La decisión final debe ser pequeña y reversible: separa la fuente de caché, mide con entradas equivalentes, revisa los logs y promueve el nivel solo si tus datos justifican el cambio. Así el ajuste de ZIP reduce un coste concreto sin confundirlo con un cambio de ABI, de port o de provider.
Comentarios