使用与发布包

使用与发布包#

MoonBit 的构建系统无缝集成了包管理与文档生成工具，让用户可以轻松从 mooncakes.io 获取依赖、访问模块文档并发布新模块。

在开始之前，请确保你已经安装了 moon。

设置 mooncakes.io 账户#

备注

如果你不需要发布，可以跳过此步骤。

如果你没有 mooncakes.io 账户，请运行 moon register 并按照指南操作。如果你之前注册过账户，可以使用 moon login 登录。

当你看到以下消息时，表示你已成功登录：

API token saved to ~/.moon/credentials.json

设置 MoonBit 项目#

打开现有项目，或通过 moon new <PATH> 创建新项目。例如：

$ moon new .
Created username/myapp at .

它会在该路径下生成模板文件：

├── AGENTS.md                    # Agent 协作指南
├── LICENSE                      # 开源许可证 
├── README.mbt.md                # 带 MoonBit 类型检查支持的 README 文件 
├── README.md -> README.mbt.md   # 为需要 README.md 的平台提供的符号链接
├── cmd                           
│   └── main                     
│       ├── main.mbt             # MoonBit 源文件 
│       └── moon.pkg             # username/myapp/cmd/main 包的配置文件
├── moon.mod.json                # username/myapp 模块配置
├── moon.pkg                     # username/myapp 包配置文件
├── myapp.mbt                    # MoonBit 源文件
├── myapp_test.mbt               # 黑盒测试
└── myapp_wbtest.mbt             # 白盒测试

moon new <PATH> 会生成一个包含两个包的起始模块。模块是包含多个包的发布单元。包表示一个命名空间和编译单元，由包配置文件定义，并包含同目录下的 .mbt 文件。

模块和包通过一种特殊路径标识（不是文件系统路径）。例如：

username/myapp/cmd/main
─────────────────┬─────
────────┬─────   │
        │        │
        │        └─ 位于 `username/myapp` 模块下的包 `username/myapp/cmd/main`
        │
        └────────── 模块路径，同时也定义了包 `username/myapp`

默认模板包含测试文件、文档和协作元数据。你可以安全删除任何不需要的模板文件。下面同样是一个有效的 MoonBit 项目：

├── moon.mod.json
├── moon.pkg
└── source.mbt

添加依赖#

你可以在 mooncakes.io 浏览所有可用模块。使用 moon add 添加所需依赖，或手动编辑 moon.mod.json 中的 deps 字段。

例如，要添加 moonbit-community/starter 模块的最新版本：

$ moon add moonbit-community/starter

备注

Moon 也支持本地依赖。详见 依赖管理。

从模块导入包#

moonbit-community/starter 模块包含一个 moonbit-community/starter/rabbit 包。

把 moonbit-community/starter 模块添加为依赖后，如果要在 username/myapp/cmd/main 包中使用 moonbit-community/starter/rabbit 包，你需要先导入它：

// 在 `cmd/main/moon.pkg` 中添加此导入
import {
  "moonbit-community/starter/rabbit"
}

options(
  "is-main": true
)

备注

你还可以给导入的包起一个别名：

import {
  "moonbit-community/starter/rabbit" @alias
}

现在你可以调用 rabbit 包中的 hello 函数：

// 在 `cmd/main/main.mbt` 中
fn main {
  // println("hello")
  @rabbit.hello()
}

运行你的主包，查看终端输出。

$ moon run cmd/main

移除依赖#

你可以通过 moon remove <模块名> 移除依赖。

发布你的模块#

如果你准备分享你的模块，使用 moon publish 将模块推送到 mooncakes.io。在发布之前有一些重要的注意事项需要记住：

语义化版本约定#

MoonBit 的包管理遵循 语义化版本 约定。每个模块必须以 MAJOR.MINOR.PATCH 格式定义一个版本号。每次推送，模块必须递增：

  • 当你进行不兼容的 API 更改时，递增 MAJOR 版本

  • 在向后兼容的方式下添加功能时，递增 MINOR 版本

  • 在进行向后兼容的错误修复时，递增 PATCH 版本

附加的预发布和构建元数据标签可作为 MAJOR.MINOR.PATCH 格式的扩展。

moon 实现了 最小版本选择，根据模块的语义化版本信息自动处理和安装依赖。最小版本选择假定每个模块声明自己的依赖要求，并遵循语义化版本约定，旨在使用户的依赖图尽可能接近作者的开发时依赖。

自述文件 & 元数据#

moon.mod.json 和 README.md 中的元数据将显示在 mooncakes.io 上。

元数据包括以下部分：

  • license：此模块的许可证，遵循 SPDX 约定

  • keywords：此模块的关键字

  • repository：包源代码仓库的 URL

  • description：此模块的简短描述

  • homepage：模块主页的 URL

目录