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
package/CHANGELOG.md CHANGED
@@ -1,32 +1,61 @@
1
- # 更新记录
2
-
3
- 适用于 `fcdev`、`create-fcdev`、`fcdev-cc65` 三个包,它们的版本号相同。
4
-
5
- ## 0.6.0(2026-11-15)
6
-
7
- ### 安装
8
-
9
- - cc65 工具链包改名为 `fcdev-cc65`,不再放在 `@rujianjs` 作用域下;`fcdev` 会自动安装它,使用者无须任何操作。
10
-
11
- ### 模拟器与调试
12
-
13
- - 不再提供模拟器包 `@rujianjs/fcdev-emulator`:`fcdev run` 与 `fcdev debug` 需要自备模拟器,用 `fcdev.json` 的 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定。
14
-
15
- ## 0.5.0(2026-11-13)
16
-
17
- ### 小霸王学习机 SB2000
18
-
19
- - 新增直接操作硬件的函数:通用 DMA、图形端口(显存、调色板、精灵)和硬件定时器,程序不用再自己写寄存器。
20
- - 新增硬件寄存器与位的符号,C 里以 `SB_HW_` 开头,汇编里以 `HW_` 开头。
21
- - C 接口参考扩充到 204 个函数,用 `npx fcdev api dma`、`npx fcdev api ppu`、`npx fcdev api timer` 查询新增的三个模块。
22
- - 硬件说明按真机实测更新:图形端口、DMA 和定时器的行为,并列出真机与模拟器仍有差异的读数。
23
-
24
- ### 反汇编
25
-
26
- - 识别地址表:`LDA 表,X` 加间接跳转、`PHA`/`RTS`、`JMP (地址)` 指向的表,表里的地址作为新入口继续追踪。
27
-
28
- ### 模拟器与调试
29
-
30
- - `fcdev debug` 的 `tape play`、`tape rec` 命令里的文件路径按终端当前目录解析。
31
- - 模拟器包带上新版模拟器,改动见模拟器的更新记录。
32
- - 命令的提示、错误说明和文档里的示例统一写成 `npx fcdev …`,终端里直接输入 `fcdev` 会找不到命令的原因也写进了使用说明。
1
+ # 更新记录
2
+
3
+ 适用于 `fcdev`、`create-fcdev`、`fcdev-cc65` 三个包,它们的版本号相同。
4
+
5
+ ## 0.8.0(2026-11-18)
6
+
7
+ ### 小霸王学习机 SB2000
8
+
9
+ - 源文件里可以直接写汉字:用 UTF-8 保存,构建时自动转成学习机用的 GB2312,不再需要手写 `\xC4\xE3` 这样的转义。汉字要写在 `.c`、`.s` 文件里,不在 GB2312 里的字符会报错并指出位置。
10
+ - `npm create fcdev` 的 SB2000 模板改成直接写汉字。
11
+
12
+ ### 文档
13
+
14
+ - 新增“SB2000 符号参考”(`npx fcdev docs symbols`):列出功能号、子功能号、系统变量地址、出错码、硬件寄存器与位、运行库入口的汇编名、C 名、值与说明。
15
+ - 新增“SB2000 示例程序源码”(`npx fcdev docs examples`):手册里提到的 11 个示例程序的程序名与完整源码。
16
+ - 手册里指向开发文档的引用去掉了,每篇都能独立读懂。
17
+ - Ember 的帮助文档里新增“fcdev 开发手册”,可以直接阅读这些手册、C 接口参考与符号参考。
18
+ - 随包发布的文档只保留使用手册;架构设计、目标规范、测试、发布等开发文档不再随包发布,`fcdev docs` 的主题相应减少,文件名重新编号。
19
+
20
+ ## 0.7.0(2026-11-15)
21
+
22
+ ### 模拟器与调试
23
+
24
+ - `fcdev run` 与 `fcdev debug` 改用新模拟器 Ember:用 `fcdev.json` 的 `emulator` 或环境变量 `FCDEV_EMULATOR` 指向 Ember 的可执行文件,不再支持旧模拟器。
25
+ - `fcdev debug` 的参数改为调试终端客户端 `ember-debug` 的命令,如 `debug call runtime.status`、`debug screenshot out.png`,不再支持旧模拟器的单行命令。
26
+ - `fcdev run --debug` 用独立的用户数据目录启动 Ember,可以和平时在用的 Ember 同时运行,程序载入后停在开机状态,等待 `debug` 命令。
27
+ - `fcdev` 依赖调试 SDK `ember-debug-sdk`,安装时自动带上。
28
+ - 学习机目标(SB2000)的程序可以用 `fcdev run` 在 Ember 里运行:在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,程序会放进软盘镜像、开机后自动在 SB-DOS 里输入程序名运行;加 `--debug` 则停在开机状态,由 `debug` 命令继续。
29
+
30
+ ### 反汇编
31
+
32
+ - `fcdev disasm --trace` 改为读 Ember 记录的指令轨迹,不再读旧模拟器的轨迹。
33
+
34
+ ## 0.6.0(2026-11-15)
35
+
36
+ ### 安装
37
+
38
+ - cc65 工具链包改名为 `fcdev-cc65`,不再放在 `@rujianjs` 作用域下;`fcdev` 会自动安装它,使用者无须任何操作。
39
+
40
+ ### 模拟器与调试
41
+
42
+ - 不再提供模拟器包 `@rujianjs/fcdev-emulator`:`fcdev run` 与 `fcdev debug` 需要自备模拟器,用 `fcdev.json` 的 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定。
43
+
44
+ ## 0.5.0(2026-11-13)
45
+
46
+ ### 小霸王学习机 SB2000
47
+
48
+ - 新增直接操作硬件的函数:通用 DMA、图形端口(显存、调色板、精灵)和硬件定时器,程序不用再自己写寄存器。
49
+ - 新增硬件寄存器与位的符号,C 里以 `SB_HW_` 开头,汇编里以 `HW_` 开头。
50
+ - C 接口参考扩充到 204 个函数,用 `npx fcdev api dma`、`npx fcdev api ppu`、`npx fcdev api timer` 查询新增的三个模块。
51
+ - 硬件说明按真机实测更新:图形端口、DMA 和定时器的行为,并列出真机与模拟器仍有差异的读数。
52
+
53
+ ### 反汇编
54
+
55
+ - 识别地址表:`LDA 表,X` 加间接跳转、`PHA`/`RTS`、`JMP (地址)` 指向的表,表里的地址作为新入口继续追踪。
56
+
57
+ ### 模拟器与调试
58
+
59
+ - `fcdev debug` 的 `tape play`、`tape rec` 命令里的文件路径按终端当前目录解析。
60
+ - 模拟器包带上新版模拟器,改动见模拟器的更新记录。
61
+ - 命令的提示、错误说明和文档里的示例统一写成 `npx fcdev …`,终端里直接输入 `fcdev` 会找不到命令的原因也写进了使用说明。
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  npm install --save-dev fcdev
11
11
  ```
12
12
 
13
- 要求 Node.js 22 及以上。cc65 编译器在依赖包 `fcdev-cc65` 里,npm 会自动安装;也可以用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。模拟器不随包提供,`run` 与 `debug` 需要自备:用环境变量 `FCDEV_EMULATOR` 或 `fcdev.json` 的 `emulator` 指定,调试命令要求该模拟器支持同样的调试服务。
13
+ 要求 Node.js 22 及以上。cc65 编译器在依赖包 `fcdev-cc65` 里,npm 会自动安装;也可以用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。模拟器 Ember 不随包提供,`run` 与 `debug` 需要自备:用环境变量 `FCDEV_EMULATOR` 或 `fcdev.json` 的 `emulator` 指向 Ember 的可执行文件。调试 SDK `ember-debug-sdk` 是 `fcdev` 的依赖,会自动安装。
14
14
 
15
15
  ## 使用
16
16
 
@@ -20,13 +20,13 @@ npm install --save-dev fcdev
20
20
  npx fcdev build # 构建当前目录;目录里的全部 .c、.s、.asm 链接成一个程序
21
21
  npx fcdev build src # 构建目录 src
22
22
  npx fcdev build src/a.c # 只构建这个文件,它自己是一个程序
23
- npx fcdev run src # 构建后在模拟器里运行
23
+ npx fcdev run src # 构建后在 Ember 里运行
24
24
  npx fcdev disk src # 构建后把程序放进磁盘镜像(只有声明了磁盘能力的目标)
25
25
  npx fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
26
26
  npx fcdev sync # 生成 IDE 的 C/C++ 配置
27
27
  npx fcdev info --json # 显示目标、工具链与头文件目录
28
28
  npx fcdev api sb_file_open # 查询目标的 C 接口文档(函数名、模块名、$功能号或关键词;不带词列出全部模块)
29
- npx fcdev docs syscall # 查开发文档的本机路径(主题名或关键词;不带词列出全部主题)
29
+ npx fcdev docs syscall # 查使用文档的本机路径(主题名或关键词;不带词列出全部主题)
30
30
  ```
31
31
 
32
32
  入口是 `main`(汇编程序写 `.export _main`)。产物放在项目根的 `build/<目标>/`,中间文件在 `build/obj/`。
@@ -34,12 +34,12 @@ npx fcdev docs syscall # 查开发文档的本机路径(主题名或关键
34
34
  ### 调试
35
35
 
36
36
  ```bash
37
- npx fcdev run --debug --port 5688 src # 以调试模式启动模拟器,只在收到 run 命令时运行
38
- FCDEV_DEBUG_PORT=5688 npx fcdev debug run 60
39
- FCDEV_DEBUG_PORT=5688 npx fcdev debug shot screen.png
37
+ npx fcdev run --debug --port 5688 src # 以调试模式启动 Ember,程序载入后停在开机状态
38
+ FCDEV_DEBUG_PORT=5688 npx fcdev debug call runtime.run frames=60 wait=true
39
+ FCDEV_DEBUG_PORT=5688 npx fcdev debug screenshot screen.png
40
40
  ```
41
41
 
42
- `debug` 把命令原样转发给模拟器的调试服务,命令表见模拟器的说明文档。调试端口默认 5699。
42
+ `debug` 把参数原样交给 Ember 调试 SDK 的终端客户端 `ember-debug`,`npx fcdev debug --help` 查看命令,`npx fcdev debug methods` 列出全部请求。调试端口默认 5699。学习机目标需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件,`run` 会把程序放进软盘镜像、开机并在 SB-DOS 里输入程序名运行(加 `--debug` 停在开机状态)。
43
43
 
44
44
  ### 反汇编
45
45
 
@@ -49,7 +49,7 @@ npx fcdev disasm prog.bin --base 8000 --entry 8008 # 平铺二进制:
49
49
  npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文件
50
50
  ```
51
51
 
52
- 用 `da65` 生成源码,再用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较,不一致就报错。只追得到的代码才会按指令输出,其余按数据输出;用 `--cdl`(FCEUX、Mesen 格式)或 `--trace`(模拟器 `trace` 命令的日志)补充运行时才执行到的代码。
52
+ 用 `da65` 生成源码,再用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较,不一致就报错。只追得到的代码才会按指令输出,其余按数据输出;用 `--cdl`(FCEUX、Mesen 格式)或 `--trace`(Ember 记录的指令轨迹)补充运行时才执行到的代码。
53
53
 
54
54
  ## 配置
55
55
 
@@ -65,7 +65,7 @@ npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号
65
65
  | `include` | 空 | 额外的头文件目录 |
66
66
  | `toolchain` | 空 | 自备 cc65 的根目录,优先于工具链包 |
67
67
  | `firmware` | 无 | 固件(BIOS)文件;SB2000 运行时必填,fcdev 不提供任何 BIOS 或 ROM |
68
- | `emulator` | 空 | 模拟器的路径,不设时读环境变量 `FCDEV_EMULATOR` |
68
+ | `emulator` | 空 | Ember 的路径,不设时读环境变量 `FCDEV_EMULATOR` |
69
69
  | `targetOptions` | 空 | 目标专用选项,如 NES 的 `font`(是否链接 ASCII 字库,默认 `true`)、SB2000 的 `banks`(大程序的库页个数,默认 0) |
70
70
 
71
71
  ## 目标
@@ -77,20 +77,21 @@ npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号
77
77
 
78
78
  ## 文档
79
79
 
80
- 完整的使用手册与开发文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `npx fcdev docs` 列出全部主题,`npx fcdev docs <主题>` 给出该文档的本机路径。更新记录在本包的 `CHANGELOG.md`。
80
+ 完整的使用文档随本包发布,装好后在 `node_modules/fcdev/docs/`。终端里运行 `npx fcdev docs` 列出全部主题,`npx fcdev docs <主题>` 给出该文档的本机路径。更新记录在本包的 `CHANGELOG.md`。
81
81
 
82
82
  | 想做什么 | 主题 | 文档 |
83
83
  | --- | --- | --- |
84
- | 查命令、`fcdev.json` 配置与构建流程 | `build` | `docs/02-命令行与构建.md` |
85
- | 开发 NES 程序 | `nes` | `docs/nes/01-NES目标.md` |
84
+ | 查命令、`fcdev.json` 配置与构建流程 | `build` | `docs/01-命令行与构建.md` |
85
+ | 开发 NES 程序 | `nes` | `docs/nes/01-开发指南.md` |
86
86
  | 开发 SB2000(SB-DOS)程序 | `sb2000` | `docs/sb2000/01-开发指南.md` |
87
87
  | 查 SB-DOS 系统调用与出错码 | `syscall` | `docs/sb2000/02-系统调用手册.md` |
88
88
  | 查 SB2000 的硬件行为 | `hardware` | `docs/sb2000/03-硬件说明.md` |
89
89
  | 查 SB2000 运行库的 C 函数 | `api` | `targets/sb2000/api-reference.md`(也可以用 `npx fcdev api` 查询) |
90
- | 在模拟器里运行与调试,查调试命令 | `emulator` | `docs/05-模拟器与调试.md` |
91
- | 反汇编已有程序 | `disasm` | `docs/06-反汇编.md` |
92
- | 创建项目与模板 | `create` | `docs/07-创建包与模板.md` |
93
- | 新增机型的目标 | `targets` | `docs/03-目标规范.md` |
90
+ | 查 SB2000 的功能号、地址、出错码与寄存器符号(汇编名与 C 名) | `symbols` | `targets/sb2000/symbols-reference.md` |
91
+ | 看 SB2000 示例程序的完整源码 | `examples` | `targets/sb2000/examples-source.md` |
92
+ | 在模拟器里运行与调试,查调试命令 | `emulator` | `docs/02-模拟器与调试.md` |
93
+ | 反汇编已有程序 | `disasm` | `docs/03-反汇编.md` |
94
+ | 创建项目与模板 | `create` | `docs/04-创建包与模板.md` |
94
95
 
95
96
  ## 限制
96
97
 
@@ -1,10 +1,10 @@
1
1
  # 命令行与构建
2
2
 
3
- 本文说明 `fcdev` 的命令、构建规则、配置文件 `fcdev.json` 和构建流程。目标定义见 [03-目标规范](03-目标规范.md),模拟器相关命令的细节见 [05-模拟器与调试](05-模拟器与调试.md),反汇编见 [06-反汇编](06-反汇编.md)。
3
+ 本文说明 `fcdev` 的命令、构建规则、配置文件 `fcdev.json` 和构建流程。模拟器相关命令的细节见 [02-模拟器与调试](02-模拟器与调试.md),反汇编见 [03-反汇编](03-反汇编.md)。
4
4
 
5
5
  ## 1. 命令
6
6
 
7
- 入口是 [packages/fcdev/bin/fcdev.mjs](../bin/fcdev.mjs),由 `cli/index.mjs` 的 `runCli` 分发。命令正常结束返回 0;出现 `FcdevError` 时向标准错误写“错误:”加说明与建议,返回 1。
7
+ 命令正常结束返回 0;出错时向标准错误写“错误:”加说明与建议,返回 1。
8
8
 
9
9
  `fcdev` 装在项目的 `node_modules` 里,没有加入系统的 `PATH`,在终端里要写成 `npx fcdev <命令>`(全局安装 `npm install -g fcdev` 后可以直接写 `fcdev <命令>`);`package.json` 的 `scripts` 里直接写 `fcdev <命令>`。下面的表格和本文其余地方都省略 `npx`。
10
10
 
@@ -12,26 +12,26 @@
12
12
  | --- | --- |
13
13
  | `fcdev build [路径]` | 构建,规则见第 2 节 |
14
14
  | `fcdev disk [路径]` | 构建并把产物放进磁盘镜像;只有声明了磁盘能力的目标可用,镜像放在产物旁边,文件名与程序名相同,扩展名为 `.img`,卷标为 `FCDEV` |
15
- | `fcdev run [路径]` | 构建后在模拟器里运行 |
16
- | `fcdev debug <调试命令…>` | 把命令原样转发给模拟器的调试服务 |
15
+ | `fcdev run [路径]` | 构建后在 Ember 里运行 |
16
+ | `fcdev debug <参数…>` | 把参数原样交给 Ember 调试 SDK 的终端客户端 `ember-debug`(`call`、`screenshot`、`watch` 等) |
17
17
  | `fcdev disasm <文件>` | 反汇编,并回读校验 |
18
18
  | `fcdev sync` | 生成 IDE 配置,见第 6 节 |
19
19
  | `fcdev info [--json]` | 显示目标、工具链与头文件目录 |
20
20
  | `fcdev api [词] [--json]` | 查询目标的 C 接口文档,见第 5.1 节 |
21
- | `fcdev docs [词] [--json]` | 查询开发文档的本机路径,见第 5.2 节 |
21
+ | `fcdev docs [词] [--json]` | 查询使用文档的本机路径,见第 5.2 节 |
22
22
 
23
23
  通用选项:
24
24
 
25
25
  | 选项 | 说明 |
26
26
  | --- | --- |
27
27
  | `--target <名>` | 指定目标,覆盖 `fcdev.json` 里的 `target` |
28
- | `--debug` | `run` 以调试模式启动模拟器 |
28
+ | `--debug` | `run` 以调试模式启动 Ember |
29
29
  | `--port <端口>` | `run` 的调试端口,1 到 65535,默认 5699 |
30
30
  | `--json` | `info` 输出机器可读格式 |
31
31
  | `-h`、`--help` | 显示帮助 |
32
32
  | `-v`、`--version` | 显示版本 |
33
33
 
34
- `--verbose` 能被解析,目前没有命令使用它。`disasm` 的选项见 [06-反汇编](06-反汇编.md)。`debug` 把命令名之后的全部参数原样交给调试服务,不再解析选项;它的端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
34
+ `--verbose` 能被解析,目前没有命令使用它。`disasm` 的选项见 [03-反汇编](03-反汇编.md)。`debug` 把命令名之后的全部参数原样交给 `ember-debug`,不再解析选项;它按环境变量 `FCDEV_DEBUG_PORT`(默认 5699)找到 `run --debug` 启动的 Ember,细节见 [02-模拟器与调试](02-模拟器与调试.md)。
35
35
 
36
36
  ## 2. 构建单位
37
37
 
@@ -62,7 +62,7 @@
62
62
  | `include` | 字符串数组 | 空 | 额外头文件目录,相对项目根 |
63
63
  | `toolchain` | 字符串 | 空 | 自备 cc65 的根目录,优先于工具链包 |
64
64
  | `firmware` | 字符串 | 无 | 固件(BIOS、ROM)文件路径;目标的运行方案要求固件时必填 |
65
- | `emulator` | 字符串 | 空 | 模拟器可执行文件路径,不设时读环境变量 `FCDEV_EMULATOR` |
65
+ | `emulator` | 字符串 | 空 | Ember 可执行文件路径,不设时读环境变量 `FCDEV_EMULATOR` |
66
66
  | `targetOptions` | 对象 | 空 | 目标专用选项,由各目标定义并校验 |
67
67
 
68
68
  - 配置里出现未知项、类型不对、`define` 的值不是字符串或数字时,报错并列出可用的项。
@@ -78,13 +78,16 @@
78
78
  | 产物 | `<项目根>/<out>/<目标>/<程序名><扩展名>`,程序名按目标的 `nameRule` 规范化 |
79
79
  | 中间文件 | `<项目根>/<out>/obj/<目标>/<程序名>/` |
80
80
 
81
- 中间文件目录里有每个源文件对应的 `.o`、依赖文件 `.d`,C 文件还有编译出的 `.s` 与汇编依赖文件 `.asm.d`;链接产物 `<程序名>.bin`、`<程序名>.map`、`<程序名>.dbg`;多页程序还有展开后的链接配置 `<程序名>.cfg`;以及指纹文件 `stamp.json`。`.o` 的文件名取源文件相对目录的路径,去掉扩展名,目录分隔符换成 `__`。
81
+ 中间文件目录里有每个源文件对应的 `.o`、依赖文件 `.d`,C 文件还有编译出的 `.s` 与汇编依赖文件 `.asm.d`;目标声明了源文件编码时(如 sb2000),还有每个源文件转码后的副本 `.gb2312.c` 或 `.gb2312.s`;链接产物 `<程序名>.bin`、`<程序名>.map`、`<程序名>.dbg`;多页程序还有展开后的链接配置 `<程序名>.cfg`;以及指纹文件 `stamp.json`。`.o` 的文件名取源文件相对目录的路径,去掉扩展名,目录分隔符换成 `__`。
82
82
 
83
83
  ### 4.2 单个程序
84
84
 
85
85
  1. 对每个 `.c`:`cc65` 输出 `.s` 与依赖文件(`--create-dep`)。
86
86
  2. 对每个 `.s`(含上一步生成的):`ca65` 汇编成 `.o`,同样输出依赖文件。
87
- 3. `ld65`:按目标的链接配置,依次链接启动代码、用户的 `.o`、开启的目标选项所带的目标文件,最后链接目标声明的库;生成 `.bin`、`.map`、`.dbg`。目标声明了 `forceImports` 时,用 `-u` 强制引入这些符号。目标声明了多页(换页)程序(`banked`)且库页个数大于 0 时,链接配置由目标的模板按库页个数展开,写在中间文件目录里,打包器也不再检查映像大小上限,见 [03-目标规范](03-目标规范.md) 第 2.3 节。
87
+
88
+ 目标声明了源文件编码时(sb2000 声明了 GB2312),上面两步编译的是转码后的副本,错误信息仍指向原文件;转换规则见 [sb2000 开发指南](sb2000/01-开发指南.md) 第 5 节。
89
+
90
+ 3. `ld65`:按目标的链接配置,依次链接启动代码、用户的 `.o`、开启的目标选项所带的目标文件,最后链接目标声明的库;生成 `.bin`、`.map`、`.dbg`。目标声明了多页(换页)程序且库页个数大于 0 时,链接配置按库页个数展开,写在中间文件目录里,打包器也不再检查映像大小上限。
88
91
  4. 打包器把 `.bin` 做成最终产物。
89
92
 
90
93
  工具参数:
@@ -138,7 +141,7 @@
138
141
 
139
142
  ### 5.2 文档查询
140
143
 
141
- `fcdev docs` 查询随主包发布的开发文档(主包的 `docs/` 目录),只读、不联网、不需要 `fcdev.json` 和工具链。主题登记在 `src/docs/doc-topics.mjs`,主题名只用小写字母、数字与连字符,清单见 [01-软件架构设计](01-软件架构设计.md) 第 9 节。
144
+ `fcdev docs` 查询随主包发布的使用文档(主包的 `docs/` 目录),只读、不联网、不需要 `fcdev.json` 和工具链。
142
145
 
143
146
  | 用法 | 结果 |
144
147
  | --- | --- |
@@ -147,7 +150,6 @@
147
150
  | `fcdev docs <词>` | 按文件名(去掉序号与扩展名也可)或主题、标题、说明里的关键词查找;只匹配到一份时同上,多份时列出摘要 |
148
151
 
149
152
  - 查询依次按主题名、文件名、关键词匹配,先匹配上的为准;一份都没有匹配上时报“没有找到”。`--json` 输出机器可读的结果:不带查询词时是全部文档,否则是匹配到的文档,每项含 `topic`、`title`、`summary`、`file`、`localPath`。
150
- - 登记项默认是 `docs/` 下的文件;登记项带 `inPackage` 时指向主包根目录下的文件,目前只有 `api` 主题(`targets/sb2000/api-reference.md`)。
151
153
  - 文档目录不存在时报错,提示改读在线文档。
152
154
 
153
155
  ## 6. `fcdev sync`
@@ -0,0 +1,89 @@
1
+ # 模拟器与调试
2
+
3
+ `fcdev` 的 `run`、`debug` 命令使用模拟器 Ember。Ember 不随 npm 包提供,要在 `fcdev` 里指明它的位置(见第 1、2 节);调试服务由 Ember 提供,`fcdev` 用调试 SDK(npm 包 `ember-debug-sdk`,是 `fcdev` 的依赖,随 `fcdev` 一起安装)与它通信。Ember 的调试协议与全部请求见 Ember 帮助文档里的“调试接口手册”,SDK 的用法见该手册的“客户端工具”页。
4
+
5
+ Ember 运行 NES 程序,也运行学习机整机(SB2000);学习机的启动方式见第 3 节与第 6 节。
6
+
7
+ ## 1. Ember 的位置
8
+
9
+ - Ember 的安装目录里有可执行文件 `ember.exe`。
10
+ - 把这个文件的路径交给 `fcdev`,见第 2 节。
11
+
12
+ ## 2. 定位 Ember
13
+
14
+ 按顺序查找,找到即停:
15
+
16
+ 1. 配置项 `emulator`。
17
+ 2. 环境变量 `FCDEV_EMULATOR`。
18
+
19
+ 都没有设置时报“找不到 Ember”,指定的路径不存在时报“找不到 Ember:路径”。`fcdev` 不去 `PATH` 里猜。
20
+
21
+ ## 3. `fcdev run`
22
+
23
+ 先确认目标能运行、能找到 Ember,再构建并启动 Ember。目标没有运行方案时报错。
24
+
25
+ | 运行方案 | 做法 |
26
+ | --- | --- |
27
+ | `rom` | Ember 直接加载产物(`.nes`),不需要固件 |
28
+ | `firmware-disk` | 学习机方案:加载 `fcdev.json` 里 `firmware` 指定的 BIOS,把程序放进磁盘镜像挂到软驱 0 并开机;没有设置 `firmware` 时在构建之前报“需要固件”,见下面与第 6 节 |
29
+
30
+ - 学习机(`firmware-disk`)没有命令行入口,不论是否带 `--debug` 都经调试服务启动(独立的用户数据目录与调试端口,同下一条):依次 `machines.setBios`(Ember 把 BIOS 复制进自己的 BIOS 目录)、`machines.boot`(上电、不运行)、`media.floppyInsert`(放入 `fcdev disk` 生成的镜像,程序名取镜像里的程序)。没有 `--debug` 时,再让机器运行到 SB-DOS 询问日期,回车跳过日期与时间,输入程序名并回车,随后 `runtime.resume`,命令行断开调试连接并返回,Ember 留在运行状态;有 `--debug` 时停在开机状态,程序还没有被运行,要在 SB-DOS 里输入程序名才运行。程序名只能用字母与数字,不合适时用 `fcdev.json` 的 `name` 改名。
31
+
32
+ - 没有 `--debug`:用 `--cartridge=<产物>` 启动 Ember,窗口打开并开始运行,命令行立即返回。用的是 Ember 平时的用户数据目录(首选项、键位映射等设置照常生效),遵守 Ember 的单实例规则,见第 5 节。
33
+ - 有 `--debug`:用独立的用户数据目录(系统临时目录下的 `fcdev-ember/<端口>`)、`--debug-port=<端口>` 与随机生成的令牌启动 Ember,不带 `--cartridge`;连上调试服务后用 `cartridges.load` 载入产物,上电但不运行(`powerOn` 为真、`resume` 为假);之后用 `fcdev debug` 继续。独立的用户数据目录让调试用的 Ember 能和平时在用的 Ember 同时运行,互不影响设置。
34
+ - `--port` 指定调试端口,默认 5699。调试模式启动前先检查端口是否被占用,被占用就报错,不去连接,避免连到别的 Ember;启动后最多等 30 秒,等到调试服务可连接并成功载入程序,超时则结束 Ember 进程并报错;Ember 在就绪前退出时立即报错。
35
+ - Ember 进程与命令行脱离,命令行退出后窗口保持打开;工作目录是 Ember 所在目录。
36
+ - Ember 没有“退出”请求,调试结束后关闭它的窗口,或按 `run` 打印的进程号结束进程。
37
+
38
+ ## 4. `fcdev debug`
39
+
40
+ ```bash
41
+ npx fcdev debug call runtime.status
42
+ npx fcdev debug call runtime.run frames=60 wait=true
43
+ npx fcdev debug screenshot screen.png
44
+ npx fcdev debug methods
45
+ ```
46
+
47
+ - `debug` 之后的全部参数原样交给调试 SDK 的终端客户端 `ember-debug`(命令有 `endpoint`、`methods`、`describe`、`call`、`screenshot`、`watch`,选项见 `npx fcdev debug --help`),它的输出与退出码就是 `fcdev` 的输出与退出码(0 成功,1 失败,2 用法错误);`fcdev` 自己不解析调试命令。
48
+ - 找到 Ember:没有显式指定位置时,用环境变量 `FCDEV_DEBUG_PORT`(默认 5699)推出 `fcdev run --debug` 用的用户数据目录,读那里的端点文件取得地址与令牌。设置了环境变量 `EMBER_DEBUG_URL`、`EMBER_DEBUG_TOKEN`、`EMBER_DEBUG_ENDPOINT`、`EMBER_USER_DATA` 之一,或在命令里给了 `--url`、`--token`、`--endpoint-file`、`--user-data-dir`,就按显式指定的位置找,可以连到平时在用的 Ember。
49
+ - 命令的工作目录就是终端当前目录,`screenshot` 的相对路径相对终端当前目录;`call` 里的 `file` 参数(如 `inspector.traceStart` 的文件名)由 Ember 写进它的调试输出目录,调试模式下是用户数据目录里的 `debug-output`,结果里的 `file` 给出完整路径。
50
+ - 请求默认最多等 60 秒;`runtime.run` 带 `wait=true` 运行很多帧时用 `--timeout <毫秒>` 加长。
51
+ - 调试 SDK 随 `fcdev` 一起安装,已经构建好,不用另外构建。
52
+
53
+ ### 4.1 常用操作
54
+
55
+ | 要做的事 | 命令 |
56
+ | --- | --- |
57
+ | 看运行状态与卡带 | `call runtime.status` |
58
+ | 运行 N 帧并等运行结束 | `call runtime.run frames=N wait=true` |
59
+ | 单步 | `call runtime.step unit=instruction count=N`(`unit` 还有 `cycle`、`scanline`、`frame`) |
60
+ | 继续运行、暂停 | `call runtime.resume`、`call runtime.pause` |
61
+ | 复位 | `call runtime.reset kind=soft`(或 `hard`) |
62
+ | 看寄存器与芯片状态 | `call inspector.getState`、`call inspector.snapshot` |
63
+ | 读内存 | `call inspector.readMemory space=cpu address=0x8000 length=16 --out 文件`(数据是二进制,用 `--out` 保存;`call inspector.listSpaces` 列出全部空间) |
64
+ | 断点 | `call inspector.addBreakpoint kind=execute address=0x8000` |
65
+ | 截图 | `screenshot 文件.png` |
66
+ | 记录指令轨迹 | `call inspector.traceStart kind=instruction file=trace.txt`,运行后 `call inspector.traceStop id=<编号>`;文件用于 `fcdev disasm --trace` |
67
+ | 记录代码与数据标记 | `call inspector.cdlStart`,运行后 `call inspector.cdlSave file=prg.cdl` |
68
+ | 注入按键 | `call input.key code=KeyW down=true`(`code` 是 `KeyboardEvent.code`,由卡带的 mapper 脚本翻译)、`call input.pad port=0 buttons=1` |
69
+ | 订阅事件 | `watch runtime.* --timeout 5000` |
70
+
71
+ 全部请求、参数与错误码用 `fcdev debug methods` 与 `fcdev debug describe <请求>` 查看。
72
+
73
+ ## 5. 限制
74
+
75
+ - 学习机的运行方式是自动在 SB-DOS 里输入程序名,靠固定的帧数等待 DOS 启动(开机运行 900 帧后直接按两次回车,调试服务里不限速、几秒完成);换了别的 BIOS 或磁盘时提示的出现时间不同,就会输错位置,这时用 `--debug` 启动,自己用 `fcdev debug` 操作。
76
+ - 不带 `--debug` 的 `fcdev run` 遵守 Ember 的单实例规则:平时用的 Ember 已经在运行时,新启动的进程只会把已有窗口提到前面,不会载入新程序(Ember 首选项里开启“允许同时运行多个实例”后不受此限,会打开新窗口);这时先关闭 Ember,或改用 `--debug`(独立的用户数据目录,不受影响)。学习机目标不受影响,它总是用独立的用户数据目录。
77
+ - 不随包发布任何 BIOS 或 ROM,由用户经 `firmware` 提供(学习机目标必填)。
78
+
79
+ ## 6. 学习机在 Ember 里的调试
80
+
81
+ 学习机用 `--debug` 启动后,机器已开机、磁盘在软驱 0 里、没有运行,操作与 NES 相同,另有:
82
+
83
+ | 要做的事 | 命令 |
84
+ | --- | --- |
85
+ | 在 SB-DOS 里敲键 | `call input.key code=KeyA down=true`,运行几帧后 `down=false`;回车是 `Enter`,不要连续几帧不运行就松开,BIOS 来不及读到 |
86
+ | 手柄、鼠标 | `call input.pad port=0 buttons=1`、`call input.mouse kind=move dx=10 dy=5`、`call input.mouse kind=down buttons=1` |
87
+ | 把软驱里被程序改写的盘片存回镜像文件 | `call media.floppySave drive=0` |
88
+ | 取出、重新放入盘片 | `call media.floppyEject drive=0`、`call media.floppyInsert drive=0 path=<镜像>` |
89
+
@@ -1,21 +1,8 @@
1
1
  # 反汇编
2
2
 
3
- `fcdev disasm` 把 NES 程序或平铺二进制反汇编成 `ca65` 可直接汇编的源码,并保证汇编回去后与原映像逐字节一致。代码在 `packages/fcdev/src/disasm/`。
3
+ `fcdev disasm` 把 NES 程序或平铺二进制反汇编成 `ca65` 可直接汇编的源码,并保证汇编回去后与原映像逐字节一致。
4
4
 
5
- ## 1. 做法
6
-
7
- 指令解码与源码文本输出交给 cc65 自带的 `da65`,不改 `da65` 的 C 代码;前端脚本负责分析,并把分析结果写成 `da65` 的信息文件。只有实测发现信息文件无法表达时,才修改 `da65` 的 C 源码,并把每处修改写进 `cc65/README-FCDEV.txt`。
8
-
9
- 流程(`disassembler.mjs`):
10
-
11
- 1. 读取输入,判断格式,取出映像(字节、第一个字节的地址、中断向量)。
12
- 2. 收集入口:中断向量、`--entry`、`--trace` 里的地址、CDL 里每段连续代码的起点。没有任何入口时报错。
13
- 3. 静态追踪,标出每个字节是指令的操作码、操作数还是未知。
14
- 4. 生成 `da65` 信息文件。
15
- 5. 运行 `da65 -i <信息文件> --multi-pass`,得到 ca65 源码。
16
- 6. 回读校验:用 `ca65`、`ld65` 重新汇编,与原映像逐字节比较;不一致就报错,指出第一个差异的偏移与地址,不输出“成功”。
17
-
18
- ## 2. 命令
5
+ ## 1. 命令
19
6
 
20
7
  ```bash
21
8
  npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址] [--cdl 文件] [--trace 文件] [--symbols 文件] [--out 目录]
@@ -27,7 +14,7 @@ npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址
27
14
  | `--base <地址>` | 平铺二进制的加载地址,十六进制,可带 `$` 或 `0x`;平铺二进制必须给 |
28
15
  | `--entry <地址>` | 追踪代码的入口,可重复;iNES 自动使用中断向量 |
29
16
  | `--cdl <文件>` | CDL 文件,其中代码段的起点也当作入口 |
30
- | `--trace <文件>` | 模拟器 `trace` 命令记录的指令轨迹,执行过的指令地址都当作入口 |
17
+ | `--trace <文件>` | Ember 的 `inspector.traceStart`(`kind=instruction`)记录的指令轨迹,执行过的指令地址都当作入口 |
31
18
  | `--symbols <文件>` | 符号文件,给地址起名字 |
32
19
  | `--out <目录>` | 输出目录,默认 `build/disasm/<输入文件名>` |
33
20
 
@@ -44,65 +31,44 @@ npx fcdev disasm <文件> [--format ines|binary] [--base 地址] [--entry 地址
44
31
 
45
32
  `<名>` 取输入文件名(不含扩展名),非字母、数字、下划线、连字符的字符换成下划线。回读不一致时这些文件仍然保留。命令成功时输出映像大小、指令条数与字节数,以及“回读校验通过”;追踪中放弃某一路的警告最多显示 10 条。
46
33
 
47
- ## 3. 输入
34
+ ## 2. 输入
48
35
 
49
- ### 3.1 映像
36
+ ### 2.1 映像
50
37
 
51
38
  - iNES:只支持映射器 0(NROM),PRG 为 16K 或 32K。32K 映在 `$8000`,16K 映在 `$C000`;跳过 trainer;从 PRG 末尾读出 NMI、复位、IRQ 三个向量。其他映射器报错,可先导出某个 bank,用 `--format binary` 并指定加载地址。
52
39
  - 平铺二进制:按 `--base` 放置,不得超出 `$FFFF`,不能为空。
53
40
 
54
- ### 3.2 CDL
41
+ ### 2.2 CDL
55
42
 
56
43
  每个字节一个标志,位 0 表示被当作代码执行过,位 1 表示被当作数据读取过。支持 FCEUX 与 Mesen 的格式;Mesen CDLv2 开头多出的 9 个字节会自动跳过;只取与 PRG 对应的前 PRG 大小个字节,比 PRG 短时报错。
57
44
 
58
- ### 3.3 指令轨迹
45
+ ### 2.3 指令轨迹
59
46
 
60
- 模拟器 `trace` 命令的日志,每行以 `T` 开头,第二列是指令地址。轨迹里的地址都是真实执行过的指令开头,比 CDL 的“代码字节”更精确。
47
+ Ember 的 `inspector.traceStart`(`kind=instruction`)记录的日志:每行是 nestest 日志的写法,行首是四位大写十六进制的指令地址,后面跟指令字节(如 `C000 4C F5 C5 JMP $C5F5 ...`)。`io`、`irq` 与调用记录的行不是指令行,一律忽略。轨迹里的地址都是真实执行过的指令开头,比 CDL 的“代码字节”更精确。生成方法:`npx fcdev debug call inspector.traceStart kind=instruction file=trace.txt`,运行一段时间后 `npx fcdev debug call inspector.traceStop id=<编号>`,结果里的 `file` 是完整路径(文件写在 Ember 的调试输出目录)。
61
48
 
62
- ### 3.4 符号文件
49
+ ### 2.4 符号文件
63
50
 
64
51
  每行“名字 = 地址”或“名字 地址”,地址为十六进制,可带 `$` 或 `0x`;以 `;` 或 `#` 开头的行是注释,空行忽略。名字必须是合法的 ca65 标识符。同一地址有多个名字时只用第一个。中断向量对应的地址自动命名为 `reset`、`nmi`、`irq`。
65
52
 
66
53
  信息文件里总是引入 NES 的 `fcnes.inc`,所以 PPU 寄存器地址会显示成符号名;对平铺二进制也一样。
67
54
 
68
- ## 4. 静态追踪
55
+ ## 3. 静态追踪
69
56
 
70
- 规则(`analysis.mjs`):
57
+ 规则:
71
58
 
72
59
  - 顺序执行继续;条件分支两路都追;`JMP` 只追目标;`JSR` 追目标并假定会返回。
73
60
  - `RTS`、`RTI`、`BRK` 与间接 `JMP` 结束这一路。
74
61
  - 遇到非法操作码、超出映像末尾或与已识别的指令重叠时,放弃这一路并记入警告。
75
62
  - 没被追到的字节都按数据输出,这不影响回读校验。
76
- - 入口都追完后,查找经地址表分发的跳转(`address-tables.mjs`),表里的目标成为新入口,再继续追,直到没有新表。识别的写法(窗口为加载指令之后的 10 条顺序指令):
63
+ - 入口都追完后,查找经地址表分发的跳转,表里的目标成为新入口,再继续追,直到没有新表。识别的写法(窗口为加载指令之后的 10 条顺序指令):
77
64
  - `LDA 表,X/Y` 与 `LDA 表+1,X/Y` 成对,窗口里有间接 `JMP`:字表,目标就是表里的值;
78
65
  - 一对加载指令、两条 `PHA` 与一条 `RTS`:目标是表里的值加 1,表可以是字表,也可以是低、高字节分开的两张表;
79
66
  - 间接 `JMP (地址)` 的地址在映像内、那里还是未识别的字节:那里是字表。
80
67
  表项必须落在映像里、是官方操作码、不在已识别指令的中间,否则表在这一项结束,单张表最多 128 项;字表占的字节按 `AddrTable` 输出,分开的两张表保持为数据。
81
68
 
82
- 指令表在 `opcode-table.mjs`,共 151 条官方指令,数据取自 `da65` 的 `cc65/src/da65/opc6502.c`;非官方(非法)操作码不在表里。
83
-
84
- ## 5. 信息文件
85
-
86
- `info-writer.mjs` 把整个映像划分成首尾相接、互不重叠的段,没有遗漏,否则 `da65` 会把没说明的字节默认当成代码:
87
-
88
- | 段类型 | 用于 |
89
- | --- | --- |
90
- | `Code` | 追踪到的指令 |
91
- | `ByteTable` | 没被追到的字节 |
92
- | `AddrTable` | iNES 末尾 6 字节的中断向量表,以及识别出的字表 |
93
-
94
- 另有 `GLOBAL`(输入输出文件名、起始地址、CPU)、`ASMINC`(符号定义文件)与 `LABEL`(用户符号与中断向量名)。
95
-
96
- ## 6. 验证与限制
97
-
98
- 验证(见 [08-测试与验证](08-测试与验证.md)):`fcdev` 自己构建的 NES hello 与 SB2000 的 `.EXE`,以及一个真实的 NROM 游戏(超级马里奥,由环境变量 `FCDEV_TEST_NES_ROM` 提供)回读都与原文件逐字节一致。静态追踪追不到表驱动之外的间接调用,所以马里奥只追到约 2320 字节代码,其余按数据输出,回读仍一致;补充 CDL 或 `trace` 能扩大覆盖。步步高 DOS 下的 GBASIC(`.CMD`,26896 字节,平铺二进制加载地址 `$7B00`)加入地址表识别后,代码从 6905 字节增到 8980 字节,再加一个经人工确认的入口 `$880F` 增到 10361 字节;再用模拟器的 `trace ... unique` 记录下运行 BASIC 语句、图形编辑与退回 DOS 时执行过的地址,并补三个经单独追踪确认的入口,增到 14843 字节(剩余约 12000 字节主要是图形数据与关键字表),回读一致。
99
-
100
- 限制:
69
+ ## 4. 限制
101
70
 
102
71
  - iNES 只支持 NROM。
103
72
  - 只识别上述几种写法的地址表;用立即数拼出地址再存进指针的跳转、调用方自己写进工作区的分发、直接访问表项的对象表都追不到,也不把数据识别成字符串,未追到的字节都是 `ByteTable`。
104
- - 模拟器自带的 CDL 只对 SB2K 映射器有效。
105
73
  - SB2000 固件页的 CDL 验证没有做。
106
74
  - `da65` 输出的源码是 CRLF 换行。
107
-
108
- 以后要做的项目登记在 [待办备忘](待办备忘.md)。
@@ -1,6 +1,6 @@
1
1
  # 创建包与模板
2
2
 
3
- `create-fcdev` 是 `npm create fcdev` 运行的包:在空目录生成开发结构与示例程序,之后用 `npm run build` 构建。代码在 `packages/create-fcdev/`,只依赖 Node,不引入其他依赖。
3
+ `create-fcdev` 是 `npm create fcdev` 运行的包:在空目录生成开发结构与示例程序,之后用 `npm run build` 构建。只依赖 Node,不引入其他依赖。
4
4
 
5
5
  ## 1. 命令
6
6
 
@@ -50,16 +50,6 @@ npm create fcdev@latest [目录] [-- 选项]
50
50
 
51
51
  ## 4. 模板
52
52
 
53
- 每个模板是 `templates/<目标>-<语言>/` 目录,包含:
54
-
55
- | 文件 | 说明 |
56
- | --- | --- |
57
- | `template.json` | `target`、`language`、`title`,可选 `scripts`(额外的 npm 脚本)与 `notes`(创建完成后提示的说明);目录名必须等于 `<target>-<language>` |
58
- | `README.md` | 生成项目的说明,可用 `{{name}}`;末尾有“文档”一节,写明开发文档随 `fcdev` 安装在 `node_modules/fcdev/docs/`,并给出对应目标的 `npx fcdev docs <主题>` |
59
- | `src/hello.c` 或 `src/hello.s` | 示例程序 |
60
-
61
- 目录名以 `_` 开头的是公共文件目录,不是模板,目前只有 `_common/gitignore`。
62
-
63
53
  四个模板:
64
54
 
65
55
  | 模板 | hello world |
@@ -68,7 +58,3 @@ npm create fcdev@latest [目录] [-- 选项]
68
58
  | `nes-asm` | 同样的行为,汇编直接写 PPU 寄存器,`.include "fcnes.inc"`,导出 `_main` |
69
59
  | `sb2000-c` | `sb_puts` 显示英文与中文(GB2312)各一行,`sb_getkey` 等键后返回 |
70
60
  | `sb2000-asm` | 同样的行为,汇编调用 `_sb_puts`、`_sb_getkey`,导出 `_main` |
71
-
72
- ## 5. 新增模板
73
-
74
- 新增机型的目标后,在 `templates/` 下加 `<目标>-c` 与 `<目标>-asm` 两个目录,写 `template.json`、`README.md` 与示例程序;目标需要额外脚本或提示时写进 `template.json`。模板必须能用 `fcdev build` 构建成功,`npm run release:verify` 会逐个验证,见 [09-发布](09-发布.md)。
@@ -1,6 +1,6 @@
1
- # NES 目标
1
+ # NES 开发指南
2
2
 
3
- NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它之上加了一个辅助库 `fcnes` 和 ASCII 字库,使 hello 程序保持单文件。目标目录是 [packages/fcdev/targets/nes](../../targets/nes),字段含义见 [03-目标规范](../03-目标规范.md)。
3
+ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它之上加了一个辅助库 `fcnes` 和 ASCII 字库,使 hello 程序保持单文件。目标的定义与运行库随 `fcdev` 包安装,在包里的 `targets/nes/` 下。
4
4
 
5
5
  ## 1. 目标定义
6
6
 
@@ -39,14 +39,9 @@ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它
39
39
 
40
40
  ## 4. 字库
41
41
 
42
- - 字库数据来自公有领域的 `font8x8_basic`(Daniel Hepper,源自 IBM 公共领域 VGA 字体),原文件保留在 `chr/font8x8_basic.h`,已转成 `chr/ascii-8x8.chr`(ASCII `$20` 到 `$7F` 的 8×8 字模,共 1536 字节)。
43
42
  - `src/nes-font.s` 把字库放进 `CHARS` 段:前 `$200` 字节留空(对应 `$20` 之前的 32 个图块),之后是字模。
44
43
  - 目标选项 `font`(布尔,默认 `true`)为 `true` 时链接 `lib/nes-font.o`。在 `fcdev.json` 里写 `"targetOptions": { "font": false }` 可关闭,由程序自己提供 CHR 数据。
45
44
 
46
- ## 5. 运行库
45
+ ## 5. 运行
47
46
 
48
- `lib-build.json` 把 `src/fcnes.s` 编成 `lib/fcnes.lib`,把 `src/nes-font.s` 编成 `lib/nes-font.o`,`.incbin` 的搜索目录是 `chr`。构建方法见 [03-目标规范](../03-目标规范.md) 第 5 节。
49
-
50
- ## 6. 运行
51
-
52
- `npx fcdev run` 启动模拟器直接加载 `.nes`,不需要固件。验证记录见 [08-测试与验证](../08-测试与验证.md):NES hello 在模拟器里截图核对,屏幕上显示 `HELLO, NES!`。
47
+ `npx fcdev run` 启动 Ember 直接加载 `.nes`,不需要固件;`--debug` 启动调试模式,程序载入后停在开机状态,继续用 `npx fcdev debug`,见 [02-模拟器与调试](../02-模拟器与调试.md)。验证方式:NES 程序在 Ember 的调试模式里运行 60 帧并截图。