diff --git a/docs/plugins/create/howto.md b/docs/plugins/create/howto.md index 31f6354c..94904db5 100644 --- a/docs/plugins/create/howto.md +++ b/docs/plugins/create/howto.md @@ -3,6 +3,7 @@ ## What's in the plugin? The directory structure is as follows: + ```shell . ├── README.md @@ -26,7 +27,7 @@ The directory structure is as follows: - `metadata.lua` Plugin metadata information. Used to describe the basic information of the plugin, such as the plugin name, version, etc. - `README.md` Plugin documentation. - `LICENSE` Plugin license. -- +- ::: warning Plugin template To facilitate the development of plugins, we provide a plugin template that you can use directly [vfox-plugin-template](https://github.com/version-fox/vfox-plugin-template) to develop a plugin. @@ -37,14 +38,14 @@ To facilitate the development of plugins, we provide a plugin template that you The full list of hooks callable from vfox. | Hook | **Required** | Description | -|:------------------------------------------------|:-------------|:--------------------------------------------------------------------------------| -| [hooks/available.lua](#available) | ✅ | List all available versions | -| [hooks/pre_install.lua](#preinstall) | ✅ | Parse version and return pre-installation information | -| [hooks/env_keys.lua](#envkeys) | ✅ | Configure environment variables | -| [hooks/post_install.lua](#postinstall) | ❌ | Execute additional operations after install, such as compiling source code, etc | -| [hooks/pre_use.lua](#preuse) | ❌ | An opportunity to change the version before using it | -| [hooks/parse_legacy_file.lua](#parselegacyfile) | ❌ | Custom parser for legacy version files | -| [hooks/pre_uninstall.lua](#preuninstall) | ❌ | Perform some operations before uninstalling targeted version | +| :---------------------------------------------- | :----------- | :------------------------------------------------------------------------------ | +| [hooks/available.lua](#available) | ✅ | List all available versions | +| [hooks/pre_install.lua](#preinstall) | ✅ | Parse version and return pre-installation information | +| [hooks/env_keys.lua](#envkeys) | ✅ | Configure environment variables | +| [hooks/post_install.lua](#postinstall) | ❌ | Execute additional operations after install, such as compiling source code, etc | +| [hooks/pre_use.lua](#preuse) | ❌ | An opportunity to change the version before using it | +| [hooks/parse_legacy_file.lua](#parselegacyfile) | ❌ | Custom parser for legacy version files | +| [hooks/pre_uninstall.lua](#preuninstall) | ❌ | Perform some operations before uninstalling targeted version | ## Required hook functions @@ -57,7 +58,6 @@ directory in advance. If it is a compressed package such as `tar`, `tar.gz`, `tar.xz`, `zip`, `vfox` will help you to decompress it directly. - By default, `vfox` reads the file name from the URL. If the last item in the URL is not a valid file name, you should specify the file name by appending a fragment at the end, so that `vfox` can identify the file format and decompress it. For example: `https://example.com/1234567890#/filename.zip`. @@ -102,7 +102,6 @@ function PLUGIN:PreInstall(ctx) end ``` - ### Available This hook function is called when the `vfox search` command is executed. It is used to return the current available @@ -166,7 +165,6 @@ function PLUGIN:EnvKeys(ctx) end ``` - ## Optional hook functions ::: warning @@ -231,13 +229,13 @@ end This hook is used to parse other configuration files to determine the version of the tool. For example, the `.nvmrc` file of `nvm`, the `.sdkmanrc` file of `SDKMAN`, etc. - ::: danger This hook must be used with the `legacyFilenames` configuration item to tell `vfox` which files your plugin can parse. ::: **location**: `metadata.lua` -```lua + +```lua --- The list of legacy file names that the current plugin supports parsing, such as: .nvmrc, .node-version, .sdkmanrc PLUGIN.legacyFilenames = { '.nvmrc', @@ -246,7 +244,8 @@ PLUGIN.legacyFilenames = { ``` **location**: `hooks/parse_legacy_file.lua` -```lua + +```lua function PLUGIN:ParseLegacyFile(ctx) local filename = ctx.filename local filepath = ctx.filepath @@ -266,7 +265,8 @@ This is called before the SDK is uninstalled. If the plugin needs to perform som uninstalling, it can implement this hook function. For example, cleaning up the cache, deleting configuration files, etc. **Location**: `hooks/pre_uninstall.lua` -```lua + +```lua function PLUGIN:PreUninstall(ctx) local mainSdkInfo = ctx.main local mainPath = mainSdkInfo.path @@ -283,14 +283,14 @@ end ## Test Plugin Currently, VersionFox plugin testing is straightforward. You only need to place the plugin file in the -`${HOME}/.version-fox/plugins` directory and verify that your features are working using different commands. You can use +`${HOME}/.version-fox/plugin` directory and verify that your features are working using different commands. You can use `print`/`printTable` statements in Lua scripts for printing log. - PLUGIN:PreInstall -> `vfox install @` - PLUGIN:PostInstall -> `vfox install @` - PLUGIN:Available -> `vfox search ` - PLUGIN:EnvKeys -> `vfox use @` - + In addition, you can use the `--debug` parameter to view more log information, for example: ```shell @@ -300,7 +300,6 @@ vfox --debug use @ ... ``` - ## Example Here is an example of a plugin that supports the `Node.js`. @@ -309,7 +308,6 @@ https://github.com/version-fox/vfox-nodejs You can refer to this plugin to develop your own plugin. - ## Publish to the public registry `vfox` allows custom installation of plugins, such as: diff --git a/docs/zh-hans/plugins/create/howto.md b/docs/zh-hans/plugins/create/howto.md index 290d350f..83e408b7 100644 --- a/docs/zh-hans/plugins/create/howto.md +++ b/docs/zh-hans/plugins/create/howto.md @@ -1,9 +1,9 @@ - # 创建插件 ## 插件里有什么 目录结构如下: + ```shell . ├── README.md @@ -36,15 +36,15 @@ `vfox`支持的所有钩子函数列表。 -| 钩子 | **必须** | 描述 | -|:------------------------------------------------|:-------|:---------------------| -| [hooks/available.lua](#available) | ✅ | 列举所有可用版本 | -| [hooks/pre_install.lua](#preinstall) | ✅ | 解析版本号并返回预安装信息,如下载地址等 | -| [hooks/env_keys.lua](#envkeys) | ✅ | 配置环境变量 | -| [hooks/post_install.lua](#postinstall) | ❌ | 执行额外的操作, 如编译源码等 | -| [hooks/pre_use.lua](#preuse) | ❌ | 在切换版本之前, 提供修改版本的机会 | -| [hooks/parse_legacy_file.lua](#parselegacyfile) | ❌ | 自定义解析遗留文件 | -| [hooks/pre_uninstall.lua](#preuninstall) | ❌ | 删除之前进行额外操作 | +| 钩子 | **必须** | 描述 | +| :---------------------------------------------- | :------- | :-------------------------------------- | +| [hooks/available.lua](#available) | ✅ | 列举所有可用版本 | +| [hooks/pre_install.lua](#preinstall) | ✅ | 解析版本号并返回预安装信息,如下载地址等 | +| [hooks/env_keys.lua](#envkeys) | ✅ | 配置环境变量 | +| [hooks/post_install.lua](#postinstall) | ❌ | 执行额外的操作, 如编译源码等 | +| [hooks/pre_use.lua](#preuse) | ❌ | 在切换版本之前, 提供修改版本的机会 | +| [hooks/parse_legacy_file.lua](#parselegacyfile) | ❌ | 自定义解析遗留文件 | +| [hooks/pre_uninstall.lua](#preuninstall) | ❌ | 删除之前进行额外操作 | ## 必须实现的钩子函数 @@ -52,11 +52,12 @@ 返回预安装信息， 例如具体版本号、下载源等信息。 `vfox`会帮你提前将这些文件下载到特定目录下。如果是压缩包如`tar`、`tar.gz`、`tar.xz`、`zip`这四种压缩包， `vfox`会直接帮你解压处理。 -`vfox`默认从下载链接中获取文件名，如果下载链接最后一项不是有效的文件名，可以通过在链接末尾附加Fragment来指定文件名，以便于`vfox`识别文件格式并解压。 如：`https://example.com/1234567890#/filename.zip` +`vfox`默认从下载链接中获取文件名，如果下载链接最后一项不是有效的文件名，可以通过在链接末尾附加 Fragment 来指定文件名，以便于`vfox`识别文件格式并解压。 如：`https://example.com/1234567890#/filename.zip` 如果版本的返回值为空，表示未找到版本，`vfox`会询问用户是否进行搜索操作。 **位置**: `hooks/pre_install.lua` + ```lua function PLUGIN:PreInstall(ctx) --- 用户输入 @@ -97,6 +98,7 @@ end 返回当前可用版本列表。如没有则返回空数组。 **位置**: `hooks/available.lua` + ```lua function PLUGIN:Available(ctx) --- 用户输入附带的参数, 数组 @@ -124,9 +126,10 @@ end ### EnvKeys -告诉`vfox`当前SDK需要配置的环境变量有哪些。 +告诉`vfox`当前 SDK 需要配置的环境变量有哪些。 **位置**: `hooks/env_keys.lua` + ```lua function PLUGIN:EnvKeys(ctx) local mainSdkInfo = ctx.main @@ -155,19 +158,18 @@ function PLUGIN:EnvKeys(ctx) end ``` - - ## 可选钩子函数 ::: warning 如果不需要这些钩子函数，请**删除对应的`.lua`文件**! -::: +::: ### PostInstall 拓展点，在`PreInstall`执行之后调用，用于执行额外的操作， 如编译源码等。根据需要实现。 **位置**: `hooks/post_install.lua` + ```lua function PLUGIN:PostInstall(ctx) --- ctx.rootPath SDK 安装目录 @@ -187,6 +189,7 @@ end 如果 `PreUse` 函数返回了版本信息， `vfox` 将会使用这个新的版本信息。 **位置**: `hooks/pre_use.lua` + ```lua function PLUGIN:PreUse(ctx) --- 用户输入的版本 @@ -212,6 +215,7 @@ function PLUGIN:PreUse(ctx) } end ``` + ### ParseLegacyFile 解析其他配置文件，以确定工具的版本。例如，`nvm` 的 `.nvmrc` 文件、`SDKMAN` 的 `.sdkmanrc` 文件等。 @@ -221,7 +225,8 @@ end ::: **位置**: `metadata.lua` -```lua + +```lua --- 当前插件支持解析的遗留文件名列表, 例如: .nvmrc, .node-version, .sdkmanrc PLUGIN.legacyFilenames = { '.nvmrc', @@ -230,7 +235,8 @@ PLUGIN.legacyFilenames = { ``` **位置**: `hooks/parse_legacy_file.lua` -```lua + +```lua function PLUGIN:ParseLegacyFile(ctx) --- 文件名 local filename = ctx.filename @@ -251,7 +257,8 @@ end 在卸载 SDK 之前执行的钩子函数。如果插件需要在卸载之前执行一些操作，可以实现这个钩子函数。例如清理缓存、删除配置文件等。 **位置**: `hooks/pre_uninstall.lua` -```lua + +```lua function PLUGIN:PreUninstall(ctx) local mainSdkInfo = ctx.main local mainPath = mainSdkInfo.path @@ -267,7 +274,7 @@ end ## 测试插件 -目前，`vfox` 插件测试方法很简陋。您需要将插件放在 `${HOME}/.version-fox/plugins` 目录中，并使用不同的命令验证您的功能是否正常工作。 +目前，`vfox` 插件测试方法很简单。您需要将插件放在 `${HOME}/.version-fox/plugin` 目录中，并使用不同的命令验证您的功能是否正常工作。 您可以在插件中使用 `print`/`printTable` 函数来打印日志进行调试。 - PLUGIN:PreInstall -> `vfox install @` @@ -284,22 +291,18 @@ vfox --debug use @ ... ``` - - ## 插件示例 https://github.com/version-fox/vfox-nodejs 你可以参考这个插件来开发自己的插件。 - - ## 向官方插件存储库提交插件 `vfox`可以允许自定义安装插件，比如: ```shell -vfox add --source https://github.com/version-fox/vfox-nodejs/releases/download/v0.0.5/vfox-nodejs_0.0.5.zip +vfox add --source https://github.com/version-fox/vfox-nodejs/releases/download/v0.0.5/vfox-nodejs_0.0.5.zip ``` 为了使你的用户更轻松，你可以将插件添加到官方插件存储库中，以列出你的插件并使用较短的命令轻松安装，比如 `vfox add nodejs`。