Racket 编程入门

第 7 部分 · 走向生产:工程化与实战

发布一个 Racket 包——从零走完官方流程

写一个 Racket 包并发布到官方仓库,没有想象中那么难——这篇带你从零走完整套流程,做出符合官方标准的包。

读到这里,你大概已经装过不少别人的包了。装是消费,发是生产——而第一次发布的人,常常卡在两个极端:

  • 要么写成"Hello World"式的玩具包
  • 要么在发布前就被工程细节拖住

这篇的目标只有一个:

让你第一次发布的 Racket 包,符合官方生态的基本预期,并成功进入官方包目录。

什么样的包才算「合格」

如果目标只是“能被 Package Catalog 收录”,Racket 的硬性门槛其实比下面这份清单更低:例如,一个没有额外依赖的单 collection 包,技术上甚至可以没有 info.rkt。但如果目标是做一个可维护、可构建、对用户友好的正式包,建议至少准备:

  • 一个可被 require 的模块
  • 一个 info.rkt,显式声明 collection、依赖、版本等元数据
  • README 与 LICENSE
  • 可访问的包源码地址
  • 能通过构建的测试与文档

后文按这套“推荐工程基线”来走,而不是把它误写成 Catalog 的最低准入条件。

包的基本结构

my-first-pkg/
├── main.rkt
├── info.rkt
├── my-first-pkg.scrbl
├── README.md
├── LICENSE
└── tests/
 └── test-main.rkt

这是 Racket 官方生态中 最常见、最稳妥 的结构,新手不建议自行变形。

一个真实可发布的模块

#lang racket/base

(require racket/contract)

(provide add1-safe
 (contract-out
 [even? (-> exact-integer? boolean?)]))

(define (add1-safe x)
 (+ x 1))

这个示例刻意保持简单,但具备官方包的基本特征:

  • 使用 racket/base
  • 明确 provide
  • 至少一个公共 API
  • 至少一个带合约的导出函数

info.rkt:包元数据的中枢

#lang info

(define collection "my-first-pkg")
(define pkg-desc "My first Racket package")
(define version "0.1.0")
(define pkg-authors '("Your Name"))

(define deps '("base"))
(define build-deps '("scribble-lib" "racket-doc" "rackunit-lib"))

(define scribblings '(("my-first-pkg.scrbl" ())))

(define license 'MIT)

info.rkt 是包元数据的主要入口:依赖、版本、collection 形态、文档等都可以在这里声明。对于没有额外依赖的简单单 collection 包,它并非技术上的绝对必需;但实际发布时强烈建议保留,否则包的含义和依赖关系很容易变得隐式。

文档:不是 Catalog 硬门槛,但正式包应该有

Package Catalog 并不把“必须有 Scribble 文档”当成所有包的硬性准入条件。不过,对准备给别人使用的正式包来说,文档几乎是必需品。

#lang scribble/manual

@require[@for-label[my-first-pkg racket/base]]

@title{My First Package}
@author{Your Name}

@defmodule[my-first-pkg]

@section{API}

@defproc[(add1-safe [x integer?]) integer?]{
Adds 1 to @racket[x].
}

要求只有三点:

  • 有 @defmodule
  • 每个导出函数有说明
  • 文档可以成功构建

测试:为构建而写

#lang racket/base

(require rackunit
 my-first-pkg)

(check-equal? (add1-safe 1) 2)
(check-true (even? 2))

测试的目的不是覆盖率,而是确保包在官方构建环境中不会失败。

raco test .

README 与 LICENSE

README 至少应包含安装方式:

raco pkg install my-first-pkg

LICENSE 建议选择常见协议(MIT / BSD / Apache-2.0)。

发布

  1. 将代码推送到 Git 仓库
  2. 打开 https://pkgs.racket-lang.org/
  3. 选择 Add Your Own Package
  4. 填写包名与仓库地址并提交

系统会自动执行构建、测试和文档生成。

发布成功后,你的包即可通过:

raco pkg install my-first-pkg

进行安装。

版本与维护

  • 第一次发布使用 0.1.0 即可
  • 后续更新递增版本号
  • 破坏性修改再考虑主版本升级

这些属于下一阶段内容,不影响第一次发布。

第一次发布,做到这三条

第一次发布 Racket 包,不需要做到“完美工程”,但必须做到:

  • 结构正确
  • 信息完整
  • 能通过官方构建

做到这些,你发布的就不是玩具包,而是一个 正式进入 Racket 生态的官方包。

这一页读下来还顺利吗?

发现错误、没讲清楚、代码跑不起来——都欢迎告诉我们,这本书会持续修订。