docs(zh): for pkg json

docs/manual-zh/src/SUMMARY.md

@@ -1,3 +1,17 @@
 # 目录
 
-- [构建系统教程](./tutorial.md)
+- [构建系统教程](./tutorial.md)
+- [包配置](./package.md)
+  - [包名](./package/name.md)
+  - [is-main 字段](./package/is-main.md)
+  - [import 字段](./package/import.md)
+  - [test-import 字段](./package/test-import.md)
+  - [wbtest-import字段](./package/wbtest-import.md)
+  - [链接选项](./package/link.md)
+    - [wasm 后端链接选项](./package/link/wasm.md)
+    - [wasm-gc 后端链接选项](./package/link/wasm-gc.md)
+    - [js 后端链接选项](./package/link/js.md)
+  - [warn 列表](./package/warnings.md)
+  - [alert 列表](./package/alerts.md)
+  - [条件编译](./package/conditional-compilation.md)
+  - [预构建命令](./package/pre-build.md)

docs/manual-zh/src/package.md

@@ -0,0 +1,3 @@
+# 包配置
+
+moon 使用 `moon.pkg.json` 文件来识别、描述一个包。

docs/manual-zh/src/package/alerts.md

@@ -0,0 +1,9 @@
+# alert 列表
+
+关闭用户预设 alter。
+
+```json
+{
+  "alert_list": "-alert_1-alert_2"
+}
+```

docs/manual-zh/src/package/conditional-compilation.md

@@ -0,0 +1,31 @@
+# 条件编译
+
+条件编译的最小单位是文件。
+
+在条件编译表达式中，支持三种逻辑操作符：`and`、`or` 和 `not`，其中 `or` 操作符可以省略不写。
+
+例如，`["or", "wasm", "wasm-gc"]` 可以简写为 `["wasm", "wasm-gc"]`。
+
+条件表达式中的条件可以分为后端和优化级别：
+
+- **后端条件**：`"wasm"`、`"wasm-gc"` 和 `"js"`
+- **优化等级条件**：`"debug"` 和 `"release"`
+
+条件表达式支持嵌套。
+
+如果一个文件未在 `"targets"` 中列出，它将默认在所有条件下编译。
+
+示例：
+
+```json
+{
+    "targets": {
+        "only_js.mbt": ["js"],
+        "not_js.mbt": ["not", "js"],
+        "only_debug.mbt": ["and", "debug"],
+        "js_and_release.mbt": ["and", "js", "release"],
+        "js_only_test.mbt": ["js"],
+        "complex.mbt": ["or", ["and", "wasm", "release"], ["and", "js", "debug"]]
+    }
+}
+``` 

docs/manual-zh/src/package/import.md

@@ -0,0 +1,3 @@
+# import 字段
+
+`import` 字段用于指定一个包所依赖的其他包。

docs/manual-zh/src/package/is-main.md

@@ -0,0 +1,8 @@
+# is-main 字段
+
+`is-main` 字段用于指定一个包是否需要被链接成一个可执行的文件。
+
+链接所生成的产物与后端相关，当该字段为 `true` 时：
+
+- 对于 `wasm` 和 `wasm-gc` 后端，将会生成一个可以独立运行的 WebAssembly 模块。
+- 对于 `js` 后端，将会生成一个可以独立运行的 JavaScript 文件。

docs/manual-zh/src/package/link.md

@@ -0,0 +1,15 @@
+# 链接选项
+
+moon 默认只会链接 `is-main` 为 `true` 的包，如果需要链接其他包，可以通过 `link` 选项指定。
+
+`link` 选项用于指定链接选项，它的值可以为布尔值或一个对象。
+
+- `link` 值为 `true` 时，表示需要链接该包。构建时所指定的后端不同，产物也不同。
+
+  ```json
+  {
+    "link": true
+  }
+  ```
+
+- `link` 值为对象时，表示需要链接该包，并且可以指定链接选项，详细配置请查看对应后端的子页面。

docs/manual-zh/src/package/link/js.md

@@ -0,0 +1,40 @@
+# js 后端链接选项
+
+#### 可配置选项
+
+- `exports` 选项用于指定 JavaScript 模块的导出函数名。
+
+  例如，如下配置将当前包中的 `hello` 函数导出为 JavaScript 模块的 `hello` 函数。在 JavaScript 宿主中，可以通过 `hello` 函数来调用当前包中的 `hello` 函数。
+
+  ```json
+  {
+    "link": {
+      "js": {
+        "exports": [
+          "hello"
+        ]
+      }
+    }
+  }
+  ```
+
+- `format` 选项用于指定 JavaScript 模块的输出格式。
+
+  目前支持的格式有：
+  - `esm`
+  - `cjs`
+  - `iife`
+
+  例如，如下配置将当前包的输出格式指定为 ES Module。
+
+  ```json
+  {
+    "link": {
+      "js": {
+        "format": "esm"
+      }
+    }
+  }
+  ```
+
+

docs/manual-zh/src/package/link/wasm-gc.md

@@ -0,0 +1,3 @@
+# wasm-gc 后端链接选项
+
+wasm-gc 后端与 wasm 后端的链接选项类似，只不过没有 `heap-start-address` 选项。

docs/manual-zh/src/package/link/wasm.md

@@ -0,0 +1,63 @@
+# wasm 后端链接选项
+
+#### 可配置选项
+
+- `exports` 选项用于指定 wasm 后端导出的函数名。
+
+  例如，如下配置将当前包中的 `hello` 函数导出为 wasm 模块的 `hello` 函数, `foo` 函数导出为 wasm 模块的 `foo` 函数。在 wasm 宿主中，可以通过 `hello` 和 `bar` 函数来调用当前包中的 `hello` 和 `foo` 函数。
+
+  ```json
+  {
+    "link": {
+      "wasm": {
+        "exports": [
+          "hello",
+          "foo:bar"
+        ]
+      },
+    }
+  }
+  ```
+
+- `heap_start_address` 选项用于指定 moonc 编译到 wasm 后端时能够使用的线性内存的起始地址。
+
+  例如，如下配置将线性内存的起始地址设置为 1024。
+
+  ```json
+  {
+    "link": {
+        "wasm": {
+          "heap_start_address": 1024
+      },
+    }
+  }
+  ```
+
+- `import-memory` 选项用于指定 wasm 模块导入的线性内存。
+
+  例如，如下配置将 wasm 模块导入的线性内存指定为 `env` 模块的 `memory` 变量。
+
+  ```json
+  {
+    "link": {
+      "wasm": {
+        "import-memory": {
+          "module": "env",
+          "name": "memory"
+        }
+      },
+    }
+  }
+  ```
+
+- `export-memory-name` 选项用于指定 wasm 模块导出的线性内存名称。
+
+  ```json
+  {
+    "link": {
+      "wasm": {
+        "export-memory-name": "memory"
+      },
+    }
+  }
+  ```

docs/manual-zh/src/package/name.md

@@ -0,0 +1,3 @@
+# 包名
+
+包名不可配置，它由包的目录名决定。

docs/manual-zh/src/package/pre-build.md

@@ -0,0 +1,34 @@
+# 预构建命令
+
+字段 `"pre-build"` 用于指定预构建命令，预构建命令会在 `moon check|build|test` 等构建命令之前执行。
+
+`"pre-build"`是一个数组，数组中的每个元素是一个对象，对象中包含 `input`，`output` 和 `command` 三个字段，`input` 和 `output` 可以是字符串或者字符串数组，`command` 是字符串，`command` 中可以使用任意命令行命令，以及 `$input`，`$output` 变量，分别代表输入文件、输出文件，如果是数组默认使用空格分割。
+
+目前内置了一个特殊命令 `:embed`，用于将文件转换为 MoonBit 源码，`--text` 参数用于嵌入文本文件，`--binary` 用于嵌入二进制文件，`--text` 为默认值，可省略不写。`--name` 用于指定生成的变量名，默认值为 `resource`。命令的执行目录为当前 `moon.pkg.json` 所在目录。
+
+```json
+{
+  "pre-build": [
+    {
+      "input": "a.txt",
+      "output": "a.mbt",
+      "command": ":embed -i ${input} -o ${output}"
+    }
+  ]
+}
+```
+
+如果当前包目录下的 `a.txt` 的内容为
+```
+hello,
+world
+```
+
+执行  `moon build` 后，在此 `moon.pkg.json` 所在目录下生成如下 `a.mbt` 文件
+
+```
+let resource : String =
+  #|hello,
+  #|world
+  #|
+```

docs/manual-zh/src/package/test-import.md

@@ -0,0 +1,3 @@
+# test-import 字段
+
+`test-import` 字段用于指定该包对应的黑盒测试包所依赖的其他包。

docs/manual-zh/src/package/warnings.md

@@ -0,0 +1,45 @@
+# warn 列表
+
+关闭对应的编译器预设警告编号。
+
+例如，如下配置中 `-2` 代表关闭编号为 2(Unused variable) 的警告
+
+```json
+{
+  "warn_list": "-2",
+}
+```
+
+可用 `moonc build-package -warn-help` 查看编译器预设的警告编号
+
+```
+$ moonc -v                      
+v0.1.20240914+b541585d3
+
+$ moonc build-package -warn-help
+Available warnings: 
+  1 Unused function.
+  2 Unused variable.
+  3 Unused type declaration.
+  4 Redundant case in a pattern matching (unused match case).
+  5 Unused function argument.
+  6 Unused constructor.
+  7 Unused module declaration.
+  8 Unused struct field.
+ 10 Unused generic type variable.
+ 11 Partial pattern matching.
+ 12 Unreachable code.
+ 13 Unresolved type variable.
+ 14 Lowercase type name.
+ 15 Unused mutability.
+ 16 Parser inconsistency.
+ 18 Useless loop expression.
+ 19 Top-level declaration is not left aligned.
+ 20 Invalid pragma
+ 21 Some arguments of constructor are omitted in pattern.
+ 22 Ambiguous block.
+ 23 Useless try expression.
+ 24 Useless error type.
+ 26 Useless catch all.
+  A all warnings
+```

docs/manual-zh/src/package/wbtest-import.md

@@ -0,0 +1,3 @@
+# wbtest-import字段
+
+`wbtest-import` 字段用于指定该包对应的白盒测试包所依赖的其他包。