update post

Author: waruqi

docs/posts/xmake-update-v3.1.1.md

@@ -22,30 +22,18 @@ architectures, a reworked template distribution, and a `pkg` package manager for
 An addon extends **xmake itself**. Where a package provides libraries for your program, an
 addon provides new abilities for the build tool.
 
-```sh
-$ xmake addon --install esp32-devel
-$ xmake create -t esp32.blink -l c blink
-$ cd blink
-$ xmake f --board=esp32c3
-$ xmake
-$ xmake install                       # flash it to the board
-```
-
-Those five lines are the whole ESP32 setup: the addon carried the cross toolchain, the build
-rules, the flashing logic and the project template.
-
 #### What an addon can carry
 
 Every payload is optional, an addon ships only what it provides:
 
 | Payload | What it becomes | Used as |
 | --- | --- | --- |
-| `plugins/` | a new xmake command | `xmake monitor` |
-| `rules/` | a build rule | `add_rules("@addon/esp32-devel/app")` |
-| `toolchains/` | a toolchain | `set_toolchains("@addon/esp32-devel/esp32")` |
-| `templates/` | a project template | `xmake create -t esp32.blink` |
-| `modules/` | importable lua modules | `import("@addon.serial-tools.serial")` |
-| `includes/` | includable configuration | `includes("@addon/esp32-devel/board")` |
+| `plugins/` | a new xmake command | `xmake hello` |
+| `rules/` | a build rule | `add_rules("@addon/my-addon/app")` |
+| `toolchains/` | a toolchain | `set_toolchains("@addon/my-addon/mycc")` |
+| `templates/` | a project template | `xmake create -t myapp` |
+| `modules/` | importable lua modules | `import("@addon.my-addon.utils")` |
+| `includes/` | includable configuration | `includes("@addon/my-addon/board")` |
 
 The payloads are namespaced through `@addon/<name>/...`, so two addons never collide. Plugins
 and templates are the exception — a command name is global — and an install which would
@@ -54,14 +42,14 @@ shadow another addon's command is rejected.
 #### Managing addons
 
 ```sh
-$ xmake addon --install esp32-devel                      # from the repository index
-$ xmake addon --install github:xmake-addons/esp32-devel  # from github, `#branch` works too
+$ xmake addon --install my-addon                         # from the repository index
+$ xmake addon --install github:myrepo/my-addon           # from github, `#branch` works too
 $ xmake addon --install https://github.com/user/repo.git # from any git url
 $ xmake addon --install /path/to/my-addon                # from a local directory
 
 $ xmake addon --list
-$ xmake addon --search esp32
-$ xmake addon --remove esp32-devel
+$ xmake addon --search my
+$ xmake addon --remove my-addon
 $ xmake addon --upgrade
 ```
 
@@ -71,12 +59,12 @@ A project can declare what it needs, so a fresh clone does not have to install a
 hand — xmake fetches the missing addons when the project is loaded:
 
 ```lua
-add_addons("esp32-devel 1.0.x")
+add_addons("my-addon 1.0.x")
 
-includes("@addon/esp32-devel/board")
+includes("@addon/my-addon/board")
 
-target("blink")
-    add_rules("@addon/esp32-devel/app")
+target("hello")
+    add_rules("@addon/my-addon/app")
     add_files("src/*.c")
 ```
 
@@ -153,7 +141,7 @@ Three places, a handful of interfaces:
 
 ```lua
 -- 1. in xmake.lua, what a project needs
-add_addons("esp32-devel 1.0.x")
+add_addons("my-addon 1.0.x")
 ```
 
 ```lua
@@ -164,7 +152,7 @@ addon("my-addon")
     set_license("Apache-2.0")
     set_sourcedir("src")        -- the payload root inside the repository
     add_deps("serial-tools")    -- other addons this one needs
-    add_globalmodules("detect.tools.find_avrdude")  -- only for the lookups xmake does by name
+    add_globalmodules("detect.tools.find_mytool")   -- only for the lookups xmake does by name
 ```
 
 ```lua
@@ -206,10 +194,10 @@ carries the package recipes and exposes them through an includes file:
 
 ```lua
 -- src/includes/packages/xmake.lua
-package("avr-gcc")
+package("mycc")
     set_kind("toolchain")
-    add_urls("https://.../avr-gcc-$(version).tar.bz2")
-    add_versions("7.3.0", "<sha256>")
+    add_urls("https://.../mycc-$(version).tar.gz")
+    add_versions("1.0.0", "<sha256>")
     on_install(function (package)
         os.cp("*", package:installdir())
     end)
@@ -219,11 +207,11 @@ package_end()
 ```lua
 -- src/includes/board/xmake.lua
 includes("../packages")
-option("board", {default = "uno", description = "Set the target board."})
-add_requires("avr-gcc", "avrdude")
+option("board", {default = "myboard", description = "Set the target board."})
+add_requires("mycc", "myflasher")
 ```
 
-The project writes one line — `includes("@addon/avr-devel/board")` — and gets the options,
+The project writes one line — `includes("@addon/my-addon/board")` — and gets the options,
 the toolchain and the flash tool.
 
 #### The official addons
@@ -240,6 +228,18 @@ The first batch is already in xmake-repo:
 | `format-plugin` / `doxygen-plugin` / `macro-plugin` | the former builtin commands |
 | `basic-templates` | the templates which need an external sdk (sdl, qt, verilator) |
 
+`esp32-devel`, for instance, carries the cross toolchain, the build rules, the flashing logic
+and the project template, so the whole ESP32 setup is:
+
+```sh
+$ xmake addon --install esp32-devel
+$ xmake create -t esp32.blink -l c blink
+$ cd blink
+$ xmake f --board=esp32c3
+$ xmake
+$ xmake install                       # flash it to the board
+```
+
 ### xmake ai, an Agent Written in Xmake Lua
 
 [xmake-harness](https://github.com/xmake-addons/xmake-harness) is the addon that shows how far
@@ -375,8 +375,8 @@ New architectures for the cross and linux platforms, e.g. SPARC64.
 ### Reworked Template Distribution
 
 The templates directory was reorganized and the distribution reworked, which is what makes the
-`templates/` payload of an addon possible — `xmake create -t esp32.blink` comes from an addon,
-not from the xmake installation.
+`templates/` payload of an addon possible — the templates behind `xmake create -t` can now come
+from an addon instead of being built into the xmake installation.
 
 ### pkg Package Manager for BSD
 

docs/zh/posts/xmake-update-v3.1.1.md

@@ -16,43 +16,32 @@ outline: deep
 
 我们平时用的包，提供的是程序要链接的库，而 addon 扩展的是 xmake 本身，给构建工具增加新的能力。
 
-```sh
-$ xmake addon --install esp32-devel
-$ xmake create -t esp32.blink -l c blink
-$ cd blink
-$ xmake f --board=esp32c3
-$ xmake
-$ xmake install                       # 烧写到板子
-```
-
-整个 ESP32 的开发流程就这几行，交叉工具链、构建规则、烧写逻辑和工程模板，全部由这个 addon 提供，用户不需要再单独去装任何东西。
-
 #### 一个 addon 可以提供什么
 
 下面这几类扩展内容都是可选的，addon 提供哪些就带哪些：
 
 | 目录 | 提供的能力 | 使用方式 |
 | --- | --- | --- |
-| `plugins/` | 新的 xmake 命令 | `xmake monitor` |
-| `rules/` | 构建规则 | `add_rules("@addon/esp32-devel/app")` |
-| `toolchains/` | 工具链 | `set_toolchains("@addon/esp32-devel/esp32")` |
-| `templates/` | 工程模板 | `xmake create -t esp32.blink` |
-| `modules/` | 可导入的 lua 模块 | `import("@addon.serial-tools.serial")` |
-| `includes/` | 可包含的配置片段 | `includes("@addon/esp32-devel/board")` |
+| `plugins/` | 新的 xmake 命令 | `xmake hello` |
+| `rules/` | 构建规则 | `add_rules("@addon/my-addon/app")` |
+| `toolchains/` | 工具链 | `set_toolchains("@addon/my-addon/mycc")` |
+| `templates/` | 工程模板 | `xmake create -t myapp` |
+| `modules/` | 可导入的 lua 模块 | `import("@addon.my-addon.utils")` |
+| `includes/` | 可包含的配置片段 | `includes("@addon/my-addon/board")` |
 
 这些扩展内容都是带命名空间的，统一通过 `@addon/<name>/...` 来引用，所以两个 addon 即使提供了同名的规则也不会冲突。只有插件和模板是例外，因为命令名和模板 id 是全局的，如果安装的 addon 会覆盖掉别的 addon 的命令，xmake 会直接拒绝。
 
 #### addon 的管理
 
 ```sh
-$ xmake addon --install esp32-devel                      # 从仓库索引安装
-$ xmake addon --install github:xmake-addons/esp32-devel  # 从 github 安装，支持 `#branch`
+$ xmake addon --install my-addon                         # 从仓库索引安装
+$ xmake addon --install github:myrepo/my-addon           # 从 github 安装，支持 `#branch`
 $ xmake addon --install https://github.com/user/repo.git # 从任意 git url 安装
 $ xmake addon --install /path/to/my-addon                # 从本地目录安装
 
 $ xmake addon --list
-$ xmake addon --search esp32
-$ xmake addon --remove esp32-devel
+$ xmake addon --search my
+$ xmake addon --remove my-addon
 $ xmake addon --upgrade
 ```
 
@@ -61,12 +50,12 @@ $ xmake addon --upgrade
 工程也可以直接声明自己需要哪些 addon，这样别人克隆下来就不用手动安装了，加载工程的时候，xmake 会自动把缺失的 addon 拉下来：
 
 ```lua
-add_addons("esp32-devel 1.0.x")
+add_addons("my-addon 1.0.x")
 
-includes("@addon/esp32-devel/board")
+includes("@addon/my-addon/board")
 
-target("blink")
-    add_rules("@addon/esp32-devel/app")
+target("hello")
+    add_rules("@addon/my-addon/app")
     add_files("src/*.c")
 ```
 
@@ -139,7 +128,7 @@ addon 相关的接口不多，主要就是下面三个地方：
 
 ```lua
 -- 1. 在 xmake.lua 中，声明工程需要哪些 addon
-add_addons("esp32-devel 1.0.x")
+add_addons("my-addon 1.0.x")
 ```
 
 ```lua
@@ -150,7 +139,7 @@ addon("my-addon")
     set_license("Apache-2.0")
     set_sourcedir("src")        -- 仓库内存放扩展目录的根目录
     add_deps("serial-tools")    -- 依赖的其他 addon
-    add_globalmodules("detect.tools.find_avrdude")  -- 只有需要被 xmake 按名字查找的模块才用得上
+    add_globalmodules("detect.tools.find_mytool")   -- 只有需要被 xmake 按名字查找的模块才用得上
 ```
 
 ```lua
@@ -187,10 +176,10 @@ addon 提供的所有东西，都要通过 `@addon/<name>/...` 或者 `@addon.<n
 
 ```lua
 -- src/includes/packages/xmake.lua
-package("avr-gcc")
+package("mycc")
     set_kind("toolchain")
-    add_urls("https://.../avr-gcc-$(version).tar.bz2")
-    add_versions("7.3.0", "<sha256>")
+    add_urls("https://.../mycc-$(version).tar.gz")
+    add_versions("1.0.0", "<sha256>")
     on_install(function (package)
         os.cp("*", package:installdir())
     end)
@@ -200,11 +189,11 @@ package_end()
 ```lua
 -- src/includes/board/xmake.lua
 includes("../packages")
-option("board", {default = "uno", description = "Set the target board."})
-add_requires("avr-gcc", "avrdude")
+option("board", {default = "myboard", description = "Set the target board."})
+add_requires("mycc", "myflasher")
 ```
 
-工程里只需要 `includes("@addon/avr-devel/board")` 一行，配置选项、工具链和烧写工具就都齐了。
+工程里只需要 `includes("@addon/my-addon/board")` 一行，配置选项、工具链和烧写工具就都齐了。
 
 #### 目前提供的官方 addon
 
@@ -220,6 +209,17 @@ add_requires("avr-gcc", "avrdude")
 | `format-plugin` / `doxygen-plugin` / `macro-plugin` | 原来的几个内置命令 |
 | `basic-templates` | 依赖外部 SDK 的工程模板（sdl、qt、verilator） |
 
+以 `esp32-devel` 为例，交叉工具链、构建规则、烧写逻辑和工程模板都由它提供，所以整个 ESP32 的开发流程就这么几行，用户不需要再单独去装什么东西：
+
+```sh
+$ xmake addon --install esp32-devel
+$ xmake create -t esp32.blink -l c blink
+$ cd blink
+$ xmake f --board=esp32c3
+$ xmake
+$ xmake install                       # 烧写到板子
+```
+
 ### xmake ai，用 xmake lua 写的 AI 助手
 
 [xmake-harness](https://github.com/xmake-addons/xmake-harness) 这个 addon 算是把 addon 的能力用到了极致，它是一个完整的 AI Agent 框架，会话记录、agent 主循环、工具管线、权限策略、沙箱、skills、子 agent、斜杠命令和终端 UI，全部用 xmake lua 实现，没有任何第三方依赖。装上之后就多了一个 `xmake ai` 命令：
@@ -332,7 +332,7 @@ set_policy("package.host.install_locally", true)   -- 如果你确实想让工
 
 ### 重构模板分发
 
-我们重新组织了模板目录，也重构了模板的分发方式，addon 的 `templates/` 目录正是基于这个改动才能实现，`xmake create -t esp32.blink` 这个模板来自 addon，而不是 xmake 安装包自带的。
+我们重新组织了模板目录，也重构了模板的分发方式，addon 的 `templates/` 目录正是基于这个改动才能实现，`xmake create -t` 用到的模板现在可以由 addon 提供，而不必内置在 xmake 安装包里。
 
 ### BSD 的 pkg 包管理器