From cce9bb28dc6aafd7d2e643877911905fd20047f3 Mon Sep 17 00:00:00 2001
From: h7x4 <h7x4@nani.wtf>
Date: Mon, 15 Jul 2024 10:50:58 +0200
Subject: [PATCH] doc/packages/vcpkg: init

---
 doc/packages/index.md         |  1 +
 doc/packages/vcpkg.section.md | 24 ++++++++++++++++++++++++
 2 files changed, 25 insertions(+)
 create mode 100644 doc/packages/vcpkg.section.md

diff --git a/doc/packages/index.md b/doc/packages/index.md
index 38dba5b3498f..69dd8c3b3bff 100644
--- a/doc/packages/index.md
+++ b/doc/packages/index.md
@@ -24,6 +24,7 @@ shell-helpers.section.md
 steam.section.md
 cataclysm-dda.section.md
 urxvt.section.md
+vcpkg.section.md
 weechat.section.md
 xorg.section.md
 ```
diff --git a/doc/packages/vcpkg.section.md b/doc/packages/vcpkg.section.md
new file mode 100644
index 000000000000..b0fa5fd22fd4
--- /dev/null
+++ b/doc/packages/vcpkg.section.md
@@ -0,0 +1,24 @@
+# VCPKG {#sec-vcpkg}
+
+The `vcpkg-tool` package  has a wrapper around the `vcpkg` executable to avoid writing to the nix store.
+The wrapper will also be present in `vcpkg`, unless you specify `vcpkg.override { vcpkg-tool = vcpkg-tool-unwrapped; }`
+
+The wrapper has been made in a way so that it will provide default cli arguments, but tries not to interfere if the user provides the same arguments.
+The arguments also have corresponding environment variables that can be used as an alternative way of overriding these paths.
+
+Run the wrapper with the environment variable `NIX_VCPKG_DEBUG_PRINT_ENVVARS=true` to get a full list of corresponding environment variables.
+
+## Nix specific environment variables {#sec-vcpkg-nix-envvars}
+
+The wrapper also provides some new nix-specific environment variables that lets you control some of the wrapper functionality.
+
+- `NIX_VCPKG_WRITABLE_PATH = <path>`
+
+   Set this environment variable to specify the path where `vcpkg` will store buildtime artifacts.
+   This will become the base path for all of the other paths.
+
+- `NIX_VCPKG_DEBUG_PRINT_ENVVARS = true | false`
+
+   Set this to `true` for the wrapper to print the corresponding environment variables for the arguments that will be provided to the unwrapped executable.
+   The list of variables will be printed right before invoking `vcpkg`.
+   This can be useful if you suspect that the wrapper for some reason was unable to prioritize user-provided cli args over its default ones, or for fixing other issues like typos or unexpanded environment variables.