[Doc] Update binarycaching.md with clearer description

[AugP]

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.

Describe the pull request

• What does your PR fix?

  Small documentation fix.

• Does your PR follow the maintainer guide?

  Yes

[Osyotr]

There are few things unclear left:

1. In what cases library will be rebuilt from source? Compiler update, port update, etc.
2. Is there any way to clean "dead" cache? Or better, don't rebuld (and cache) libraries when compiler update doesn't break abi compatibility?

[AugP]

There are few things unclear left:

1. In what cases library will be rebuilt from source? Compiler update, port update, etc.
2. Is there any way to clean "dead" cache? Or better, don't rebuld (and cache) libraries when compiler update doesn't break abi compatibility?

I agree, thank you for the feedback! I'll work with Robert to address these questions in the PR.

[ras0219-msft]

In what cases library will be rebuilt from source? Compiler update, port update, etc.

There is the implementation notes section, however the ABI is explicitly non-normative -- we fully intend to add additional fields and content to it in the future.

https://github.com/microsoft/vcpkg/blob/f1d44a97469401417687bd9dfe92fecc26ecf849/docs/users/binarycaching.md#implementation-notes-internal-details-subject-to-change-without-notice

Is there any way to clean "dead" cache?

Unfortunately there's no way for vcpkg to determine what's truly "dead"; you could have a 3 month old instance of vcpkg on your disk that you've moved from its original location, so there's no way we could track it.

As for the actual operation of cleaning, it's backend specific. For files, they can just be deleted. For NuGet / Cloud providers, it's up to those specific providers on how they offer "cleaning" services.

Or better, don't rebuld (and cache) libraries when compiler update doesn't break abi compatibility?

Unfortunately, abi compatibility is extremely specific to the compilers and can even vary based on flags. For example, LTO/LTCG usually changes the abi compatibility computation. Because of this, we take a conservative approach to ensure correctness.