fcdev 0.7.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 (39) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +9 -8
  3. package/docs/{02- → 01-}/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +10 -8
  4. package/docs/{05- → 02-}/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +12 -22
  5. package/docs/{06- → 03-}/345/217/215/346/261/207/347/274/226.md +12 -46
  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 +21 -26
  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 +3 -3
  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/commands/docs-command.mjs +2 -2
  17. package/src/cli/index.mjs +1 -1
  18. package/src/config/config-loader.mjs +1 -1
  19. package/src/docs/doc-index.mjs +1 -1
  20. package/src/docs/doc-topics.mjs +9 -15
  21. package/src/docs/index.mjs +1 -1
  22. package/src/emulator/sb2000-session.mjs +15 -12
  23. package/src/targets/target-registry.mjs +9 -1
  24. package/targets/nes/lib/fcnes.lib +0 -0
  25. package/targets/nes/lib/nes-font.o +0 -0
  26. package/targets/sb2000/api-reference.md +2 -1
  27. package/targets/sb2000/examples-source.md +1330 -0
  28. package/targets/sb2000/lib/crt0.o +0 -0
  29. package/targets/sb2000/lib/sb2000.lib +0 -0
  30. package/targets/sb2000/symbols-reference.md +670 -0
  31. package/targets/sb2000/target.json +1 -0
  32. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +0 -164
  33. package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +0 -123
  34. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +0 -50
  35. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +0 -75
  36. package/docs/09-/345/217/221/345/270/203.md +0 -75
  37. package/docs/10-VS Code/346/211/251/345/261/225.md" +0 -131
  38. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +0 -50
  39. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +0 -10
@@ -32,6 +32,7 @@
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
  },
@@ -1,164 +0,0 @@
1
- # 软件架构设计
2
-
3
- fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板和反汇编前端,运行与调试用的模拟器(Ember)需要自备。用 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-debug-sdk` 是 Ember 调试服务的客户端,`fcdev` 的 `debug` 与 `run --debug` 经它连接 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 与模拟器 Ember 的源码放在仓库根目录的 `cc65/` 与 `ember/`,由本仓库维护;`virtuanes/` 是 `fcdev` 不再使用的旧模拟器,保留作学习机阶段的参考 | 以后在本仓库里直接修改与升级,来源仍可核对 |
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
- ember/ 模拟器 Ember 的源码(本仓库维护,设计与调试服务见 ember/docs)
80
- virtuanes/ 旧模拟器源码(VirtuaNES 调试版,fcdev 不再使用,保留作参考)
81
- vscode/ VS Code 扩展(独立的 npm 项目,不在工作区里),见 [10-VS Code扩展](10-VS%20Code扩展.md)
82
- tools/ 维护脚本,见第 8 节
83
- apps/ 应用程序与示例(apps/sb2000:SB-DOS 的 asm、edit、runnes、disk 与 examples 示例),不在工作区里,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 10 节
84
- test/ 仓库级测试:目录结构、cc65 工具链包、SB2000 头文件
85
- machines/ 各机型的资料与工程(不属于 fcdev 包,不随包发布),一个机型一个目录,如 machines/sb2000
86
- build/ 构建中间目录(不入库):cc65-work/ 是 cc65 的构建副本,virtuanes/ 是旧模拟器的编译输出
87
- ```
88
-
89
- ## 5. 主包分层
90
-
91
- `packages/fcdev/src/` 下每个目录是一层功能,目录之间只能按下表引用,并且只经对方的 `index.mjs`:
92
-
93
- | 目录 | 职责 | 允许引用 |
94
- | --- | --- | --- |
95
- | `shared` | 错误类型、文件与进程小工具 | 无 |
96
- | `api` | 目标的 C 接口文档:解析头文件文档注释、查询与格式化 | 无 |
97
- | `docs` | 开发文档的主题登记表:主题名、文件、标题、说明,以及本机路径 | `shared` |
98
- | `config` | 查找与读取 `fcdev.json` | `shared` |
99
- | `targets` | 目标注册表、程序名规则 | `shared` |
100
- | `toolchain` | 定位与调用 cc65 工具链 | `shared` |
101
- | `packagers` | 打包器:平铺映像、iNES、FAT12 软盘镜像 | `shared` |
102
- | `emulator` | 定位与启动 Ember、定位调试 SDK 的终端客户端 | `shared` |
103
- | `disasm` | 反汇编前端 | `shared`、`toolchain` |
104
- | `build` | 构建计划、增量、调用工具链、打包 | `shared`、`config`、`targets`、`toolchain`、`packagers` |
105
- | `cli` | 参数解析与各命令 | `shared`、`config`、`targets`、`toolchain`、`build`、`emulator`、`disasm`、`api`、`docs` |
106
-
107
- - `bin/fcdev.mjs` 只调用 `cli` 的 `runCli`。
108
- - `targets`、`toolchain`、`packagers` 之间不互相引用,由 `build` 组装。
109
- - 依赖表在 `tools/check-structure.mjs` 里登记,`npm run boundaries` 检查;新增目录要先登记,改表时同步改本节。
110
-
111
- ## 6. 错误处理
112
-
113
- - 可预期的使用错误(配置有误、找不到工具、构建失败等)一律抛 `FcdevError`,带错误码 `code` 和下一步建议 `hint`。
114
- - `runCli` 捕获 `FcdevError`,向标准错误写“错误:”加说明,再写建议,返回退出码 1;其他异常是程序自身的缺陷,不捕获,直接抛出。
115
- - 外部工具(cc65、ca65、ld65)的输出原样透传,不改写,供 VS Code 问题匹配器使用。
116
- - 启动外部程序不经过 shell,参数逐个传递,带超时(默认 120 秒)。
117
-
118
- ## 7. 许可证分区
119
-
120
- | 部分 | 许可证 |
121
- | --- | --- |
122
- | 仓库与 `fcdev`、`create-fcdev` 自己的代码 | Apache-2.0,见根目录 `LICENSE` |
123
- | `cc65/` 及工具链包 | zlib,见 `cc65/LICENSE` |
124
- | `virtuanes/` | GPL-3.0-only,见 `virtuanes/LICENSE` |
125
-
126
- 模拟器源码里只有 `interp.h`、`nx_hq2x.h`、`nx_Scale2x.h` 三个文件头写“版本 2 或以后”,合并后按 GPLv3 发布。两个包都是独立程序,许可证互不影响。
127
-
128
- ## 8. 维护脚本
129
-
130
- | 脚本 | 作用 |
131
- | --- | --- |
132
- | `tools/build-cc65.mjs` | 构建 cc65 工具与运行库,组装 `fcdev-cc65`,见 [04-cc65工具链](04-cc65工具链.md) |
133
- | `tools/build-libs.mjs` | 按各目标的 `lib-build.json` 用 `cc65`、`ca65`、`ar65` 编出 `lib/` 下的运行库(`.c` 与 `.s` 源码,目录项递归展开);`fcdev` 的 `prepack` 与 `npm test` 前自动运行 |
134
- | `tools/gen-sb2000-header.mjs` | 由 `sb2000.inc` 生成 `sb2000-symbols.h` |
135
- | `tools/check-sb2000-api.mjs` | 检查 SB2000 的 C 接口:函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 6 节 |
136
- | `tools/gen-sb2000-api-doc.mjs` | 由头文件文档注释生成 `targets/sb2000/api-reference.md` |
137
- | `tools/check-structure.mjs` | 检查主包各层的依赖方向(`npm run boundaries`) |
138
- | `tools/release-check.mjs` | 发布前检查(`npm run release:check`),见 [09-发布](09-发布.md) |
139
- | `tools/verify-install.mjs` | 打包后在临时目录里创建、安装并构建四个模板(`npm run release:verify`) |
140
- | `tools/release.mjs` | 发布脚本:升版本号、检查、试发布与按顺序发布(`npm run release:prepare`、`npm run release:publish`),见 [09-发布](09-发布.md) 第 6 节 |
141
-
142
- ## 9. 文档清单
143
-
144
- 文档放在主包的 `docs/` 目录,在这里维护,随 `fcdev` 包一起发布:安装后在 `node_modules/fcdev/docs/`。`npx fcdev docs` 列出全部主题并给出本机路径,主题登记在 `src/docs/doc-topics.mjs`;新增、改名或删除文档时同步改登记,测试会核对登记与目录一致。文档里指向主包内文件的链接用相对路径,指向仓库其他目录(`tools/`、`virtuanes/`、`vscode/` 等,不随包发布)的文件只写路径,不做链接。`api` 主题是例外:它指向目标目录里由头文件文档注释生成的接口参考,不放进 `docs/`,避免两份不一致。
145
-
146
- | 主题 | 文档 | 内容 |
147
- | --- | --- | --- |
148
- | `architecture` | 01-软件架构设计 | 本文 |
149
- | `build` | [02-命令行与构建](02-命令行与构建.md) | 命令、构建规则、配置文件、构建流程 |
150
- | `targets` | [03-目标规范](03-目标规范.md) | 目标定义、打包器、新增机型的步骤 |
151
- | `toolchain` | [04-cc65工具链](04-cc65工具链.md) | cc65 源码、构建与工具链包 |
152
- | `emulator` | [05-模拟器与调试](05-模拟器与调试.md) | 运行方案、Ember 定位、调试服务与 debug 命令 |
153
- | `disasm` | [06-反汇编](06-反汇编.md) | 反汇编前端的流程与限制 |
154
- | `create` | [07-创建包与模板](07-创建包与模板.md) | 创建命令、模板与生成内容 |
155
- | `testing` | [08-测试与验证](08-测试与验证.md) | 测试分层、环境变量与运行方法 |
156
- | `release` | [09-发布](09-发布.md) | 发布顺序、前提与检查 |
157
- | `vscode` | [10-VS Code扩展](10-VS%20Code扩展.md) | 扩展的智能感知、语法高亮、项目信息来源、目录分层与打包 |
158
- | `nes` | [nes/01-NES目标](nes/01-NES目标.md) | NES 目标的构建与接口 |
159
- | `sb2000` | [sb2000/01-开发指南](sb2000/01-开发指南.md) | SB2000 目标的程序格式、内存布局、运行库、常用做法与示例 |
160
- | `syscall` | [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) | SB-DOS 的系统调用:参数、结果、出错码与可靠程度 |
161
- | `hardware` | [sb2000/03-硬件说明](sb2000/03-硬件说明.md) | SB2000 的硬件行为 |
162
- | `api` | [api-reference](../targets/sb2000/api-reference.md) | SB2000 运行库全部函数的接口参考(由头文件文档注释生成,查询用 `npx fcdev api`) |
163
- | `todo` | [待办备忘](待办备忘.md) | 已确定以后再做的事项 |
164
- | `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` | Ember 直接加载产物 |
61
- | `firmware-disk` | 加载 `fcdev.json` 里 `firmware` 指定的固件,把程序做成磁盘镜像挂到软驱并开机,再在 SB-DOS 里输入程序名运行(经 Ember 的调试服务,见 [05-模拟器与调试](05-模拟器与调试.md) 第 3 节);没有设置 `firmware` 时 `fcdev run` 报错 |
62
-
63
- `run.emulator` 必须是字符串,标识要用的模拟器,目前写 `ember`,主包总是用 Ember 运行(Ember 程序由配置项 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定),该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。
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,75 +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` | 指向 Ember 的可执行文件(如 `ember/out/Ember-win32-x64/ember.exe`);设置后额外运行“真实 Ember”的用例(还需要 cc65 与已构建的调试 SDK) |
27
- | `FCDEV_TEST_FIRMWARE` | 指向 SB2000 的 BIOS 文件,用于“SB2000 程序在 Ember 里运行”的用例;没有设置时用仓库里的 `reference/rom/SB2K_BIOS.NES` |
28
- | `FCDEV_TEST_NES_ROM` | 指向一个 NROM 的 `.nes` 文件;设置后额外对它做完整反汇编与回读 |
29
- | `FCDEV_SKIP_GUI_TESTS` | 设为 `1` 时跳过会打开 Ember 窗口的用例 |
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` | Ember 定位、端口检查、调试用户数据目录与环境变量、学习机程序名的按键、`run` 对学习机目标没有固件时报错、找不到 Ember 时报错、`debug` 把参数交给 `ember-debug`(需要调试 SDK 已构建);真实 Ember 里调试模式载入 NES 程序、运行 60 帧、截图,并用 `debug` 命令连到同一个 Ember。SB2000 运行库的测试程序(约 15 个用例,共数百项检查)在 `sb2000-library`,经 Ember 的调试服务运行整机(需要 Ember、cc65、已构建的调试 SDK 与 BIOS,缺一就整组跳过),见 [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 在 Ember 里运行:`emulator` 测试的真实 Ember 用例把程序载入调试模式的 Ember,运行 60 帧后用 `output.screenshot` 与 `fcdev debug screenshot` 截图并核对 PNG 文件头。
50
- - SB2000 的 C、汇编 hello 曾在旧模拟器里运行并截图核对屏幕文字(显示 `Hello, SB2000!` 与“你好,小霸王!”并能返回 DOS),这部分用例已删除;现在由 `sb2000-library` 的文字输出、显示等用例在 Ember 里覆盖运行与屏幕显示,没有单独核对 hello 的屏幕文字。
51
- - `fcdev run` 在 Ember 里运行学习机程序的完整流程(构建、打包镜像、添加固件、开机、输入程序名、运行)已用 `apps/sb2000/hwtest` 实际运行并截图核对,没有做成自动测试用例。
52
- - SB2000 的程序运行环境验证(V01 到 V10)的结论见 [sb2000/02-系统调用手册](sb2000/02-系统调用手册.md) 第 9 节。
53
- - 运行库测试程序的停靠点用写断点实现(对全局变量 `sb_test_stop` 设断点),不对函数入口设执行断点,原因见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 12 节。
54
- - 用调试服务验证时一律显式指定端口,避免连到别的 Ember;只结束本仓库启动的 Ember 进程。
55
-
56
- ## 5. 反汇编验证
57
-
58
- `fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥)回读后都与原文件逐字节一致,详见 [06-反汇编](06-反汇编.md) 第 6 节。
59
-
60
- ## 6. 安装验证
61
-
62
- `npm run release:verify`(`tools/verify-install.mjs`):
63
-
64
- 1. 把四个包用 `npm pack` 打成 `.tgz`。
65
- 2. 在临时目录里从本地 `.tgz` 安装 `create-fcdev`,不访问 npm 仓库,也不执行 `npm publish`。
66
- 3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev`、工具链包与调试 SDK(`fcdev` 依赖它们,不访问 npm 仓库时要一并给出),运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
67
- 4. 调试 SDK 单独装进临时目录,确认 `ember-debug-sdk` 与 `ember-debug-sdk/node` 两个入口能加载,`dist/cli.js`、`dist/mcp.js` 在。
68
- 5. 结束后删除临时目录;加 `--keep` 可保留,便于查看。
69
-
70
- 只验证构建,不启动模拟器。
71
-
72
- ## 7. 注意事项
73
-
74
- - 真实 Ember 的用例用系统临时目录下的 `fcdev-ember/<端口>` 做用户数据目录,结束时按进程号结束自己启动的 Ember 并删除该目录,不碰平时在用的 Ember。
75
- - 没有目测的界面输出,汇报时写明。
@@ -1,75 +0,0 @@
1
- # 发布
2
-
3
- 本文说明四个 npm 包的发布顺序、前提、检查和元数据。npm 的登录与 `npm publish` 由用户执行,不在代码或文档里记录任何凭据。
4
-
5
- ## 1. 包与版本
6
-
7
- | 包 | 说明 |
8
- | --- | --- |
9
- | `fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
10
- | `fcdev` | 主包,对工具链包写精确版本的 `optionalDependencies`,对 `ember-debug-sdk` 写精确版本的 `dependencies` |
11
- | `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
12
- | `ember-debug-sdk` | Ember 调试服务的客户端 SDK(含终端客户端与 MCP 服务),目录 `packages/ember-debug-sdk`;`fcdev` 的 `debug` 命令与 `run --debug` 经它连接 Ember,所以 `fcdev` 依赖它 |
13
-
14
- - 四个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包与 `ember-debug-sdk` 的依赖版本必须与之相同(`node tools/release.mjs prepare` 会一并改)。
15
- - `ember-debug-sdk` 的 `dist` 不入库,`npm pack` 与 `npm publish` 前会由它的 `prepack` 自动构建;发布脚本还会先运行它的 `check`(生成接口类型、类型检查、oxlint、构建、测试)。
16
- - `release-check` 会检查工具链包的包名是否在 `fcdev` 的 `optionalDependencies` 里。
17
- - 工具链包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs`。
18
- - 每个包的 `package.json` 写 `license`、`engines`(`node >=22`)、`files`,不写 `repository`、`homepage`、`bugs`(源码不公开,写了也打不开)。作者与邮箱为 `sungbin`、`sungbin@3578.cn`。
19
-
20
- ## 2. 发布前提
21
-
22
- 1. 所有改动已提交。
23
- 2. 工具链包已构建:`node tools/build-cc65.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
24
- 3. `npm run release:check` 通过。
25
- 4. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(`fcdev`、`create-fcdev`、`fcdev-cc65` 共用一份,SDK 没有单独的更新记录,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展有自己的 `CHANGELOG.md`(`vscode/`),版本号独立,有改动才升;Ember 没有随这些包发布。
26
-
27
- ## 3. 检查
28
-
29
- `npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
30
-
31
- - 四个包的版本一致,都写了 `license`,`fcdev` 对工具链包与 `ember-debug-sdk` 的依赖版本一致;工具链包的包名在 `fcdev` 的依赖里。
32
- - `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
33
- - 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
34
- - `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
35
- - 工具链包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
36
- - `ember-debug-sdk` 已构建(`dist` 存在),发布内容含两个入口、命令行入口与类型声明。
37
- - 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
38
-
39
- `npm run release:verify` 做安装验证,见 [08-测试与验证](08-测试与验证.md) 第 6 节。
40
-
41
- ## 4. 发布顺序
42
-
43
- 先发被依赖的工具链包与调试 SDK,再发 `fcdev`,最后发 `create-fcdev`:
44
-
45
- 1. `fcdev-cc65`
46
- 2. `ember-debug-sdk`
47
- 3. `fcdev`
48
- 4. `create-fcdev`
49
-
50
- `npm publish` 需要先登录 npm,可能还要二次验证。可以先对每个包运行 `npm publish --dry-run`,核对内容清单与体积。
51
-
52
- ## 5. 包的体积
53
-
54
- `npm publish --dry-run` 的结果(版本 0.1.0):
55
-
56
- | 包 | 文件数 | 包大小 |
57
- | --- | --- | --- |
58
- | `fcdev` | 71 | 64 kB |
59
- | `create-fcdev` | 23 | 15 kB |
60
- | `fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
61
- | `ember-debug-sdk` | 30 | 88 kB |
62
-
63
- 体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
64
-
65
- ## 6. 发布脚本
66
-
67
- `tools/release.mjs` 把上面的步骤串起来,不暂存、不提交:
68
-
69
- | 命令 | 作用 |
70
- | --- | --- |
71
- | `npm run release:prepare -- <版本号>` | 升版本号:改主包、创建包与 SDK 的 `version`、主包对工具链包的精确依赖,重新构建工具链包并生成它的 `package.json`,再运行 `npm install` 刷新锁文件。完成后由使用者自己提交 |
72
- | `npm run release:publish -- --dry-run` | 演练:跑全部测试、SDK 的 `check`、`release:check`、`release:verify` 与各包的 `npm publish --dry-run`,不登录、不真正发布;已经发布过的版本只警告并跳过试发布 |
73
- | `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、四个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4 节的顺序发布,发布后不再用 `npm view` 核对(新发布的包要等 npm 审核,马上查不到)。验证码由 npm 在终端里询问 |
74
-
75
- 两个命令都可以加 `--allow-dirty`,允许工作区有未提交的改动,只用于演练。
@@ -1,131 +0,0 @@
1
- # VS Code 扩展
2
-
3
- 扩展放在仓库的 `vscode/` 目录,包名 `fcdev`,显示名“fcdev 6502 开发”。首版做 ca65 汇编的语法高亮,以及 ca65 汇编与 cc65 的 C 的智能感知。扩展不内置编译器,只经 `node_modules` 里的 `fcdev` 命令行读取项目信息。
4
-
5
- ## 1. 范围
6
-
7
- 首版包含:
8
-
9
- - ca65 汇编(`.s`、`.asm`、`.inc`)的悬停、补全、转到定义、文档符号。
10
- - C 代码的智能感知:自动运行 `fcdev sync`,让 C/C++ 扩展与 clangd 找到 cc65 的头文件与宏。
11
- - 头文件里符号与函数的文档注释(`/** */`),悬停时显示。
12
- - ca65 汇编的语法高亮(TextMate 语法)。C 用 VS Code 内置的 C 语法,不另提供。
13
-
14
- 首版不含,登记在 [待办备忘](待办备忘.md):任务与问题匹配器、构建与运行命令、新建项目、调试。
15
-
16
- ## 2. 语言支持的分工
17
-
18
- | 语言 | 由谁提供 | 做法 |
19
- | --- | --- | --- |
20
- | C | VS Code 的 C/C++ 扩展或 clangd | 本扩展运行 `fcdev sync`,生成 `.vscode/c_cpp_properties.json` 与 `compile_flags.txt`,里面有头文件目录与预定义宏 |
21
- | 汇编 | 本扩展 | 自己解析 ca65 源码,不依赖其他扩展 |
22
-
23
- 本扩展的 `package.json` 用 `extensionPack` 带上 C/C++ 扩展(`ms-vscode.cpptools`),安装本扩展时一并安装;用户仍可单独卸载它,改用 clangd。
24
-
25
- C 的头文件注释用 Doxygen 的 `/** */` 写法,C/C++ 扩展与 clangd 都会在悬停时显示;`sb2000-symbols.h` 里每个常量宏上方的注释由 `tools/gen-sb2000-header.mjs` 从 `sb2000.inc` 的行尾注释生成。
26
-
27
- ### 2.1 C 的配置同步
28
-
29
- | 触发 | 行为 |
30
- | --- | --- |
31
- | 扩展激活(工作区里有 `fcdev.json`) | 同步所有工作区文件夹里的 fcdev 项目 |
32
- | 工作区文件夹增减 | 同步 |
33
- | `fcdev.json` 新建或修改 | 丢弃该项目的信息缓存,合并 500 毫秒内的连续变化后同步该项目 |
34
- | 命令“fcdev:同步 C/C++ 智能感知配置” | 手动同步,带进度,结束后弹出结果;没有 fcdev 项目时提示 |
35
-
36
- 自动同步只写日志,失败也不弹提示;日志在“输出”面板的 fcdev 通道。设置 `fcdev.intelliSense.autoSync`(默认开启)可关闭自动同步。
37
-
38
- `fcdev sync` 的预定义宏里带 `__fastcall__`、`__cdecl__` 两个空宏:cc65 的头文件用它们标注调用约定,C/C++ 扩展与 clangd 不认识,不定义会报语法错误。这两个宏只出现在 `info` 与 `sync` 的输出里,不参与构建。
39
-
40
- #### 提示选择配置
41
-
42
- C/C++ 扩展用哪个配置,只保存在它自己的工作区状态里,其他扩展无法读写,所以本扩展不能自动切换到 `fcdev` 配置。`.vscode/c_cpp_properties.json` 里除 `fcdev` 外还有其他配置时(例如名为 `Win32` 的默认配置),C/C++ 扩展可能选的不是 `fcdev`,这时 cc65 的头文件不会生效。扩展在同步成功后检查这个文件,条件满足时弹出提示:
43
-
44
- - 提示带“选择配置”按钮,点击后运行 C/C++ 扩展的命令 `C_Cpp.ConfigurationSelect`,由用户在列表里点选 `fcdev`。
45
- - 只在安装了 C/C++ 扩展(`ms-vscode.cpptools`)时提示;只用 clangd 的项目不受影响。
46
- - 每个项目每次 VS Code 会话只提示一次;在同一次同步里有多个项目时合并成一条。
47
- - 设置 `fcdev.intelliSense.promptConfigurationSelection`(默认开启)可关闭提示。
48
- - 只检查同步成功的项目;读取配置文件出错只写日志,不影响同步。
49
-
50
- ### 2.2 汇编
51
-
52
- | 功能 | 行为 |
53
- | --- | --- |
54
- | 悬停 | 6502 指令:功能、影响的标志位、寻址方式的写法与字节数;ca65 伪指令:写法与说明;符号:定义写法、种类、常量的值(同时给出十进制、十六进制与二进制)、源码里的说明注释、所在分组与文件行号 |
55
- | 补全 | 指令助记符、伪指令(输入 `.` 触发)、局部标签(输入 `@` 触发)、可见的符号 |
56
- | 转到定义 | 标签、常量、宏等符号跳到定义处;同名定义在同一范围内有多处时全部列出 |
57
- | 文档符号 | 大纲与面包屑里列出标签、常量、`.define`、宏、`.proc`、`.scope`、`.struct`、`.enum` |
58
-
59
- 可见的符号来自:
60
-
61
- 1. 当前文件,含局部标签与未保存的修改;名字重名时优先取这里的定义。
62
- 2. 当前文件 `.include` 的文件,最多展开 8 层;路径先按当前文件所在目录找,再按 `fcdev info --json` 给出的汇编引入目录找(含目标的 `asminclude`,所以 `sb2000.inc` 的符号能直接看到)。
63
- 3. 工作区里其他汇编文件里的非局部符号。
64
-
65
- 后两项读自磁盘并缓存;汇编文件变化时,丢弃该文件的解析缓存与工作区文件列表。扩展不理解条件汇编的取舍,`.if` 里的符号都会被收集。
66
-
67
- ### 2.3 汇编的语法高亮
68
-
69
- 语法文件是 `syntaxes/ca65.tmLanguage.json`,作用域名 `source.ca65`,对 `.s`、`.asm`、`.inc` 生效。它按行匹配,不理解上下文,所以只靠行首位置和固定词表分类。
70
-
71
- | 内容 | 作用域 |
72
- | --- | --- |
73
- | `;` 注释 | `comment.line.semicolon.ca65` |
74
- | `"..."`、`'...'` 字符串(行尾自动结束,字符串里的分号不算注释) | `string.quoted.double.ca65`、`string.quoted.single.ca65` |
75
- | 行首的标签定义(`name:`、`@local:`、`name::`),行首的 `:` 匿名标签 | `entity.name.function.label.ca65`、`entity.name.function.label.anonymous.ca65` |
76
- | 行首的常量定义(`NAME = 值`、`NAME := 值`) | `variable.other.constant.ca65` |
77
- | `.proc`、`.macro` 后的名字;`.scope`、`.struct`、`.enum` 后的名字 | `entity.name.function.ca65`、`entity.name.type.ca65` |
78
- | `.if` 系列、`.else`、`.elseif`、`.endif` | `keyword.control.conditional.ca65` |
79
- | 伪函数(`.defined`、`.sizeof`、`.lobyte` 等) | `support.function.pseudo.ca65` |
80
- | 其他以 `.` 开头的汇编指令 | `keyword.other.directive.ca65` |
81
- | 分支、跳转、返回指令(`bcc`、`jmp`、`jsr`、`rts`、`brk` 等) | `keyword.control.flow.ca65` |
82
- | 其他 6502 指令 | `keyword.other.mnemonic.ca65` |
83
- | `asl a` 等的累加器、`,x`、`,y` | `variable.language.register.ca65` |
84
- | `$` 十六进制、`%` 二进制、十进制数 | `constant.numeric.hex.ca65`、`constant.numeric.binary.ca65`、`constant.numeric.decimal.ca65` |
85
- | `#` 立即数标记 | `keyword.operator.immediate.ca65` |
86
- | `@name` 局部标签引用、`:+`、`:-` 匿名标签引用 | `variable.other.local.ca65`、`variable.other.anonymous.ca65` |
87
-
88
- - 指令与汇编指令不分大小写。
89
- - 标签定义要求冒号紧跟在名字后面,行首 `bne :+` 因此不会被当成标签。
90
- - 宏的调用与不在词表里的标识符不着色,因为单行匹配无法区分它们与符号。
91
- - 指令词表与 `vscode/src/shared/assembly/instruction-reference.ts`、`vscode/src/shared/assembly/directive-reference.ts` 的覆盖,由 `test/syntaxes/ca65-grammar.test.ts` 逐条检查。
92
-
93
- ## 3. 项目信息的来源
94
-
95
- 扩展经 `node <项目根>/node_modules/fcdev/bin/fcdev.mjs` 调用命令行,不经 shell,不依赖全局安装。
96
-
97
- | 命令 | 用途 |
98
- | --- | --- |
99
- | `fcdev info --json` | 读取目标、头文件目录、汇编引入目录与预定义宏;每个项目缓存一份,`fcdev.json` 变化后失效 |
100
- | `fcdev sync` | 生成 C/C++ 扩展的配置 |
101
-
102
- 项目没有安装 `fcdev` 或命令失败时,汇编智能感知只用当前文件与工作区里的源码,引入目录里的符号看不到;原因写在日志里,不弹提示。
103
-
104
- ## 4. 目录与分层
105
-
106
- 按分层组织,层内再按功能分目录,具体类只在组装根创建:
107
-
108
- | 目录 | 职责 |
109
- | --- | --- |
110
- | `src/contracts` | 接口:汇编智能感知服务、汇编源文件存取、C 配置同步服务、C/C++ 配置检查器、命令行执行器、项目信息提供者 |
111
- | `src/shared` | 纯函数与数据:ca65 解析、行内词法、数字格式、指令与伪指令参考、悬停文字、项目信息与 c_cpp_properties.json 的解析 |
112
- | `src/logic` | 业务:符号解析(含 `.include` 展开)、汇编智能感知服务、C 配置同步服务 |
113
- | `src/infra` | 与外部交互:读工作区文件、调用命令行、查找项目、读取 c_cpp_properties.json |
114
- | `src/entry` | VS Code 入口:四个汇编提供者、命令与文件监视器 |
115
- | `src/platform` | 日志(输出通道) |
116
- | `src/bootstrap` | 组装根 `extension.ts` |
117
- | `syntaxes` | ca65 的 TextMate 语法文件(静态资源,不经分层) |
118
-
119
- - 层之间的依赖方向、文件头、注释宽度与 `package.json` 声明和代码的一致性,由 `test/structure.test.ts` 检查。
120
- - 各层之间只经 `contracts` 里的接口协作;只有 `entry`、`platform`、`infra` 可以引用 `vscode`。
121
-
122
- ## 5. 构建、测试与打包
123
-
124
- 在 `vscode/` 目录运行:
125
-
126
- | 命令 | 用途 |
127
- | --- | --- |
128
- | `npm run check` | 类型检查、oxlint、测试、构建 |
129
- | `npm run package` | 生成 `.vsix`(不入库);发布到应用市场需要发布者账号,由用户操作 |
130
-
131
- 测试在 Node 环境里运行,`vscode` 模块用 `test/support/vscode-mock.ts` 替代;入口层的测试验证提供者与命令的行为,真实 VS Code 里的显示效果要手动打开项目核对。语法文件的测试用开发依赖 `vscode-textmate` 与 `vscode-oniguruma` 真实加载语法并分词,不依赖 VS Code;颜色由用户的主题决定,只检查作用域名。