Skip to content

Commit

Permalink
[Doc] Update binarycaching.md with clearer description (#18033)
Browse files Browse the repository at this point in the history
* Update binarycaching.md with clearer description

We received user feedback about the binary caching feature not being clear. I rewrote some of the opening section to try to describe it better. Feedback is appreciated.

* Apply suggestions from code review

Co-authored-by: ras0219 <533828+ras0219@users.noreply.github.com>

Co-authored-by: ras0219 <533828+ras0219@users.noreply.github.com>
  • Loading branch information
AugP and ras0219 authored May 26, 2021
1 parent df34b02 commit ce6253b
Showing 1 changed file with 10 additions and 2 deletions.
12 changes: 10 additions & 2 deletions docs/users/binarycaching.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,17 @@

**The latest version of this documentation is available on [GitHub](https://github.com/Microsoft/vcpkg/tree/master/docs/users/binarycaching.md).**

Binary caching is vcpkg's method for reusing package builds between projects and between machines. Think of it as a "package restore accelerator" that gives you the same results as though you built from source. Each build is packaged independently, so changing one library only requires rebuilding consuming libraries.
Libraries installed with vcpkg can always be built from source. However, that can duplicate work and waste time when working across multiple projects.

If your CI provider offers a native "caching" function, we recommend using both methods for the most performant results.
Binary caching is a vcpkg feature that saves copies of library binaries in a shared location that can be accessed by vcpkg for future installs. This means that, as a user, you should only need to build dependencies from source once. If vcpkg is asked to install the same library with the same build configuration in the future, it will just copy the built binaries from the cache and finish the operation in seconds.

Binary caching is especially effective when using Continuous Integration, since local developers can reuse the binaries produced during a CI run. It also greatly enhances the performance of "ephemeral" or "hosted" build agents, since all local changes are otherwise lost between runs. By using binary caching backed by a cloud service, such as GitHub, Azure, or many others, you can ensure your CI runs at maximum speed and only rebuilds your dependencies when they've changed.

Caches can be hosted in a variety of environments. The most basic examples are a folder on the local machine or a network file share. Caches can also be stored in any NuGet feed (such as GitHub or Azure DevOps Artifacts), Azure Blob Storage*, or Google Cloud Storage*.

\* (experimental)

If your CI provider offers a native "caching" function, we recommend using both vcpkg binary caching and the native method for the most performant results.

In-tool help is available via `vcpkg help binarycaching`.

Expand Down

0 comments on commit ce6253b

Please sign in to comment.