doc: shims & PATH

docs/.vitepress/en.ts

@@ -59,6 +59,7 @@ function sidebar(): DefaultTheme.Sidebar {
             items: [
                 {text: 'Core', link: '/usage/core-commands'},
                 {text: 'Plugins', link: '/usage/plugins-commands'},
+                {text: 'Shims & PATH', link: '/usage/shims-path'},
                 {text: 'All Commands', link: '/usage/all-commands'},
             ]
         },

docs/.vitepress/zh.ts

@@ -67,6 +67,7 @@ function sidebar(): DefaultTheme.Sidebar {
             items: [
                 {text: '核心', link: '/zh-hans/usage/core-commands'},
                 {text: '插件', link: '/zh-hans/usage/plugins-commands'},
+                {text: '垫片 & PATH', link: '/zh-hans/usage/shims-path'},
                 {text: '所有命令', link: '/zh-hans/usage/all-commands'},
             ]
         },

docs/guides/configuration.md

@@ -71,7 +71,7 @@ registry:
 - https://rawcdn.githack.com/version-fox/vfox-plugins/plugins
   :::
 
-## Cache Settings <Badge type="tip" text=">= 0.4.3" vertical="middle" />
+## Cache Settings <Badge type="tip" text=">= 0.5.0" vertical="middle" />
 
 `vfox` will cache the results of the `search` command (`available` hook) by default to reduce the number of network requests. The default
 cache time is `12h`.

docs/usage/shims-path.md

@@ -0,0 +1,71 @@
+# Shims & PATH <Badge type="tip" text=">= 0.5.0" vertical="middle" />
+
+`vfox` manage versions by manipulating `PATH` directly, but some IDEs don't read the `PATH` environment variable, so we
+need some extra operations to let the IDE used.
+
+## Shims Directory
+
+This directory is used to store all shims of global SDK.
+
+**Location**: `$HOME/.version-fox/shims`
+
+```shell
+$ vfox use -g nodejs@14.17.0
+$ ~/.version-fox/shims/node -v
+v14.17.0
+```
+
+::: warning
+
+`vfox` only handles all binary files in the installation directory. If you install binary files through other
+installation tools (`npm`), the `shims` directory will not contain them.
+
+Take `nodejs` as an example:
+```shell
+$ vfox use -g nodejs@14.17.0
+$ npm install -g prettier@3.1.0
+$ ~/.version-fox/shims/node -v
+v14.17.0
+$ ~/.version-fox/shims/prettier -v # File not found!!!!
+```
+
+> Do not intend to provide the ability to rebuild `shim`. Please use the `current` soft link.
+
+:::
+
+::: tip Shim Implementation
+
+- **Windows**: `.exe` and `.shim` files
+- **Unix**: Soft link
+
+Take `nodejs` as an example:
+- **Windows**: `node.exe` and `node.shim`
+- **Unix**: `.version-fox/shims/node` -> `.version-fox/cache/nodejs/v-14.17.0/nodejs-14.17.0/bin/node`
+:::
+
+## `current` Soft Link
+
+`vfox` will create a soft link `current` in the `$HOME/.version-fox/cache/<sdk>/` directory, pointing to the corresponding SDK.
+
+**Location**: `$HOME/.version-fox/cache/<sdk>/current`
+
+Take `Nodejs` as an example:
+
+```shell
+$ vfox use -g nodejs@14.17.0
+$ npm install -g prettier@3.1.0
+$ ~/.version-fox/cache/nodejs/current/node -v
+v14.17.0
+$ ~/.version-fox/cache/nodejs/current/prettier -v  # Ok!!!
+3.1.0
+```
+
+::: tip
+
+`vfox`'s core for version management is also implemented through the `current` soft link.
+
+When you switch on Shell, a soft link is actually created to point to the corresponding SDK version, and the `current`
+soft link is stored in the temporary directory of the current `Shell`, as well as configured to `PATH`, to achieve version switching.
+
+:::
+

docs/zh-hans/guides/configuration.md

@@ -69,7 +69,7 @@ registry:
 - https://rawcdn.githack.com/version-fox/vfox-plugins/plugins
   :::
 
-## 缓存 <Badge type="tip" text=">= 0.4.3" vertical="middle" />
+## 缓存 <Badge type="tip" text=">= 0.5.0" vertical="middle" />
 
 `vfox` 默认会缓存`search`命令的结果, 以减少网络请求次数。默认缓存时间为`12h`。
 

docs/zh-hans/usage/shims-path.md

@@ -0,0 +1,73 @@
+# 垫片 & PATH <Badge type="tip" text=">= 0.5.0" vertical="middle" />
+
+`vfox` 是通过直接操作`PATH`来进行版本管理的, 但是有些IDE并不会读取`PATH`环境变量,
+所以我们需要一些额外的操作来让IDE读取到`vfox`的版本。
+
+## Shims 目录
+
+该目录用于存放所有全局SDK垫片文件 。
+
+**位置**: `$HOME/.version-fox/shims`
+
+```shell
+$ vfox use -g nodejs@14.17.0
+$ ~/.version-fox/shims/node -v
+v14.17.0
+```
+
+::: warning 注意
+
+`vfox` 只会处理插件指定目录下的所有二进制文件, 如果你通过其他安装工具(`npm`)安装二进制文件, `shims`目录下是不会包含的。
+
+以`nodejs`为例:
+
+```shell
+$ vfox use -g nodejs@14.17.0
+$ npm install -g prettier@3.1.0
+$ ~/.version-fox/shims/node -v
+v14.17.0
+$ ~/.version-fox/shims/prettier -v # 文件不存在!!!!
+```
+
+> 并不打算提供重建`shim`的能力。 请使用`current`软链。
+
+:::
+
+::: tip 垫片实现
+
+- **Windows**: `.exe` 和 `.shim` 文件
+- **Unix**: 软链接
+
+以`nodejs`为例:
+
+- **Windows**: `node.exe` 和 `node.shim`
+- **Unix**: `.version-fox/shims/node` -> `.version-fox/cache/nodejs/v-14.17.0/nodejs-14.17.0/bin/node`
+  :::
+
+## `current` 软链接
+
+`vfox` 除了会将全局SDK垫片放置在`shims`目录下, 还会在`$HOME/.version-fox/cache/<sdk>/`目录下创建一个软链接`current`,
+指向对应的SDK。
+
+位置: `$HOME/.version-fox/cache/<sdk>/current`
+
+以`Nodejs`为例:
+
+```shell
+$ vfox use -g nodejs@14.17.0
+$ npm install -g prettier@3.1.0
+$ ~/.version-fox/cache/nodejs/current/node -v
+v14.17.0
+$ ~/.version-fox/cache/nodejs/current/prettier -v  # 可以了!!!
+3.1.0
+```
+
+::: tip
+
+`vfox`对于版本管理的核心也是通过`current`软链接来实现的.
+
+当你在命令行中进行切换时, 实际上会创建一个软链接指向对应的SDK版本, 并将`current`软链接存放在当前`Shell`的临时目录下,
+以及配置到`PATH`中, 从而实现版本的切换。
+
+:::
+