# vcpkg: Troubleshooting & Dependency Lifecycle

Reference for the `vcpkg` skill. Use this when a user encounters vcpkg build failures, package-not-found errors, needs to read build logs, or manages the dependency lifecycle (removing, changing features, replacing libraries, cleaning the cache).

## Reading vcpkg Build Logs

Build logs are stored at:
```
<vcpkg-root>/buildtrees/<port-name>/
```

Key log files:
- `config-<triplet>-out.log` — CMake configure output
- `build-<triplet>-<dbg|rel>-<out|err>.log` — common build logs
- `install-<triplet>-<dbg|rel>-<out|err>.log` — common install logs

Exact names vary by port and build helper; use the path vcpkg prints for the failing command.

When a build fails, vcpkg prints the path to the relevant log. Start with the `-err.log` file for the failing step.

---

## Resolving package-not-found After Install

If CMake says `Could not find a package configuration file provided by "X"`:

1. **Check toolchain file** — ensure `-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake` is set
2. **Check triplet match** — the installed triplet must match your build architecture
3. **Check package name** — vcpkg port names may differ from CMake package names (e.g., port `nlohmann-json` → `find_package(nlohmann_json)`)
4. **Check installed list** — run `vcpkg list` to confirm the package is actually installed
5. **Clear CMake cache** — delete `CMakeCache.txt` and reconfigure

---

## Dependency Lifecycle

### Removing a Library

1. Remove it from `vcpkg.json` → `"dependencies"` array
2. Run `vcpkg install` to reconcile (manifest mode auto-removes unused packages)

In classic mode:
```console
vcpkg remove boost-regex
vcpkg remove boost-regex --recurse  # also removes dependents
```

### Changing Features on an Installed Library

Update the features in `vcpkg.json`:
```json
{
  "dependencies": [
    {
      "name": "curl",
      "features": ["ssl", "ssh"]
    }
  ]
}
```

Then run `vcpkg install` — vcpkg will detect the feature change and rebuild.

In classic mode:
```console
vcpkg install curl[ssl,ssh] --recurse   # permits rebuilding with the new feature set
```

### Replacing One Library with Another

1. Remove the old library from `vcpkg.json`
2. Add the new library to `vcpkg.json`
3. Run `vcpkg install` to reconcile
4. Update your source code: change `#include` directives, `find_package()` calls, and `target_link_libraries()` in CMakeLists.txt

### Cleaning the vcpkg Cache

```powershell
# Remove all package build artifacts
vcpkg x-clean

# Optional: remove local cache/install directories
Remove-Item -Recurse -Force <vcpkg-root>\buildtrees,<vcpkg-root>\downloads,<vcpkg-root>\installed,.\vcpkg_installed
```

```bash
# Remove all package build artifacts
vcpkg x-clean

# Optional: remove local cache/install directories
rm -rf <vcpkg-root>/buildtrees <vcpkg-root>/downloads <vcpkg-root>/installed ./vcpkg_installed
```