fcdev 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/CHANGELOG.md +61 -32
  2. package/README.md +17 -16
  3. package/docs/{02- → 01-}/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +14 -12
  4. package/docs/02-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +89 -0
  5. package/docs/{06- → 03-}/345/217/215/346/261/207/347/274/226.md +13 -47
  6. package/docs/{07- → 04-}/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +1 -15
  7. package/docs/nes/{01-NES/347/233/256/346/240/207.md → 01-/345/274/200/345/217/221/346/214/207/345/215/227.md} +4 -9
  8. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +25 -30
  9. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +4 -4
  10. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +5 -5
  11. package/package.json +5 -2
  12. package/src/build/bank-link-config.mjs +1 -1
  13. package/src/build/build-plan.mjs +1 -1
  14. package/src/build/program-builder.mjs +10 -5
  15. package/src/build/source-charset.mjs +111 -0
  16. package/src/cli/args-parser.mjs +1 -1
  17. package/src/cli/commands/debug-command.mjs +20 -58
  18. package/src/cli/commands/docs-command.mjs +2 -2
  19. package/src/cli/commands/run-command.mjs +36 -39
  20. package/src/cli/index.mjs +5 -5
  21. package/src/config/config-loader.mjs +2 -2
  22. package/src/disasm/disassembler.mjs +1 -1
  23. package/src/disasm/trace.mjs +4 -3
  24. package/src/docs/doc-index.mjs +1 -1
  25. package/src/docs/doc-topics.mjs +32 -38
  26. package/src/docs/index.mjs +1 -1
  27. package/src/emulator/debug-cli.mjs +48 -0
  28. package/src/emulator/emulator-launcher.mjs +107 -29
  29. package/src/emulator/emulator-locator.mjs +7 -7
  30. package/src/emulator/index.mjs +4 -3
  31. package/src/emulator/sb2000-session.mjs +104 -0
  32. package/src/targets/target-registry.mjs +9 -1
  33. package/targets/nes/lib/fcnes.lib +0 -0
  34. package/targets/nes/lib/nes-font.o +0 -0
  35. package/targets/nes/target.json +1 -1
  36. package/targets/sb2000/api-reference.md +2 -1
  37. package/targets/sb2000/examples-source.md +1330 -0
  38. package/targets/sb2000/lib/crt0.o +0 -0
  39. package/targets/sb2000/lib/sb2000.lib +0 -0
  40. package/targets/sb2000/symbols-reference.md +670 -0
  41. package/targets/sb2000/target.json +2 -1
  42. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -163
  43. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +0 -123
  44. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +0 -50
  45. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +0 -92
  46. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +0 -72
  47. package/docs/09-/345/217/221/345/270/203.md +0 -70
  48. package/docs/10-VS Code/346/211/251/345/261/225.md" +0 -131
  49. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +0 -47
  50. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +0 -10
  51. package/src/emulator/debug-client.mjs +0 -125
@@ -32,11 +32,12 @@
32
32
  },
33
33
  "extension": ".EXE",
34
34
  "nameRule": "dos-8.3",
35
+ "sourceCharset": "gb2312",
35
36
  "disk": {
36
37
  "packager": "fat-floppy"
37
38
  },
38
39
  "run": {
39
- "emulator": "virtuanes",
40
+ "emulator": "ember",
40
41
  "mode": "firmware-disk"
41
42
  }
42
43
  }
@@ -1,163 +0,0 @@
1
- # 软件架构设计
2
-
3
- fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板和反汇编前端,运行与调试用的模拟器需要自备。用 C 或 ca65 汇编开发,构建出各机型的可运行程序。首批目标是 NES 与小霸王学习机 SB2000,之后按“目标”加入步步高、裕兴等机型。
4
-
5
- 本文说明包的划分、目录、分层规则和设计决策。各部分的细节见第 9 节列出的文档。
6
-
7
- ## 1. 范围
8
-
9
- 范围内:
10
-
11
- - 命令行构建工具、目标定义、cc65 工具链包、创建包与模板、反汇编前端。
12
- - 首批目标:NES、SB2000;其他机型按 [03-目标规范](03-目标规范.md) 加入。
13
- - VS Code 扩展的智能感知与语法高亮:见 [10-VS Code扩展](10-VS%20Code扩展.md)。
14
-
15
- 范围外:
16
-
17
- - VS Code 扩展的任务、命令与调试:登记在 [待办备忘](待办备忘.md)。
18
- - BIOS 与固件的反汇编整理,BIOS 迁移到 ca65:不属于 fcdev,各机型的这类工作放在仓库的 `machines/<机型>/`(如 `machines/sb2000/`)。
19
- - 把模拟器内核集成进 VS Code 面板,以及调试适配器协议(DAP)。
20
- - 步步高、裕兴的目标定义:缺少资料,加入前先调研。
21
- - 任何机型的 BIOS、ROM 文件:不随包发布,由用户提供。
22
- - 安装脚本:不使用 `postinstall` 之类的钩子。
23
-
24
- ## 2. 设计决策
25
-
26
- | 编号 | 决策 | 原因 |
27
- | --- | --- | --- |
28
- | D01 | 用 npm 包发布命令行、目标、模板与编译器 | 项目锁定版本;终端、CI 与 Copilot 都能构建,不依赖 VS Code |
29
- | D02 | 包名:主包 `fcdev`,创建包 `create-fcdev`,工具链包 `fcdev-cc65`;三个包都不带作用域,目录名与包名相同 | `npm create fcdev` 会自动运行 `create-fcdev`;工具链包只被主包依赖,使用者不直接输入名字 |
30
- | D03 | 命令行与库用 Node 22 的 ESM(`.mjs`)加 JSDoc,运行时无依赖,不需要构建步骤 | 发布内容就是源码,便于核对 |
31
- | D04 | 用 npm workspaces 管理多个包,发布的三个包同一个版本号,同步发布;主包对工具链包写精确版本;工作区里的 `ember-debug-sdk` 是 Ember 调试服务的客户端,版本独立,不属于这三个包 | 命令行、目标与编译器必须配套 |
32
- | D05 | 一种机型是一个“目标”,是主包内 `targets/<名>/` 一个目录;新增机型只加目录,不改构建流程 | 多机型扩展 |
33
- | D06 | 目标声明可选能力:磁盘镜像、模拟器运行;没有该能力的目标,对应命令明确报错 | NES 没有磁盘,学习机有 |
34
- | D07 | 构建由 `fcdev` 自己判断增量,不用 `make` | Windows 上不必另装 `make` |
35
- | D08 | 目标运行库在发布前用 `cc65`、`ca65`、`ar65` 编译成 `.lib` 随包发布(C 与汇编源码都可以,一个函数一个目标文件) | 目标文件格式与平台无关,使用者不必再编译库 |
36
- | D09 | 工具链是体积较大的二进制,放在独立的包里,主包用 `optionalDependencies` 引用 | 不适用的环境可以跳过安装,也不拖慢主包 |
37
- | D10 | 许可证分区,见第 7 节 | 各自保留原许可证,作为独立程序互不影响 |
38
- | D11 | cc65 与模拟器的源码放在仓库根目录的 `cc65/` 与 `virtuanes/`,由本仓库维护 | 以后在本仓库里直接修改与升级,来源仍可核对 |
39
- | D12 | 反汇编不改 `da65` 的 C 代码,用前端脚本生成它的信息文件 | 只有实测发现信息文件无法表达时才改,见 [06-反汇编](06-反汇编.md) |
40
-
41
- ## 3. 包与依赖
42
-
43
- ```mermaid
44
- flowchart LR
45
- CREATE[create-fcdev] -->|生成的项目依赖| CLI[fcdev 主包]
46
- CLI --> TG[内置目标: nes、sb2000]
47
- CLI -->|optionalDependencies| TC[fcdev-cc65 工具链包]
48
- EXT[VS Code 扩展] -.->|调用命令行| CLI
49
- ```
50
-
51
- | 包 | 内容 | 是否入库 |
52
- | --- | --- | --- |
53
- | `fcdev` | 命令行、构建核心、内置目标、反汇编前端 | 是 |
54
- | `create-fcdev` | 创建项目的命令与四个模板 | 是 |
55
- | `fcdev-cc65` | cc65、ca65、ld65、ar65、da65,头文件、库与链接配置 | 只入库 `package.json`,其余由脚本生成 |
56
-
57
- - 主包不引用具体机型的代码,只读取 `targets/` 下的目标定义。
58
- - 主包找不到工具链或模拟器时,不去 `PATH` 里猜,报错并说明可选的解决办法。
59
-
60
- ## 4. 仓库目录
61
-
62
- ```text
63
- famiclone/
64
- LICENSE Apache-2.0
65
- README.md 使用说明
66
- package.json 工作区根(private)
67
- packages/
68
- fcdev/ 主包
69
- bin/fcdev.mjs
70
- docs/ 本目录的文档,随主包发布;nes/、sb2000/ 是各目标的文档
71
- src/ 见第 5 节
72
- targets/ 内置目标:nes、sb2000
73
- test/
74
- create-fcdev/ 创建包
75
- bin/ src/ templates/ test/
76
- fcdev-cc65/ 工具链包
77
- ember-debug-sdk/ Ember 调试服务的 SDK(独立包,不随 fcdev 发布,说明见它的 README)
78
- cc65/ cc65 源码(删减版,本仓库维护)
79
- virtuanes/ 模拟器源码(VirtuaNES 调试版,本仓库维护)
80
- vscode/ VS Code 扩展(独立的 npm 项目,不在工作区里),见 [10-VS Code扩展](10-VS%20Code扩展.md)
81
- tools/ 维护脚本,见第 8 节
82
- apps/ 应用程序与示例(apps/sb2000:SB-DOS 的 asm、edit、runnes、disk 与 examples 示例),不在工作区里,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 10 节
83
- test/ 仓库级测试:目录结构、cc65 工具链包、SB2000 头文件
84
- machines/ 各机型的资料与工程(不属于 fcdev 包,不随包发布),一个机型一个目录,如 machines/sb2000
85
- build/ 构建中间目录(不入库):cc65-work/ 是 cc65 的构建副本,virtuanes/ 是模拟器的编译输出
86
- ```
87
-
88
- ## 5. 主包分层
89
-
90
- `packages/fcdev/src/` 下每个目录是一层功能,目录之间只能按下表引用,并且只经对方的 `index.mjs`:
91
-
92
- | 目录 | 职责 | 允许引用 |
93
- | --- | --- | --- |
94
- | `shared` | 错误类型、文件与进程小工具 | 无 |
95
- | `api` | 目标的 C 接口文档:解析头文件文档注释、查询与格式化 | 无 |
96
- | `docs` | 开发文档的主题登记表:主题名、文件、标题、说明,以及本机路径 | `shared` |
97
- | `config` | 查找与读取 `fcdev.json` | `shared` |
98
- | `targets` | 目标注册表、程序名规则 | `shared` |
99
- | `toolchain` | 定位与调用 cc65 工具链 | `shared` |
100
- | `packagers` | 打包器:平铺映像、iNES、FAT12 软盘镜像 | `shared` |
101
- | `emulator` | 定位与启动模拟器、调试客户端 | `shared` |
102
- | `disasm` | 反汇编前端 | `shared`、`toolchain` |
103
- | `build` | 构建计划、增量、调用工具链、打包 | `shared`、`config`、`targets`、`toolchain`、`packagers` |
104
- | `cli` | 参数解析与各命令 | `shared`、`config`、`targets`、`toolchain`、`build`、`emulator`、`disasm`、`api`、`docs` |
105
-
106
- - `bin/fcdev.mjs` 只调用 `cli` 的 `runCli`。
107
- - `targets`、`toolchain`、`packagers` 之间不互相引用,由 `build` 组装。
108
- - 依赖表在 `tools/check-structure.mjs` 里登记,`npm run boundaries` 检查;新增目录要先登记,改表时同步改本节。
109
-
110
- ## 6. 错误处理
111
-
112
- - 可预期的使用错误(配置有误、找不到工具、构建失败等)一律抛 `FcdevError`,带错误码 `code` 和下一步建议 `hint`。
113
- - `runCli` 捕获 `FcdevError`,向标准错误写“错误:”加说明,再写建议,返回退出码 1;其他异常是程序自身的缺陷,不捕获,直接抛出。
114
- - 外部工具(cc65、ca65、ld65)的输出原样透传,不改写,供 VS Code 问题匹配器使用。
115
- - 启动外部程序不经过 shell,参数逐个传递,带超时(默认 120 秒)。
116
-
117
- ## 7. 许可证分区
118
-
119
- | 部分 | 许可证 |
120
- | --- | --- |
121
- | 仓库与 `fcdev`、`create-fcdev` 自己的代码 | Apache-2.0,见根目录 `LICENSE` |
122
- | `cc65/` 及工具链包 | zlib,见 `cc65/LICENSE` |
123
- | `virtuanes/` | GPL-3.0-only,见 `virtuanes/LICENSE` |
124
-
125
- 模拟器源码里只有 `interp.h`、`nx_hq2x.h`、`nx_Scale2x.h` 三个文件头写“版本 2 或以后”,合并后按 GPLv3 发布。两个包都是独立程序,许可证互不影响。
126
-
127
- ## 8. 维护脚本
128
-
129
- | 脚本 | 作用 |
130
- | --- | --- |
131
- | `tools/build-cc65.mjs` | 构建 cc65 工具与运行库,组装 `fcdev-cc65`,见 [04-cc65工具链](04-cc65工具链.md) |
132
- | `tools/build-libs.mjs` | 按各目标的 `lib-build.json` 用 `cc65`、`ca65`、`ar65` 编出 `lib/` 下的运行库(`.c` 与 `.s` 源码,目录项递归展开);`fcdev` 的 `prepack` 与 `npm test` 前自动运行 |
133
- | `tools/gen-sb2000-header.mjs` | 由 `sb2000.inc` 生成 `sb2000-symbols.h` |
134
- | `tools/check-sb2000-api.mjs` | 检查 SB2000 的 C 接口:函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 6 节 |
135
- | `tools/gen-sb2000-api-doc.mjs` | 由头文件文档注释生成 `targets/sb2000/api-reference.md` |
136
- | `tools/check-structure.mjs` | 检查主包各层的依赖方向(`npm run boundaries`) |
137
- | `tools/release-check.mjs` | 发布前检查(`npm run release:check`),见 [09-发布](09-发布.md) |
138
- | `tools/verify-install.mjs` | 打包后在临时目录里创建、安装并构建四个模板(`npm run release:verify`) |
139
- | `tools/release.mjs` | 发布脚本:升版本号、检查、试发布与按顺序发布(`npm run release:prepare`、`npm run release:publish`),见 [09-发布](09-发布.md) 第 6 节 |
140
-
141
- ## 9. 文档清单
142
-
143
- 文档放在主包的 `docs/` 目录,在这里维护,随 `fcdev` 包一起发布:安装后在 `node_modules/fcdev/docs/`。`npx fcdev docs` 列出全部主题并给出本机路径,主题登记在 `src/docs/doc-topics.mjs`;新增、改名或删除文档时同步改登记,测试会核对登记与目录一致。文档里指向主包内文件的链接用相对路径,指向仓库其他目录(`tools/`、`virtuanes/`、`vscode/` 等,不随包发布)的文件只写路径,不做链接。`api` 主题是例外:它指向目标目录里由头文件文档注释生成的接口参考,不放进 `docs/`,避免两份不一致。
144
-
145
- | 主题 | 文档 | 内容 |
146
- | --- | --- | --- |
147
- | `architecture` | 01-软件架构设计 | 本文 |
148
- | `build` | [02-命令行与构建](02-命令行与构建.md) | 命令、构建规则、配置文件、构建流程 |
149
- | `targets` | [03-目标规范](03-目标规范.md) | 目标定义、打包器、新增机型的步骤 |
150
- | `toolchain` | [04-cc65工具链](04-cc65工具链.md) | cc65 源码、构建与工具链包 |
151
- | `emulator` | [05-模拟器与调试](05-模拟器与调试.md) | 运行方案、模拟器定位、调试服务与命令表 |
152
- | `disasm` | [06-反汇编](06-反汇编.md) | 反汇编前端的流程与限制 |
153
- | `create` | [07-创建包与模板](07-创建包与模板.md) | 创建命令、模板与生成内容 |
154
- | `testing` | [08-测试与验证](08-测试与验证.md) | 测试分层、环境变量与运行方法 |
155
- | `release` | [09-发布](09-发布.md) | 发布顺序、前提与检查 |
156
- | `vscode` | [10-VS Code扩展](10-VS%20Code扩展.md) | 扩展的智能感知、语法高亮、项目信息来源、目录分层与打包 |
157
- | `nes` | [nes/01-NES目标](nes/01-NES目标.md) | NES 目标的构建与接口 |
158
- | `sb2000` | [sb2000/01-开发指南](sb2000/01-开发指南.md) | SB2000 目标的程序格式、内存布局、运行库、常用做法与示例 |
159
- | `syscall` | [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) | SB-DOS 的系统调用:参数、结果、出错码与可靠程度 |
160
- | `hardware` | [sb2000/03-硬件说明](sb2000/03-硬件说明.md) | SB2000 的硬件行为 |
161
- | `api` | [api-reference](../targets/sb2000/api-reference.md) | SB2000 运行库全部函数的接口参考(由头文件文档注释生成,查询用 `npx fcdev api`) |
162
- | `todo` | [待办备忘](待办备忘.md) | 已确定以后再做的事项 |
163
- | `bugs` | [缺陷记录](缺陷记录.md) | 发现的缺陷及修复情况 |
@@ -1,123 +0,0 @@
1
- # 目标规范
2
-
3
- 一个“目标”对应一种机型。目标是主包里 `packages/fcdev/targets/<名>/` 下的一个目录,由 `target.json` 描述;新增机型只加目录,不改 `build` 的流程。本文说明目标的目录、`target.json` 的字段、打包器和新增机型的步骤。已有目标的文档在 [nes/](nes/01-NES目标.md) 与 [sb2000/](sb2000/01-开发指南.md) 下。
4
-
5
- ## 1. 目标目录
6
-
7
- ```text
8
- targets/<名>/
9
- target.json 目标定义
10
- include/ C 头文件
11
- asminc/ 汇编引入文件
12
- src/ 目标自己的运行库与启动代码源码
13
- lib-build.json 运行库的构建清单(没有要编译的库时可省略)
14
- lib/ 运行库的编译结果(构建生成,不入库)
15
- link.cfg 等 目标自带的链接配置(也可以直接用工具链 cfg 里的)
16
- link-banked.cfg 等 多页(换页)程序的链接配置模板,见第 2.3 节
17
- ```
18
-
19
- 目录名必须与 `target.json` 里的 `name` 一致;目标名只能用小写字母、数字和连字符。
20
-
21
- ## 2. `target.json`
22
-
23
- | 字段 | 必填 | 说明 |
24
- | --- | --- | --- |
25
- | `name`、`title` | 是 | 标识与显示名 |
26
- | `cpu` | 是 | CPU 型号,传给 `cc65` 与 `ca65`;首批目标都是 `6502` |
27
- | `cc65Target` | 是 | 传给 `cc65`、`ca65` 的目标名(`-t`),如 `none`、`nes` |
28
- | `linkConfig` | 是 | 链接配置,路径值 |
29
- | `packager` | 是 | 程序打包器名,见第 3 节 |
30
- | `extension` | 是 | 产物扩展名,含点,如 `.nes` |
31
- | `startup` | 否 | 启动代码目标文件列表,路径值;空表示用 `cc65` 目标库自带的 |
32
- | `forceImports` | 否 | 链接时用 `-u` 强制引入的符号;用于让库里的启动代码一定被链接,纯汇编程序也不例外 |
33
- | `libraries` | 否 | 链接的库,按顺序,路径值 |
34
- | `include`、`asminclude` | 否 | 头文件与汇编引入目录,路径值 |
35
- | `defines` | 否 | 预定义宏,值为字符串或数字 |
36
- | `packagerOptions` | 否 | 传给打包器的选项 |
37
- | `nameRule` | 否 | 程序名规则;空表示不限制 |
38
- | `disk` | 否 | 磁盘镜像能力,含 `packager`(磁盘打包器名) |
39
- | `run` | 否 | 运行方案,含 `emulator` 与 `mode` |
40
- | `options` | 否 | 目标专用选项,见第 4 节 |
41
- | `banked` | 否 | 多页(换页)程序的定义,见第 2.3 节 |
42
-
43
- 路径值有两种写法:
44
-
45
- - 相对目标目录,如 `lib/crt0.o`。
46
- - 以 `toolchain:` 开头,表示相对工具链根目录,如 `toolchain:cfg/nes.cfg`。
47
-
48
- 缺少必填字段、字段类型不对时,报 `TARGET_INVALID`。
49
-
50
- ### 2.1 程序名规则
51
-
52
- `nameRule` 目前只有 `dos-8.3`:主名为 1 到 8 个字母、数字、下划线或连字符,产物名转为大写;不符合时报错,不截断。写了未登记的规则也报错。规则在 `targets/name-rules.mjs` 登记。
53
-
54
- ### 2.2 运行方案
55
-
56
- `run.mode` 取值:
57
-
58
- | 值 | 含义 |
59
- | --- | --- |
60
- | `rom` | 模拟器直接加载产物 |
61
- | `firmware-disk` | 加载 `fcdev.json` 里 `firmware` 指定的固件,挂载磁盘镜像后复位 |
62
-
63
- `run.emulator` 必须是字符串,标识要用的模拟器;目前只有 `virtuanes`,主包总是按 `virtuanes` 的调试服务控制模拟器(模拟器程序由配置项 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定),该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。`firmware-disk` 需要目标同时声明 `disk`,否则运行时报“不支持磁盘镜像”。
64
-
65
- ### 2.3 多页(换页)程序
66
-
67
- 目标的程序可以超过一个窗口时,用 `banked` 说明怎么生成链接配置。程序按“库页”换页,库页个数由 `options` 里的一个数字选项决定。`banked` 的字段:
68
-
69
- | 字段 | 说明 |
70
- | --- | --- |
71
- | `option` | 数字选项名,值是库页个数;值为 0 时不用多页,按 `linkConfig` 链接,打包器选项不变 |
72
- | `linkConfig` | 多页链接配置的模板,路径值;模板里单独一行的 `%BANK_MEMORY%` 与 `%BANK_SEGMENTS%` 由 fcdev 展开,缺少时报 `TARGET_INVALID` |
73
- | `generatedFrom` | 模板里已经写出这一页之前的库页,从这一页起按个数生成 |
74
- | `maxBanks` | 库页个数的上限;选项值超过上限、不是整数或小于 0 时报 `TARGET_OPTION_INVALID` |
75
- | `memory`、`segment` | 一个库页的内存区行与段行,`{n}` 换成库页号 |
76
-
77
- 选项值大于 0 时,fcdev 把模板展开成 `<中间文件目录>/<程序名>.cfg` 交给 `ld65`,并去掉打包器选项里的 `maxSize`(大小由库页个数决定)。`ld65` 报某个库页的段没有内存区时,提示加大库页个数。`option` 必须是 `options` 里的数字选项,`generatedFrom` 与 `maxBanks` 是不小于 1 的整数,否则报 `TARGET_INVALID`。目前只有 `sb2000` 声明了 `banked`,用法见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 3.1 节。
78
-
79
- ## 3. 打包器
80
-
81
- 链接得到 `.bin`,再由打包器做成最终产物。打包器在 `packagers/index.mjs` 登记。
82
-
83
- | 打包器 | 类别 | 作用 | 选项 |
84
- | --- | --- | --- | --- |
85
- | `flat-exe` | 程序 | 平铺映像:校验文件头与大小,写成产物文件 | `header`:十六进制字符串,`??` 表示任意字节;`maxSize`:映像大小上限,字节 |
86
- | `ines` | 程序 | 校验 iNES 头与文件长度,写成 `.nes` | 无 |
87
- | `fat-floppy` | 磁盘 | 把一组文件放进 1.44MB 的 FAT12 软盘镜像根目录 | `label`:卷标 |
88
-
89
- - 程序打包器接收 `{ binaryFile, outputFile, options }`,返回 `{ outputFile, size }`。
90
- - 磁盘打包器接收 `{ files, outputFile, options }`,输入是一组 `{ name, data, mtime }`,输出一个镜像文件。
91
- - `fat-floppy` 的几何参数是 512 字节扇区、2 面、80 磁道、每磁道 18 扇区,共 2880 个扇区,与模拟器的软驱控制器一致;文件只写在根目录,每簇 1 个扇区,文件名必须符合 8.3,不支持子目录;引导扇区只有 BIOS 参数块与签名,没有启动代码,镜像只用作数据盘。
92
-
93
- ## 4. 目标专用选项
94
-
95
- `options` 里每一项是一个选项,字段:
96
-
97
- | 字段 | 说明 |
98
- | --- | --- |
99
- | `type` | `boolean`、`string` 或 `number` |
100
- | `default` | 默认值,类型必须与 `type` 一致 |
101
- | `links` | 只用于布尔选项:值为 `true` 时额外链接的目标文件,路径值 |
102
-
103
- 用户在 `fcdev.json` 的 `targetOptions` 里设置;没有定义的选项或类型不对时报错。额外链接的目标文件排在用户目标文件之后、库之前。
104
-
105
- ## 5. 运行库的构建
106
-
107
- 目标自带的运行库与启动代码用 C 或汇编写,发布前编译好随包发布。`lib-build.json` 的字段:
108
-
109
- | 字段 | 说明 |
110
- | --- | --- |
111
- | `libraries` | 库路径到源文件列表;每个源文件编成一个 `.o`(`.c` 先用 `cc65` 编成汇编,再汇编),用 `ar65 a` 合成库,再删除临时 `.o`;列表里以 `/` 结尾的项是目录,递归收录其中全部 `.c` 与 `.s`;同名文件报错 |
112
- | `objects` | 目标文件路径到源文件,直接汇编成 `.o` |
113
- | `binIncludeDirs` | `.incbin` 的搜索目录,相对目标目录 |
114
-
115
- 汇编时固定给 `-I <目标>/asminc`,`-t` 与 `--cpu` 取目标的定义;`.c` 用 `cc65 -t <cc65Target> --cpu <cpu> -Oirs`,头文件目录取目标的 `include`,并带上目标的 `defines`。一个函数一个源文件,库里就是一个函数一个目标文件,链接时只带入程序用到的函数。命令 `node tools/build-libs.mjs [目标名…]` 编译;不带参数时编译全部目标。`fcdev` 的 `prepack` 与根目录 `npm test` 的 `pretest` 都会自动运行它。
116
-
117
- ## 6. 新增机型的步骤
118
-
119
- 1. 在 `packages/fcdev/targets/` 下新建目录,写 `target.json`、链接配置、启动代码、头文件与运行库源码。头文件里的函数用 `/** */` 文档注释(说明、`@param`、`@return`),`fcdev api` 直接读它们作为接口文档,见 [02-命令行与构建](02-命令行与构建.md) 第 5.1 节。动手前先用资料与模拟器确认程序格式、内存布局、系统调用与固件要求,不凭猜测实现。
120
- 2. 需要新的打包器或程序名规则时,在 `packagers/index.mjs` 或 `targets/name-rules.mjs` 登记。
121
- 3. 有运行库要编译时写 `lib-build.json`,运行 `node tools/build-libs.mjs <目标名>`。
122
- 4. 在 `create-fcdev` 里加 C 与汇编两个模板,见 [07-创建包与模板](07-创建包与模板.md)。
123
- 5. 补测试,见 [08-测试与验证](08-测试与验证.md),并在主包的 `docs/<目标名>/` 下新增该目标的说明文档,更新 [01-软件架构设计](01-软件架构设计.md) 的文档清单与 `src/docs/doc-topics.mjs` 的主题登记。
@@ -1,50 +0,0 @@
1
- # cc65 工具链
2
-
3
- `fcdev` 用 cc65 编译与链接,不使用使用者机器上自带的 cc65。cc65 的源码在本仓库的 `cc65/` 目录,由本仓库维护;构建脚本把它编成工具与运行库,组装成工具链包 `fcdev-cc65` 随 npm 发布。工具链怎么被主包找到,见 [02-命令行与构建](02-命令行与构建.md) 第 4.4 节。
4
-
5
- ## 1. 源码目录 `cc65/`
6
-
7
- - 最初导入自上游 [cc65/cc65](https://github.com/cc65/cc65) 的提交 `357f64e4e3c733d54b82bc155afc841fd8d9ee8d`(2025-08-24)。导入后由本仓库维护,可以直接修改。
8
- - 是删减版,只保留 `fcdev` 构建 `cc65`、`ca65`、`ld65`、`ar65`、`da65`,以及 `none`、`nes` 两个目标的运行库所需的文件。`cc65/README-FCDEV.txt` 写明“本目录为删减版”并给出导入的提交,这是 zlib 许可证对修改版的要求。
9
- - 许可证为 zlib,见 `cc65/LICENSE`。
10
-
11
- 保留的内容:
12
-
13
- | 位置 | 内容 |
14
- | --- | --- |
15
- | `src/` | `cc65`、`ca65`、`ld65`、`ar65`、`da65` 与共用的 `common` |
16
- | `libsrc/` | `common`、`runtime`、`none`、`nes`,以及它们的公共部分依赖的 `conio`、`dbg`、`em`、`joystick`、`mouse`、`serial`、`tgi`、`zlib` |
17
- | `include/`、`asminc/` | 头文件与汇编引入文件 |
18
- | `cfg/` | `none.cfg`、`nes.cfg`、`module.cfg` |
19
- | 各级 `Makefile`、`LICENSE` | 构建与许可 |
20
-
21
- 已删除:`test/`、`targettest/`、`doc/`、`samples/`、`util/`、持续集成与贡献说明文件、其他机型的库与头文件,以及 `co65`、`od65`、`sp65`、`grc65`、`chrcvt65`、`cl65`、`sim65`、`dbginfo` 等不用的工具。删减后必须仍能编出 `none.lib` 与 `nes.lib`;缺什么就从上游补回。
22
-
23
- ## 2. 构建
24
-
25
- ```bash
26
- node tools/build-cc65.mjs
27
- ```
28
-
29
- `tools/build-cc65.mjs` 做的事:
30
-
31
- 1. 把 `cc65/` 整个复制到 `build/cc65-work`,在副本里构建,不污染源码目录。
32
- 2. 在 `src` 里构建 `ar65`、`ca65`、`cc65`、`da65`、`ld65`,版本串显式传 `BUILD_ID=Git <提交前 7 位>`;不传时 `Makefile` 会取当前目录所在仓库(也就是 `fcdev`)的提交号,版本输出会指向错误的提交。
33
- 3. 在 `libsrc` 里构建 `none` 与 `nes` 两个运行库。
34
- 4. 组装工具链包:`bin/` 放五个可执行文件,另有 `include/`、`asminc/`、`cfg/`、`lib/none.lib`、`lib/nes.lib`、`LICENSE`。
35
- 5. 写 `manifest.json`(上游地址、提交、各文件的 SHA-256)与 `package.json`(版本与主包同步)。
36
-
37
- 用 `mingw32-make` 与 `gcc` 构建,环境变量 `FCDEV_MAKE` 可指定 make 程序。上游提交号常量 `CC65_COMMIT` 写在构建脚本里。
38
-
39
- ## 3. 工具链包
40
-
41
- - 包名 `fcdev-cc65`(与目录名相同),主包把它列为 `optionalDependencies`,版本精确一致。
42
- - 入库的只有 `package.json`;`bin/`、`include/`、`asminc/`、`lib/`、`cfg/`、`LICENSE`、`manifest.json` 都是生成物,由 `.gitignore` 排除。
43
- - 主包找不到工具链包时,提示可用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。
44
- - `npm run release:check` 校验工具链包里的文件与清单一致,且没有清单之外的文件;源码目录里的路径和清单由 `test/cc65-tools.test.mjs` 检查,见 [08-测试与验证](08-测试与验证.md)。
45
-
46
- ## 4. 升级与修改
47
-
48
- - 修改 `cc65/` 里的源码后,重新运行 `node tools/build-cc65.mjs`,再运行 `npm test`。
49
- - 要换到上游的新提交时:从上游取回上面“保留的内容”对应的文件,更新 `tools/build-cc65.mjs` 里的 `CC65_COMMIT` 和 `cc65/README-FCDEV.txt` 里的提交号,重新构建并运行全部测试。
50
- - 统一换行符的脚本不要扫描 `cc65/`:里面有 Latin-1 和 Shift-JIS 编码的文件,按 UTF-8 读写会损坏。`virtuanes/` 也一样。
@@ -1,92 +0,0 @@
1
- # 模拟器与调试
2
-
3
- `fcdev` 的 `run`、`debug` 命令经调试服务控制模拟器。模拟器不随 npm 包提供,需要自备,并且要支持第 5 节的调试服务。本仓库的 `virtuanes/` 是实现了这套服务的 VirtuaNES 调试版源码,能运行 NES 游戏,以及 SB2000 等学习机的固件与程序,由本仓库维护。模拟器的改动清单见 `virtuanes/README.md`,调试服务的命令表见第 5.1 节。
4
-
5
- ## 1. 模拟器的获得
6
-
7
- - `virtuanes/` 基于 Win32 与 DirectX,许可证 GPL-3.0-only,是 32 位程序,运行需要 32 位的 VC++ 运行库。
8
- - 编译需要 Visual Studio(含“使用 C++ 的桌面开发”),运行 `virtuanes/build.ps1 -Configuration Release`,输出在仓库根目录的 `build/virtuanes/Release/bin/VirtuaNES.exe`。编译前只结束调试实例(调试服务监听 `127.0.0.1` 端口的 `VirtuaNES.exe`);用户自己打开的模拟器不会被结束,它们占用输出文件时编译报错,需先自行关闭。
9
- - 模拟器运行时会在程序所在目录里写 `VirtuaNES.ini` 与 `save/`。
10
-
11
- ## 2. 定位模拟器
12
-
13
- 按顺序查找,找到即停:
14
-
15
- 1. 配置项 `emulator`。
16
- 2. 环境变量 `FCDEV_EMULATOR`。
17
-
18
- 都没有设置时报“找不到模拟器”,指定的路径不存在时报“找不到模拟器:路径”。模拟器需要支持同样的调试服务才能用调试命令。
19
-
20
- ## 3. `fcdev run`
21
-
22
- 先构建,再按目标的运行方案启动模拟器。目标没有运行方案时报错。
23
-
24
- | 运行方案 | 做法 |
25
- | --- | --- |
26
- | `rom` | 模拟器直接加载产物,不需要固件;没有 `--debug` 时启动后立即返回 |
27
- | `firmware-disk` | 要求 `fcdev.json` 配置 `firmware`;构建并生成磁盘镜像,以调试模式启动模拟器,依次发 `disk <镜像>`、`reset`、`live`;等 DOS 启动后在提示符下输入程序名 |
28
-
29
- - `--debug` 时不发 `live`,模拟器停在调试服务,只在收到 `run` 命令时运行;`firmware-disk` 方案总是以调试模式启动,因为要用调试服务挂载镜像。
30
- - `--port` 指定调试端口,默认 5699。
31
- - 调试模式启动前先检查端口是否被占用,被占用就报错,不去连接,避免连到别的模拟器;启动后最多等 30 秒,等到调试服务回应 `running=1`,超时则结束模拟器进程并报错。
32
- - 模拟器进程与命令行脱离,命令行退出后窗口保持打开,工作目录是模拟器所在目录(语言包按相对文件名加载)。
33
- - 非调试模式下沿用模拟器的单实例规则:已有普通模拟器窗口时,会把程序交给它打开。
34
-
35
- ## 4. `fcdev debug`
36
-
37
- ```bash
38
- npx fcdev debug run 60
39
- npx fcdev debug shot screen.png
40
- ```
41
-
42
- - 把命令原样转发给调试服务,打印应答;应答首行以 `OK` 开头时退出码为 0,否则为 1。
43
- - 端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
44
- - 模拟器的工作目录与终端不同,所以命令里的相对路径先换成绝对路径:`shot`、`disk`、`trace`、`io`、`disklog`、`calllog`、`savestate`、`loadstate` 的第一个参数,以及 `cdl save` 的前缀、`tape play`、`tape rec` 的文件;`off` 不处理;`disk` 的路径可含空格,取剩余全部。
45
- - `run`、`step` 的应答超时是 10 分钟,其余命令 30 秒。
46
-
47
- ## 5. 调试服务协议
48
-
49
- - 模拟器只在设置了环境变量 `FCDEV_DEBUG_PORT` 时启动调试服务,只监听 `127.0.0.1`。
50
- - 一行一个命令;应答若干行文本,以单独的 `.` 行结束;应答首行以 `OK` 或 `ERR` 开头。一次只处理一条命令。
51
- - 客户端在 [src/emulator/debug-client.mjs](../src/emulator/debug-client.mjs):`DebugClient.connect` 连接(5 秒超时),`send` 发命令并等应答。
52
- - `fcdev` 只经这套协议与模拟器通信,协议保持稳定;以后把内核集成进 VS Code 时,只要协议不变,`fcdev` 不用改。
53
- - 命令表见下面的第 5.1 节。`live` 命令由 `fcdev` 新增:把模拟器切换为自由运行,供 `fcdev run` 把窗口交给用户操作。
54
-
55
- ### 5.1 命令表
56
-
57
- 直接发给服务的路径必须是绝对路径;数字默认按十六进制解析(地址、扫描码、寄存器),帧数、长度、次数按十进制。
58
-
59
- | 命令 | 说明 |
60
- | --- | --- |
61
- | `status` | 运行状态、寄存器与 bank 寄存器 |
62
- | `run <帧数>` | 运行指定帧数,遇到断点提前停止 |
63
- | `step <条数>` | 单步指定条数的指令 |
64
- | `bp x\|r\|w <地址> [结束地址]` | 添加执行、读、写断点;`bp list`、`bp del <编号\|all>` |
65
- | `regs [pc=.. a=.. x=.. y=.. s=.. p=..]` | 读取或修改寄存器 |
66
- | `read <空间> <地址> <长度>` | 读内存;空间为 `cpu`、`rom`、`pram`、`vram`、`cram`、`eram`、`wram`、`ram` |
67
- | `write <空间> <地址> <十六进制字节>` | 写内存 |
68
- | `resolve <地址>` | 把 CPU 地址解析为物理空间与偏移 |
69
- | `key <扫描码> <0\|1>`、`key clear` | 按下或松开键盘键(DirectInput 扫描码) |
70
- | `mouse move <dx> <dy>`、`mouse btn <掩码>` | 鼠标移动与按键 |
71
- | `shot <文件.png>` | 截图 |
72
- | `trace <文件> [最大行数] [unique]`、`trace off` | 记录每条指令与中断;加 `unique` 时每个 CPU 地址的指令、每个中断入口只记第一次,最大行数按实际写出的行数算(适合长时间运行后给 `fcdev disasm --trace` 用;只按 CPU 地址去重,换页后同一地址的其他代码会漏记) |
73
- | `io <文件> [最大行数] [w]`、`io off` | 记录 `$2000-$4FFF` 的读写;加 `w` 只记录写 |
74
- | `pad <0-3> <十六进制掩码>`、`pad <0-3> clear` | 注入手柄按键(A=01、B=02、Select=04、Start=08、上=10、下=20、左=40、右=80),与真实输入合并 |
75
- | `disklog <文件> [最大行数]`、`disklog off` | 记录软驱控制器读写的 LBA |
76
- | `calllog <文件> <pc> <地址:长度[,...]> [最大次数] [skip=地址=值[,...]]`、`calllog off` | 每次执行到 `pc` 就记录寄存器、栈顶与内存段;`skip` 表示该地址字节等于值(十六进制)时不记录;可添加多条,`off` 全部关闭 |
77
- | `cdl on\|off\|clear\|save <前缀>` | 代码数据标记,保存为 `<前缀>-rom.cdl`、`<前缀>-pram.cdl` |
78
- | `dialogs [clear]` | 列出调试期间被自动关闭的对话框(标题、文字、按下的按钮),`clear` 同时清空记录。调试服务启动后,模拟器自己弹出的消息框、文件框会被自动按下“确定”“取消”“否”“忽略”“关闭”中第一个存在的按钮,不会停在模态对话框上;文件对话框(打开、另存为,如虚拟打印机输出 PNG 时的“Save to...”)直接按“取消”,因为没有文件名时“确定”不起作用 |
79
- | `tape play <文件>`、`tape rec <文件>`、`tape stop`、`tape status` | 数据录音机(`.vtp`)的播放与录制;`rec` 的文件在 `stop` 后才完整(命令已实现,还没有用实际程序验证) |
80
- | `disk <镜像>`、`savedisk` | 挂载或保存软盘镜像 |
81
- | `fdc eject\|insert\|wp <0\|1>\|noindex <0\|1>\|seekfail <0\|1>\|dead <0\|1>\|bad <逻辑扇区...>\|clear\|status` | 软驱故障注入。`eject`、`insert` 取出、放回盘片(取出后控制器对 READ ID 报找不到地址标志);`wp` 写保护;`noindex` 没有索引脉冲(READ ID、读写、格式化命令一直不结束);`seekfail` 磁头卡住(SEEK、RECALIBRATE 不移动,已在 0 磁道时回 0 磁道仍成功);`dead` 控制器收到命令字节后不再处理;`bad` 指定的逻辑扇区(十进制)读时报数据校验错,写不受影响;`clear` 关闭全部故障、放回盘片并取消写保护;`status` 显示当前状态。`disk` 挂载新镜像时也会清掉全部故障 |
82
- | `audio fast\|real` | 声音播放速度:`fast` 时语音与 DAC(开机音乐、WAV)不再等声卡按真实时间播放,采样直接丢弃,模拟器内部时序不变;`real` 为默认的真实时间。开关是全局状态,复位后保持;验证工具只在开机阶段打开,开机完成后恢复 |
83
- | `reset`、`softreset`、`savestate <文件>`、`loadstate <文件>` | `reset` 是硬复位(回到 BIOS),`softreset` 只复位 CPU、手柄与 APU、保留映射器状态(游戏中的软复位);另有状态存取 |
84
- | `live` | 切换为自由运行:模拟器按正常速度连续运行,不再由 `run` 授权帧数;此后只建议使用 `key`、`pad`、`mouse`、`shot`、`quit`,读写内存与断点类命令与模拟线程并行,结果不可靠。`fcdev run` 用它把窗口交给用户操作 |
85
- | `quit` | 关闭模拟器 |
86
-
87
- ## 6. 对 `virtuanes/` 的约定
88
-
89
- - 改动处按文件头约定标明,改动清单写在 `virtuanes/README.md` 的“相对上游的改动”。
90
- - 调试模式(设置了 `FCDEV_DEBUG_PORT`)下,`WinMain.cpp` 不把命令行转交给已运行的实例,调试模式的模拟器可以与用户平时用的普通实例同时运行。
91
- - `WinMain.cpp` 含 Shift-JIS 编码的内容,不要用编辑工具整体改写。
92
- - 不随包发布任何 BIOS 或 ROM,由用户经 `firmware` 提供。
@@ -1,72 +0,0 @@
1
- # 测试与验证
2
-
3
- 本文说明测试的分层、运行方法和用到的环境变量。测试用 Node 内置的 `node:test`,不引入测试框架。
4
-
5
- ## 1. 运行
6
-
7
- | 命令 | 作用 |
8
- | --- | --- |
9
- | `npm test` | 运行全部测试;运行前自动执行 `npm run build:libs` 编译各目标的运行库 |
10
- | `npm run boundaries` | 检查主包的分层依赖,见 [01-软件架构设计](01-软件架构设计.md) 第 5 节 |
11
- | `npm run check` | 依赖边界检查加测试 |
12
- | `npm run release:check` | 发布前检查,见 [09-发布](09-发布.md) |
13
- | `npm run release:verify` | 打包后在临时目录里创建、安装并构建四个模板 |
14
-
15
- 测试文件在 `packages/fcdev/test/`、`packages/create-fcdev/test/` 与仓库根的 `test/`,文件名以 `.test.mjs` 结尾。
16
-
17
- VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;在 `vscode/` 目录运行 `npm run check`,见 [10-VS Code扩展](10-VS%20Code扩展.md) 第 5 节。
18
-
19
- 找不到 cc65 工具链时,需要真实工具的用例会跳过,并在跳过说明里写明原因;纯逻辑的用例不受影响。
20
-
21
- ## 2. 环境变量
22
-
23
- | 变量 | 作用 |
24
- | --- | --- |
25
- | `FCDEV_CC65_HOME` | 指向自备的 cc65 目录;没有工具链包时用它跑集成测试 |
26
- | `FCDEV_EMULATOR` | 指向自备的模拟器 |
27
- | `FCDEV_TEST_FIRMWARE` | 指向 SB2000 的 BIOS 文件(仓库里有一份:`machines/sb2000/reference/rom/SB2K_BIOS.NES`);设置后额外运行“SB2000 程序在模拟器里运行”的用例 |
28
- | `FCDEV_TEST_NES_ROM` | 指向一个 NROM 的 `.nes` 文件;设置后额外对它做完整反汇编与回读 |
29
- | `FCDEV_SKIP_GUI_TESTS` | 设为 `1` 时跳过会打开模拟器窗口的用例 |
30
-
31
- ## 3. 测试分层
32
-
33
- | 层次 | 文件 | 内容 |
34
- | --- | --- | --- |
35
- | 单元测试 | `args-parser`、`config`、`build-helpers`、`targets-packagers`、`fat12-image` | 参数解析、配置查找与未知项报错、源文件收集、依赖文件解析、工具参数、目标字段校验、程序名规则、各打包器、FAT12 镜像 |
36
- | 命令行与构建 | `cli`、`build`、`toolchain` | 帮助、版本、错误输出与退出码、`build`、`info`、`sync`;构建计划的路径规则;增量与错误提示;工具链定位的优先级与不完整报错 |
37
- | 目标 | `sb2000`(主包) | 构建 C 与汇编程序,文件头、大小与内存布局,运行库一个函数一个目标文件、链接只带用到的函数,多页程序的文件页序、库页不够与超过上限的提示,`disk` 命令,缺少固件的提示 |
38
- | 模拟器 | `emulator`、`sb2000`、`sb2000-library` | 调试客户端的应答解析与超时、模拟器定位、端口检查、`debug` 命令的路径换算;真实模拟器里运行 NES 程序并截图;设置固件后运行 SB2000 程序,以及运行库每个模块的测试程序(约 15 个用例,共数百项检查,文件与磁盘类用例把镜像读回核对;换页的用例覆盖 9 个库页与上限 113 个库页),见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节 |
39
- | 反汇编 | `disasm` | 映像读取、CDL 与轨迹解析、静态追踪、信息文件、回读校验;对 `fcdev` 自己构建的 NES 与 SB2000 程序做完整反汇编;设置 `FCDEV_TEST_NES_ROM` 时对真实游戏做反汇编 |
40
- | 创建包 | `create`(`create-fcdev`) | 参数解析、模板列表、项目生成、目录检查、交互选择、安装流程;四个模板都能用 `fcdev` 构建 |
41
- | 接口文档 | `api-command`(主包)、`sb2000-api`(仓库) | `fcdev api` 命令的各种查询与错误提示、头文件文档注释的解析、系统调用标签的匹配;SB2000 接口检查(函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因);入库的 `api-reference.md` 与头文件生成的结果一致 |
42
- | 仓库 | `cc65-tools`、`sb2000-header`、`structure` | `cc65/` 里的必要路径与工具链包的校验值;入库的 `sb2000-symbols.h` 与生成结果一致;分层检查对违规的识别 |
43
- | 文档 | `docs-command`(主包) | `fcdev docs` 命令的列表、按主题名、文件名与关键词查询、`--json`、错误提示;文档主题登记与 `docs/` 目录里的文件一一对应(包内其他位置的登记项文件必须存在),主题名合法且不重复,架构文档的文档清单列全了每个主题 |
44
-
45
- 集成测试用真实的 cc65 构建四个模板,检查产物头部与大小。
46
-
47
- ## 4. 模拟器验证
48
-
49
- - NES hello 与 SB2000 的 C、汇编 hello 在模拟器里运行,用调试服务的 `shot` 命令截图,核对屏幕文字:NES 显示 `HELLO, NES!`,SB2000 显示 `Hello, SB2000!` 与“你好,小霸王!”并能返回 DOS。
50
- - SB2000 的程序运行环境验证(V01 到 V10)的结论见 [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) 第 9 节。
51
- - 运行库测试程序的停靠点用写断点实现(对全局变量 `sb_test_stop` 设断点),不对函数入口设执行断点,原因见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节。
52
- - 用调试服务验证时一律显式指定端口,避免连到别的模拟器;只结束本仓库启动的模拟器进程。
53
-
54
- ## 5. 反汇编验证
55
-
56
- `fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥)回读后都与原文件逐字节一致,详见 [06-反汇编](06-反汇编.md) 第 6 节。
57
-
58
- ## 6. 安装验证
59
-
60
- `npm run release:verify`(`tools/verify-install.mjs`):
61
-
62
- 1. 把三个包用 `npm pack` 打成 `.tgz`。
63
- 2. 在临时目录里从本地 `.tgz` 安装 `create-fcdev`,不访问 npm 仓库,也不执行 `npm publish`。
64
- 3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev` 与工具链包,运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
65
- 4. 结束后删除临时目录;加 `--keep` 可保留,便于查看。
66
-
67
- 只验证构建,不启动模拟器。
68
-
69
- ## 7. 注意事项
70
-
71
- - 带真实模拟器的用例运行后会在模拟器所在目录里生成 `VirtuaNES.ini` 与 `save/`,不用删。
72
- - 没有目测的界面输出,汇报时写明。
@@ -1,70 +0,0 @@
1
- # 发布
2
-
3
- 本文说明三个 npm 包的发布顺序、前提、检查和元数据。npm 的登录与 `npm publish` 由用户执行,不在代码或文档里记录任何凭据。
4
-
5
- ## 1. 包与版本
6
-
7
- | 包 | 说明 |
8
- | --- | --- |
9
- | `fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
10
- | `fcdev` | 主包,对工具链包写精确版本的 `optionalDependencies` |
11
- | `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
12
-
13
- - 三个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包的依赖版本必须与之相同。工作区里的 `packages/ember-debug-sdk`(`ember-debug-sdk`)不在这三个包之列,版本独立,不由本文的发布脚本发布。
14
- - `release-check` 会检查工具链包的包名是否在 `fcdev` 的 `optionalDependencies` 里。
15
- - 工具链包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs`。
16
- - 每个包的 `package.json` 写 `license`、`engines`(`node >=22`)、`files`,不写 `repository`、`homepage`、`bugs`(源码不公开,写了也打不开)。作者与邮箱为 `sungbin`、`sungbin@3578.cn`。
17
-
18
- ## 2. 发布前提
19
-
20
- 1. 所有改动已提交。
21
- 2. 工具链包已构建:`node tools/build-cc65.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
22
- 3. `npm run release:check` 通过。
23
- 4. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(三个包共用一份,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展与模拟器各有自己的 `CHANGELOG.md`(`vscode/`、`virtuanes/`),版本号独立,有改动才升。
24
-
25
- ## 3. 检查
26
-
27
- `npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
28
-
29
- - 三个包的版本一致,都写了 `license`,`fcdev` 对工具链包的依赖版本一致;工具链包的包名在 `fcdev` 的依赖里,作用域包声明了公开发布。
30
- - `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
31
- - 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
32
- - `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
33
- - 工具链包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
34
- - 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
35
-
36
- `npm run release:verify` 做安装验证,见 [08-测试与验证](08-测试与验证.md) 第 6 节。
37
-
38
- ## 4. 发布顺序
39
-
40
- 先发工具链包,再发 `fcdev`,最后发 `create-fcdev`:
41
-
42
- 1. `fcdev-cc65`
43
- 2. `fcdev`
44
- 3. `create-fcdev`
45
-
46
- `npm publish` 需要先登录 npm,可能还要二次验证。可以先对每个包运行 `npm publish --dry-run`,核对内容清单与体积。
47
-
48
- ## 5. 包的体积
49
-
50
- `npm publish --dry-run` 的结果(版本 0.1.0):
51
-
52
- | 包 | 文件数 | 包大小 |
53
- | --- | --- | --- |
54
- | `fcdev` | 71 | 64 kB |
55
- | `create-fcdev` | 23 | 15 kB |
56
- | `fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
57
-
58
- 体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
59
-
60
- ## 6. 发布脚本
61
-
62
- `tools/release.mjs` 把上面的步骤串起来,不暂存、不提交:
63
-
64
- | 命令 | 作用 |
65
- | --- | --- |
66
- | `npm run release:prepare -- <版本号>` | 升版本号:改主包与创建包的 `version`、主包对工具链包的精确依赖,重新构建工具链包并生成它的 `package.json`,再运行 `npm install` 刷新锁文件。完成后由使用者自己提交 |
67
- | `npm run release:publish -- --dry-run` | 演练:跑全部测试、`release:check`、`release:verify` 与各包的 `npm publish --dry-run`,不登录、不真正发布;已经发布过的版本只警告并跳过试发布 |
68
- | `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、三个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4 节的顺序发布,发布后不再用 `npm view` 核对(新发布的包要等 npm 审核,马上查不到)。验证码由 npm 在终端里询问 |
69
-
70
- 两个命令都可以加 `--allow-dirty`,允许工作区有未提交的改动,只用于演练。