模块配置

模块配置#

moon 使用 moon.mod.json 文件来标识和描述一个模块。

提示

访问 moon 的仓库 查看最新最完整的 JSON 模式。

名称#

name 字段用于指定模块的名称，它是必需的。

{
  "name": "example"
  // ...
}

模块名称可以包含字母、数字、_、- 和 /。

对于发布到 mooncakes.io 的模块，模块名称必须以用户名开头。例如：

{
  "name": "moonbitlang/core"
  // ...
}

版本#

version 字段用于指定模块的版本。

此字段是可选的。对于发布到 mooncakes.io 的模块，版本号必须遵循 语义化版本 2.0.0 规范。

{
  "name": "example",
  "version": "0.1.0"
  // ...
}

依赖管理#

deps 字段用于指定模块的依赖项。

它由 moon add 和 moon remove 等命令自动管理。

{
  "name": "username/hello",
  "deps": {
    "moonbitlang/x": "0.4.6"
  }
}

你也可以指定一个本地依赖，例如：

{
  "name": "username/hello",
  "deps": {
    "username/other": {
      "path": "../other"
    }
  }
}

元信息#

README#

readme 字段用于指定模块的 README 文件的路径。

仓库#

repository 字段用于指定模块的仓库的 URL。

许可证#

license 字段用于指定模块的许可证。许可证类型必须符合 SPDX 许可证列表。

{
  "license": "MIT"
}

关键字#

keywords 字段用于指定模块的关键字。

{
  "keywords": ["example", "test"]
}

描述#

description 字段用于指定模块的描述。

{
  "description": "This is a description of the module."
}

包含和排除#

include 和 exclude 字段用于在发布过程中包含或排除特定的目录或文件。

它遵循 gitignore 语法，并且包含的内容会覆盖排除的内容。例如，以下配置将包含 build/assets 但排除 build 目录中的其他内容。

{
  "exclude": ["build"],
  "include": ["build/assets"]
}

你可以使用 moon package --list 来验证打包结果是否符合预期。

首选目标#

preferred-target 字段允许 moon 和语言服务器知道应该使用哪个目标作为默认目标，从而避免在开发针对 Wasm GC 以外的其他后端的项目时需要传递 --target。

{
  "preferred-target": "js"
}

源目录#

source 字段用于指定模块的源目录。

它必须是 moon.mod.json 文件所在目录的子目录，并且必须是相对路径。

当使用 moon new 命令创建一个模块时，将自动生成一个 src 目录，并且 source 字段的默认值将为 src。

{
  "source": "src"
}

如果 source 字段不存在，或其值为 null 或空字符串 ""，则等同于设置 "source": "."。这意味着源目录与 moon.mod.json 文件所在目录相同。

{
  "source": null
}
{
  "source": ""
}
{
  "source": "."
}

警告列表#

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

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

{
  "warn-list": "-2"
}

如果需要禁用多种警告，可以直接连接起来进行组合。

{
  "warn-list": "-2-4"
}

如果需要激活某种原来未启用的警告，则使用加号。

{
  "warn-list": "+31"
}

你可以使用 moonc build-package -warn-help 来查看预设编译器警告编号列表。

$ moonc -v
v0.1.20250606+a3f4966ca

$ moonc build-package -warn-help
Available warnings: 
  1 Unused function.
  2 Unused variable.
  3 Unused type declaration.
  4 Unused abstract type.
  5 Unused type variable.
  6 Unused constructor.
  7 Unused field or constructor argument.
  8 Redundant modifier.
  9 Unused function declaration.
 10 Struct never constructed.
 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.
 27 Deprecated syntax.
 28 Todo
 29 Unused package.
 30 Empty package alias.
 31 Optional argument never supplied.
 32 Default value of optional argument never used.
 33 Unused import value
 35 Reserved keyword.
 36 Loop label shadows another label.
 37 Unused loop label.
 38 Useless guard.
 39 Duplicated method.
 40 Call a qualified method using regular call syntax.
 41 Closed map pattern.
 42 Invalid attribute.
 43 Unused attribute.
 44 Invalid inline-wasm.
 46 Useless `..` in pattern
 47 Invalid mbti file
 48 Trait method with default implementation not marked with `= _`
 49 Unused pub definition because it does not exist in mbti file.
  A all warnings

警示列表#

禁用用户预设警示。

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

脚本#

scripts 字段用于定义与模块关联的自定义脚本。

postadd 脚本#

postadd 脚本在模块添加后自动运行。执行时，脚本的当前工作目录（cwd）设置为 moon.mod.json 文件所在的目录。

{
  "scripts": {
    "postadd": "python3 build.py"
  }
}

[实验性] 预构建配置脚本#

警告

这个功能是极其实验性的，其 API 可能随时发生变化。本文件反映了截至 2025-06-03 的实现。

重要

使用此功能可能会在您的计算机上执行任意代码。请谨慎使用，仅与受信任的依赖项一起使用。

pre-build 配置脚本的添加是为了帮助本地目标编程。要使用此脚本，请在您的 moon.mod.json 中添加您的脚本：

{
  "--moonbit-unstable-prebuild": "<path/to/build-script>"
}

路径是相对于项目根目录的相对路径。脚本可以是 JavaScript 脚本（扩展名为 .js、.cjs、.mjs）使用 node 执行，或者是 Python 脚本（扩展名为 .py）使用 python3 或 python 执行。

输入#

脚本将从标准输入流（stdin）接收一个具有 BuildScriptEnvironment 结构的 JSON：

/** 表示构建脚本接收的环境 */
interface BuildScriptEnvironment {
  env: Record<string, string>
  paths: Paths
}

interface BuildInfo {
  /** 当前构建脚本正在运行的目标信息 */
  host: TargetInfo
  /** 正在构建的模块的目标信息 */
  target: TargetInfo
}

interface TargetInfo {
  /** 我们正在使用的实际后端，例如 `wasm32`、`wasmgc`、`js`、`c`、`llvm` */
  kind: string // TargetBackend
}

输出#

脚本预计将在其标准输出流（stdout）中打印一个具有 BuildScriptOutput 结构的 JSON 字符串：

interface BuildScriptOutput {
  /** 构建变量 */
  vars?: Record<string, string>
  /** 链接配置 */
  link_configs?: LinkConfig[]
}

interface LinkConfig {
  /** 要配置的包的名称 */
  package: string

  /** 需要传播到依赖项的链接标志
   *
   * 参考：`cargo::rustc-link-arg=FLAG` */
  link_flags?: string

  /** 需要链接的库，传播到依赖项
   *
   * 参考：`cargo::rustc-link-lib=LIB` */
  link_libs?: string[]

  /** 需要在链接期间搜索的路径，传播到依赖项
   *
   * 参考：`cargo::rustc-link-search=[KIND=]PATH` */
  link_search_paths?: string[]
}

构建变量#

您可以在 moon.pkg.json 的本地链接参数中使用 vars 字段中发出的变量，格式为 ${build.<var_name>}。

例如，如果您的构建脚本输出：

{ "vars": { "CC": "gcc" } }

并且您的 moon.pkg.json 结构如下：

{
  "link": {
    "native": {
      "cc": "${build.CC}"
    }
  }
}

它会被转换为

{
  "link": {
    "native": {
      "cc": "gcc"
    }
  }
}
目录