Skip to content

Commit

Permalink
docs: add more tutorials
Browse files Browse the repository at this point in the history
  • Loading branch information
futrime committed Dec 4, 2023
1 parent 4ae5d14 commit 789e870
Show file tree
Hide file tree
Showing 5 changed files with 260 additions and 0 deletions.
51 changes: 51 additions & 0 deletions docs/tutorials/publish_your_first_pack.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Publishing Your First Pack

First, you should ensure that you have installed [lip](https://github.com/lippkg/lip).

## Creating a Repository

Next, you need to create a GitHub repository to store your pack. You can use any name you like, such as `my-pack`.

In the repository, it is recommended to include a `README.md` file to describe the pack, and a `logo.png` file to serve as the package's icon.

### Creating a tooth.json

Create a `tooth.json` file in the export directory of the pack with the following content:

```json
{
"format_version": 2,
"tooth": "github.com/my-github-username/my-pack",
"version": "0.1.0",
"info": {
"name": "MyPack",
"description": "A great pack!",
"author": "My Name",
"tags": [
"pack"
]
},
"dependencies": {
"github.com/tooth-hub/levilamina": "1.0.x",
"github.com/tooth-hub/another-pack": "2.0.x"
}
}
```

Replace the value of the `tooth` field with the GitHub repository address, replace the value of the `version` field with the version number, and fill in the values of the fields in `info`.

In the `dependencies` section, specify LeviLamina and any other packages to be integrated.

For more information about `tooth.json`, please refer to <https://docs.lippkg.com/tooth_json_file_reference.html>.

### Trying to Pack and Install the Pack

Run `lip tooth pack pack.tth`, which will generate a packaged pack file `pack.tth` in the current directory. You can move this pack to a suitable location and try to install it using `lip install pack.tth`.

### Publishing the Pack

Commit the changes to the GitHub repository, then click on `Releases` in the repository on GitHub, click on `Create a new release`, fill in the `Tag version` and `Release title`, and then click `Publish release` to publish the pack. Note that the corresponding tag must be in a format similar to `v0.1.0`, which means adding a `v` prefix to the value of the `version` field in `tooth.json`.

Afterwards, you can install your pack using `lip install github.com/my-github-username/pack-name`. Due to synchronization delays in the version listing, this command may throw an error in the initial period after the release. In such cases, you can specify the version number to install the pack, for example, `lip install github.com/my-github-username/pack-name@0.1.0`.

After some time, you will be able to see your pack in LipUI and on <www.lippkg.com>.
51 changes: 51 additions & 0 deletions docs/tutorials/publish_your_first_pack.zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# 发布你的第一个整合包

首先,你应当确保你安装了[lip](https://github.com/lippkg/lip)

## 创建一个仓库

然后,你需要创建一个GitHub仓库,用于存放你的整合包。你可以使用任何你喜欢的名称,例如`my-pack`

在仓库中,我们建议放一个`README.md`文件,用于描述整合包;并放一个`logo.png`文件,用于作为整合包的图标。

### 创建一个tooth.json

在整合包导出目录中创建一个`tooth.json`文件,内容如下:

```json
{
"format_version": 2,
"tooth": "github.com/my-github-username/my-pack",
"version": "0.1.0",
"info": {
"name": "MyPack",
"description": "A great pack!",
"author": "My Name",
"tags": [
"pack"
]
},
"dependencies": {
"github.com/tooth-hub/levilamina": "1.0.x",
"github.com/tooth-hub/another-pack": "2.0.x"
}
}
```

替换`tooth`字段的值为GitHub仓库地址,替换`version`字段的值为版本号,填写`info`中各个字段的值。

`dependencies`中填写LeviLamina和要整合的一切包。

更多关于`tooth.json`的信息,请参考<https://docs.lippkg.com/tooth_json_file_reference.html>

### 尝试打包和安装整合包

运行`lip tooth pack pack.tth`,将会在当前目录下生成一个`pack.tth`文件,这是一个打包好的整合包。你可以移动这个整合包到合适的地方,并使用`lip install pack.tth`尝试安装这个整合包。

### 发布整合包

将更改提交到GitHub仓库,然后在GitHub仓库中点击`Releases`,点击`Create a new release`,填写`Tag version``Release title`,然后点击`Publish release`,即可发布整合包。注意对应的tag必须为类似`v0.1.0`的格式,也就是`tooth.json``version`字段的值加上一个`v`

然后你就可以通过`lip install github.com/my-github-username/pack-name`来安装你的整合包了。由于版本列表同步延迟,这个命令可能会在刚发布的一段时间内报错,你可以指定版本号来安装整合包,例如`lip install github.com/my-github-username/pack-name@0.1.0`

在一段时间后,你也可以在LipUI和<www.lippkg.com>查看到你的整合包了。
78 changes: 78 additions & 0 deletions docs/tutorials/publish_your_first_plugin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Publish Your First Plugin

In the tutorial [Create Your First Plugin](create_your_first_plugin.md), we created a simple plugin. In this tutorial, we will learn how to publish a plugin.

### Prerequisites

First, make sure you have installed [lip](https://github.com/lippkg/lip).

You should also have followed the steps in [Create Your First Plugin](create_your_first_plugin.md) to create a plugin, where the exported plugin directory has a structure similar to the following:

```
.
└── plugin-name
├── manifest.json
├── plugin-name.dll
└── plugin-name.pdb
```

Here, `plugin-name` is the name of the plugin.

### Create a GitHub Repository

First, you need to create a GitHub repository to store your plugin. You can use any name you like, such as `plugin-name`.

In the repository, we recommend including a `README.md` file to describe the plugin and a `logo.png` file to serve as the plugin's icon.

### Create a tooth.json

Create a `tooth.json` file in the exported plugin directory with the following content:

```json
{
"format_version": 2,
"tooth": "github.com/my-github-username/plugin-name",
"version": "0.1.0",
"info": {
"name": "MyPlugin",
"description": "MyPlugin is a great plugin!",
"author": "My Name",
"tags": [
"plugin"
]
},
"dependencies": {
"github.com/tooth-hub/another-plugin": "2.0.x"
},
"prerequisites": {
"github.com/tooth-hub/levilamina": "1.0.x"
},
"files": {
"place": [
{
"src": "plugin-name/*",
"dest": "plugins/plugin-name"
}
]
}
}
```

Replace the value of the `tooth` field with the GitHub repository address of your plugin, replace the value of the `version` field with the version number of your plugin, fill in the values of the fields in the `info` section, and fill in the values of the fields in the `dependencies` and `prerequisites` sections.

!!! note
The `dependencies` section automatically installs the required plugins when installing the plugin and uninstalls them when uninstalling the plugin. However, the `prerequisites` section does not automatically install the required plugins; instead, it throws an error if the dependencies are missing. Generally, the plugins listed in the `prerequisites` section should be fundamental and framework-level packages, such as `github.com/tooth-hub/levilamina`, to avoid accidentally uninstalling them during the plugin uninstallation process.

For more information about `tooth.json`, please refer to <https://docs.lippkg.com/tooth_json_file_reference.html>.

### Try Packing and Installing the Plugin

In the exported plugin directory, run `lip tooth pack plugin.tth`. This will generate a `plugin.tth` file in the current directory, which is a packaged plugin. You can move this plugin to a suitable location and try installing it using `lip install plugin.tth`.

### Publish the Plugin

Commit your changes to the GitHub repository, then click on "Releases" in the repository on GitHub, click on "Create a new release," fill in the "Tag version" and "Release title" fields, and then click on "Publish release" to publish the plugin. Note that the corresponding tag must be in a format similar to `v0.1.0`, which means it should be the value of the `version` field in `tooth.json` prefixed with a `v`.

You can then install your plugin using `lip install github.com/my-github-username/plugin-name`. Due to synchronization delays in the version listing, this command may throw an error in the initial period after the release. In such cases, you can specify the version number to install the plugin, for example, `lip install github.com/my-github-username/plugin-name@0.1.0`.

After some time, you will also be able to see your plugin in LipUI and <www.lippkg.com>.
78 changes: 78 additions & 0 deletions docs/tutorials/publish_your_first_plugin.zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# 发布你的第一个插件

在教程[创建你的第一个插件](create_your_first_plugin.md)中,我们创建了一个简单的插件。在本教程中,我们将学习如何发布插件。

### 前置条件

首先,你应当确保你安装了[lip](https://github.com/lippkg/lip)

你还应当按照[创建你的第一个插件](create_your_first_plugin.md)中的步骤创建了一个插件,其中插件导出目录有类似如下的结构:

```
.
└── plugin-name
├── manifest.json
├── plugin-name.dll
└── plugin-name.pdb
```

其中,`plugin-name`是插件名。

### 创建一个GitHub仓库

首先,你需要创建一个GitHub仓库,用于存放你的插件。你可以使用任何你喜欢的名称,例如`plugin-name`

在仓库中,我们建议放一个`README.md`文件,用于描述插件;并放一个`logo.png`文件,用于作为插件的图标。

### 创建一个tooth.json

在插件导出目录中创建一个`tooth.json`文件,内容如下:

```json
{
"format_version": 2,
"tooth": "github.com/my-github-username/plugin-name",
"version": "0.1.0",
"info": {
"name": "MyPlugin",
"description": "MyPlugin is a great plugin!",
"author": "My Name",
"tags": [
"plugin"
]
},
"dependencies": {
"github.com/tooth-hub/another-plugin": "2.0.x"
},
"prerequisites": {
"github.com/tooth-hub/levilamina": "1.0.x"
},
"files": {
"place": [
{
"src": "plugin-name/*",
"dest": "plugins/plugin-name"
}
]
}
}
```

替换`tooth`字段的值为你的插件的GitHub仓库地址,替换`version`字段的值为你的插件的版本号,填写`info`中各个字段的值,填写`dependencies``prerequisites`中各个字段的值。

!!! note
`dependencies`在安装插件时,会自动安装依赖的插件,在卸载插件时,会自动卸载依赖的插件。但是`prerequisites`不会自动安装,而是在缺少依赖时报错。一般来说,`prerequisites`中的插件应当是一些基础性的、框架级别的包,例如`github.com/tooth-hub/levilamina`,以避免插件的卸载过程中误卸载了这些包。

更多关于`tooth.json`的信息,请参考<https://docs.lippkg.com/tooth_json_file_reference.html>

### 尝试打包和安装插件

在插件导出目录中运行`lip tooth pack plugin.tth`,将会在当前目录下生成一个`plugin.tth`文件,这是一个打包好的插件。你可以移动这个插件到合适的地方,并使用`lip install plugin.tth`尝试安装这个插件。

### 发布插件

将更改提交到GitHub仓库,然后在GitHub仓库中点击`Releases`,点击`Create a new release`,填写`Tag version``Release title`,然后点击`Publish release`,即可发布插件。注意对应的tag必须为类似`v0.1.0`的格式,也就是`tooth.json``version`字段的值加上一个`v`

然后你就可以通过`lip install github.com/my-github-username/plugin-name`来安装你的插件了。由于版本列表同步延迟,这个命令可能会在刚发布的一段时间内报错,你可以指定版本号来安装插件,例如`lip install github.com/my-github-username/plugin-name@0.1.0`

在一段时间后,你也可以在LipUI和<www.lippkg.com>查看到你的插件了。
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ nav:
- tutorials/customized_terrain_generation.md
- tutorials/fly_in_survival.md
- tutorials/more_dimensions.md
- tutorials/publish_your_first_pack.md
- tutorials/publish_your_first_plugin.md
- tutorials/understanding_functions_in_bds.md

- Guides:
Expand Down

0 comments on commit 789e870

Please sign in to comment.