包配置

moon 使用 moon.pkg.json 文件来标识和描述一个包。访问 moon 的仓库 查看完整的 JSON 模式。

名称

包名称不可配置；它由包的文件夹目录名称确定。

is-main

is-main 字段用于指定包是否需要链接为一个可执行文件。

链接过程的输出取决于后端。当此字段设置为 true 时：

• 对于 Wasm 和 wasm-gc 后端，将生成一个独立的 WebAssembly 模块。

• 对于 js 后端，将生成一个独立的 JavaScript 文件。

导入依赖

导入

import 字段用于指定包依赖的其他包。

例如，以下导入了 moonbitlang/quickcheck 和 moonbitlang/x/encoding，将后者别名为 lib 并从后者导入函数 encode。用户可以使用 @lib.encode 代替 encode。

{
  "import": [
    "moonbitlang/quickcheck",
    { "path" : "moonbitlang/x/encoding", "alias": "lib", "value": ["encode"] }
  ]
}

测试导入

test-import 字段用于指定此包的黑盒测试包依赖的其他包，配置语法与 import 相同

test-import 字段用于指定是否导入被测试包的公共定义（默认为 true）。

白盒测试导入

wbtest-import 字段用于指定此包的白盒测试包依赖的其他包，配置语法与 import 相同。

条件编译

条件编译的最小单元是一个文件。

在条件编译表达式中，支持三种逻辑运算符：and、or 和 not，其中 or 运算符可以省略。

例如，["or", "wasm", "wasm-gc"] 可以简化为 ["wasm", "wasm-gc"]。

表达式中的条件可以被归类为后端和优化层次：

• 后端条件："wasm"、"wasm-gc" 和 "js"

• 优化层次条件："debug" 和 "release"

条件表达式支持嵌套。

如果文件未列在 "targets" 中，它将默认在所有条件下编译。

例如：

{
  "targets": {
    "only_js.mbt": ["js"],
    "only_wasm.mbt": ["wasm"],
    "only_wasm_gc.mbt": ["wasm-gc"],
    "all_wasm.mbt": ["wasm", "wasm-gc"],
    "not_js.mbt": ["not", "js"],
    "only_debug.mbt": ["debug"],
    "js_and_release.mbt": ["and", ["js"], ["release"]],
    "js_only_test.mbt": ["js"],
    "js_or_wasm.mbt": ["js", "wasm"],
    "wasm_release_or_js_debug.mbt": ["or", ["and", "wasm", "release"], ["and", "js", "debug"]]
  }
}

链接选项

默认情况下，moon 仅链接 is-main 设置为 true 的包。如果需要链接其他包，可以使用 link 选项指定。

link 选项用于指定链接选项，其值可以是布尔值或对象。

• 当 link 值为 true 时，表示应链接包。输出将根据构建时指定的后端而有所不同。

  {
    "link": true
  }
  

• 当 link 值为对象时，表示应链接包，您可以指定链接选项。有关详细配置，请参阅相应后端的子页面。

Wasm 后端链接选项

共有选项

• exports 选项用于指定 Wasm 后端导出的函数名称。

  例如，在以下配置中，当前包中的 hello 函数被导出为 wasm 模块中的 hello 函数，foo 函数被导出为 Wasm 模块中的 bar 函数。在 Wasm 宿主中，可以调用 hello 和 bar 函数来调用当前包中的 hello 和 foo 函数。

  {
    "link": {
      "wasm": {
        "exports": [
          "hello",
          "foo:bar"
        ]
      },
      "wasm-gc": {
        "exports": [
          "hello",
          "foo:bar"
        ]
      }
    }
  }
  

• import-memory 选项用于指定 Wasm 模块导入的线性内存。

  例如，以下配置指定 Wasm 模块导入的线性内存是 env 模块的 memory 变量。

  {
    "link": {
      "wasm": {
        "import-memory": {
          "module": "env",
          "name": "memory"
        }
      },
      "wasm-gc": {
        "import-memory": {
          "module": "env",
          "name": "memory"
        }
      }
    }
  }
  

• export-memory-name 选项用于指定 Wasm 模块导出的线性内存的名称。

  {
    "link": {
      "wasm": {
        "export-memory-name": "memory"
      },
      "wasm-gc": {
        "export-memory-name": "memory"
      }
    }
  }
  

Wasm 线性内存后端链接选项

• heap-start-address 选项用于指定编译到 Wasm 后端时可以使用的线性内存的起始地址。

  例如，以下配置将线性内存的起始地址设置为 1024。

  {
    "link": {
      "wasm": {
        "heap-start-address": 1024
      }
    }
  }
  

Wasm GC 后端链接选项

• use-js-string-builtin 选项用于指定在编译到 Wasm GC 后端时是否应启用 内建 JS String 提案。它将使 MoonBit 中的 String 等效于 JavaScript 宿主运行时中的 String。

  例如，以下配置将启用内建 JS String 提案。

  {
    "link": {
      "wasm-gc": {
        "use-js-builtin-string": true
      }
    }
  }
  

• imported-string-constants 选项用于指定内建 JS String 提案使用的导入字符串命名空间，默认为 _。它应符合 JS 宿主运行时中的配置。

  例如，以下配置与 JS 初始化配置了导入字符串命名空间。

  {
    "link": {
      "wasm-gc": {
        "use-js-builtin-string": true,
        "imported-string-constants": "_"
      }
    }
  }
  

  const { instance } = await WebAssembly.instantiate(bytes, {}, { importedStringConstants: "strings" });
  

JS 后端链接选项

• exports 选项用于指定要在 JavaScript 模块中导出的函数名称。

  例如，在以下配置中，当前包中的 hello 函数被导出为 JavaScript 模块中的 hello 函数。在 JavaScript 宿主中，可以调用 hello 函数来调用当前包中的 hello 函数。

  {
    "link": {
      "js": {
        "exports": [
          "hello"
        ]
      }
    }
  }
  

• format 选项用于指定 JavaScript 模块的输出格式。

  目前支持的格式有：

  • esm

  • cjs

  • iife

  例如，以下配置将当前包的输出格式设置为 ES 模块。

  {
    "link": {
      "js": {
        "format": "esm"
      }
    }
  }
  

预构建

pre-build 字段用于指定预构建命令，这些命令将在构建命令（如 moon check|build|test）之前执行。

"pre-build" 是一个数组，其中每个元素是一个包含 input、output 和 command 字段的对象。input 和 output 字段可以是字符串或字符串数组，而 command 字段是一个字符串。在 command 中，可以使用任何 shell 命令，以及分别表示输入和输出文件的 $input 和 $output 变量。如果这些字段是数组，它们将默认使用空格连接。

目前，内置了一个特殊命令 :embed，它将文件转换为 MoonBit 源代码。--text 参数用于嵌入文本文件，--binary 用于二进制文件。--text 是默认值，可以省略。--name 参数用于指定生成的变量名，默认为 resource。该命令在 moon.pkg.json 文件所在的目录中执行。

{
  "pre-build": [
    {
      "input": "a.txt",
      "output": "a.mbt",
      "command": ":embed -i $input -o $output"
    }
  ]
}

如果当前包目录中 a.txt 的内容为：

hello,
world

那么在 moon.pkg.json 所在目录中运行 moon build 后，将生成以下 a.mbt 文件：

let resource : String =
  #|hello,
  #|world
  #|

警告列表

这用于禁用特定的预设编译器警告编号。

例如，在以下配置中，-2 禁用警告编号 2（未使用的变量）。

{
  "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

警示列表

禁用用户预设警示。

{
  "alert-list": "-alert_1-alert_2"
}