Skip to content

Commit

Permalink
fix: plugin path
Browse files Browse the repository at this point in the history
  • Loading branch information
@bytemain
bytemain committed Jan 18, 2025
1 parent f24563b commit 074d941
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 44 deletions.
38 changes: 18 additions & 20 deletions docs/plugins/create/howto.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
## What's in the plugin?

The directory structure is as follows:

```shell
.
├── README.md
Expand All @@ -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.
Expand All @@ -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

Expand All @@ -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`.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -166,7 +165,6 @@ function PLUGIN:EnvKeys(ctx)
end
```


## Optional hook functions

::: warning
Expand Down Expand Up @@ -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',
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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 <sdk-name>@<version>`
- PLUGIN:PostInstall -> `vfox install <sdk-name>@<version>`
- PLUGIN:Available -> `vfox search <sdk-name>`
- PLUGIN:EnvKeys -> `vfox use <sdk-name>@<version>`

In addition, you can use the `--debug` parameter to view more log information, for example:

```shell
Expand All @@ -300,7 +300,6 @@ vfox --debug use <sdk-name>@<version>
...
```


## Example

Here is an example of a plugin that supports the `Node.js`.
Expand All @@ -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:
Expand Down
51 changes: 27 additions & 24 deletions docs/zh-hans/plugins/create/howto.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@

# 创建插件

## 插件里有什么

目录结构如下:

```shell
.
├── README.md
Expand Down Expand Up @@ -36,27 +36,28 @@

`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) | ❌ | 删除之前进行额外操作 |

## 必须实现的钩子函数

### PreInstall

返回预安装信息， 例如具体版本号、下载源等信息。 `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)
--- 用户输入
Expand Down Expand Up @@ -97,6 +98,7 @@ end
返回当前可用版本列表。如没有则返回空数组。

**位置**: `hooks/available.lua`

```lua
function PLUGIN:Available(ctx)
--- 用户输入附带的参数, 数组
Expand Down Expand Up @@ -124,9 +126,10 @@ end

### EnvKeys

告诉`vfox`当前SDK需要配置的环境变量有哪些。
告诉`vfox`当前 SDK 需要配置的环境变量有哪些。

**位置**: `hooks/env_keys.lua`

```lua
function PLUGIN:EnvKeys(ctx)
local mainSdkInfo = ctx.main
Expand Down Expand Up @@ -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 安装目录
Expand All @@ -187,6 +189,7 @@ end
如果 `PreUse` 函数返回了版本信息， `vfox` 将会使用这个新的版本信息。

**位置**: `hooks/pre_use.lua`

```lua
function PLUGIN:PreUse(ctx)
--- 用户输入的版本
Expand All @@ -212,6 +215,7 @@ function PLUGIN:PreUse(ctx)
}
end
```

### ParseLegacyFile <Badge type="tip" text=">= 0.4.0" vertical="middle" />

解析其他配置文件，以确定工具的版本。例如，`nvm` 的 `.nvmrc` 文件、`SDKMAN` 的 `.sdkmanrc` 文件等。
Expand All @@ -221,7 +225,8 @@ end
:::

**位置**: `metadata.lua`
```lua

```lua
--- 当前插件支持解析的遗留文件名列表, 例如: .nvmrc, .node-version, .sdkmanrc
PLUGIN.legacyFilenames = {
'.nvmrc',
Expand All @@ -230,7 +235,8 @@ PLUGIN.legacyFilenames = {
```

**位置**: `hooks/parse_legacy_file.lua`
```lua

```lua
function PLUGIN:ParseLegacyFile(ctx)
--- 文件名
local filename = ctx.filename
Expand All @@ -251,7 +257,8 @@ end
在卸载 SDK 之前执行的钩子函数。如果插件需要在卸载之前执行一些操作，可以实现这个钩子函数。例如清理缓存、删除配置文件等。

**位置**: `hooks/pre_uninstall.lua`
```lua

```lua
function PLUGIN:PreUninstall(ctx)
local mainSdkInfo = ctx.main
local mainPath = mainSdkInfo.path
Expand All @@ -267,7 +274,7 @@ end

## 测试插件

目前，`vfox` 插件测试方法很简陋。您需要将插件放在 `${HOME}/.version-fox/plugins` 目录中，并使用不同的命令验证您的功能是否正常工作。
目前，`vfox` 插件测试方法很简单。您需要将插件放在 `${HOME}/.version-fox/plugin` 目录中，并使用不同的命令验证您的功能是否正常工作。
您可以在插件中使用 `print`/`printTable` 函数来打印日志进行调试。

- PLUGIN:PreInstall -> `vfox install <sdk-name>@<version>`
Expand All @@ -284,22 +291,18 @@ vfox --debug use <sdk-name>@<version>
...
```



## 插件示例

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`。
Expand Down

0 comments on commit 074d941

Please sign in to comment.