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

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

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

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

这篇的目标只有一个：

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

什么样的包才算「合格」

一个可以发布到 pkgs.racket-lang.org 的包，至少需要：

一个可被 require 的模块
一个完整的 info.rkt
README 与 LICENSE
可访问的 Git 仓库
测试与文档在构建时不报错

后文的所有步骤，都是围绕这些最低要求展开的。

包的基本结构

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 决定了包能否被官方目录正确识别，没有它就无法发布。

文档：可以简单，不能没有

官方包 可以很简单，但不能没有文档。

#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）。

发布

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

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

发布成功后，你的包即可通过：

raco pkg install my-first-pkg

进行安装。

版本与维护

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

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

第一次发布，做到这三条

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

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

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