fcdev 0.5.0 → 0.7.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.
- package/CHANGELOG.md +46 -22
- package/README.md +10 -10
- package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +16 -18
- package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +6 -6
- package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +3 -3
- package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +2 -2
- package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +68 -71
- package/docs/06-/345/217/215/346/261/207/347/274/226.md +3 -3
- package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +12 -9
- package/docs/09-/345/217/221/345/270/203.md +21 -22
- package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
- package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +7 -7
- package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +4 -1
- package/package.json +5 -3
- package/src/cli/args-parser.mjs +1 -1
- package/src/cli/commands/debug-command.mjs +20 -58
- package/src/cli/commands/run-command.mjs +36 -39
- package/src/cli/index.mjs +4 -4
- package/src/config/config-loader.mjs +1 -1
- package/src/disasm/disassembler.mjs +1 -1
- package/src/disasm/trace.mjs +4 -3
- package/src/docs/doc-topics.mjs +38 -38
- package/src/emulator/debug-cli.mjs +48 -0
- package/src/emulator/emulator-launcher.mjs +107 -29
- package/src/emulator/emulator-locator.mjs +7 -21
- package/src/emulator/index.mjs +5 -4
- package/src/emulator/sb2000-session.mjs +101 -0
- package/src/toolchain/toolchain-locator.mjs +2 -2
- package/targets/nes/lib/fcnes.lib +0 -0
- package/targets/nes/lib/nes-font.o +0 -0
- package/targets/nes/target.json +1 -1
- package/targets/sb2000/lib/crt0.o +0 -0
- package/targets/sb2000/lib/sb2000.lib +0 -0
- package/targets/sb2000/target.json +1 -1
- package/src/emulator/debug-client.mjs +0 -125
|
@@ -6,45 +6,44 @@
|
|
|
6
6
|
|
|
7
7
|
| 包 | 说明 |
|
|
8
8
|
| --- | --- |
|
|
9
|
-
|
|
|
10
|
-
|
|
|
11
|
-
| `fcdev` | 主包,对两个包写精确版本的 `optionalDependencies` |
|
|
9
|
+
| `fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
|
|
10
|
+
| `fcdev` | 主包,对工具链包写精确版本的 `optionalDependencies`,对 `ember-debug-sdk` 写精确版本的 `dependencies` |
|
|
12
11
|
| `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
|
|
12
|
+
| `ember-debug-sdk` | Ember 调试服务的客户端 SDK(含终端客户端与 MCP 服务),目录 `packages/ember-debug-sdk`;`fcdev` 的 `debug` 命令与 `run --debug` 经它连接 Ember,所以 `fcdev` 依赖它 |
|
|
13
13
|
|
|
14
|
-
- 四个包同一个版本号,由 `release-check` 检查;`fcdev`
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
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
18
|
- 每个包的 `package.json` 写 `license`、`engines`(`node >=22`)、`files`,不写 `repository`、`homepage`、`bugs`(源码不公开,写了也打不开)。作者与邮箱为 `sungbin`、`sungbin@3578.cn`。
|
|
19
19
|
|
|
20
20
|
## 2. 发布前提
|
|
21
21
|
|
|
22
22
|
1. 所有改动已提交。
|
|
23
|
-
2.
|
|
24
|
-
3.
|
|
25
|
-
4. `
|
|
26
|
-
5. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(四个包共用一份,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展与模拟器各有自己的 `CHANGELOG.md`(`vscode/`、`virtuanes/`),版本号独立,有改动才升。
|
|
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 没有随这些包发布。
|
|
27
26
|
|
|
28
27
|
## 3. 检查
|
|
29
28
|
|
|
30
29
|
`npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
|
|
31
30
|
|
|
32
|
-
- 四个包的版本一致,都写了 `license`,`fcdev`
|
|
31
|
+
- 四个包的版本一致,都写了 `license`,`fcdev` 对工具链包与 `ember-debug-sdk` 的依赖版本一致;工具链包的包名在 `fcdev` 的依赖里。
|
|
33
32
|
- `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
|
|
34
33
|
- 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
|
|
35
34
|
- `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
|
|
36
|
-
- 工具链包里的文件与 `manifest.json` 记录的 SHA-256
|
|
37
|
-
-
|
|
35
|
+
- 工具链包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
|
|
36
|
+
- `ember-debug-sdk` 已构建(`dist` 存在),发布内容含两个入口、命令行入口与类型声明。
|
|
38
37
|
- 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
|
|
39
38
|
|
|
40
39
|
`npm run release:verify` 做安装验证,见 [08-测试与验证](08-测试与验证.md) 第 6 节。
|
|
41
40
|
|
|
42
41
|
## 4. 发布顺序
|
|
43
42
|
|
|
44
|
-
|
|
43
|
+
先发被依赖的工具链包与调试 SDK,再发 `fcdev`,最后发 `create-fcdev`:
|
|
45
44
|
|
|
46
|
-
1.
|
|
47
|
-
2.
|
|
45
|
+
1. `fcdev-cc65`
|
|
46
|
+
2. `ember-debug-sdk`
|
|
48
47
|
3. `fcdev`
|
|
49
48
|
4. `create-fcdev`
|
|
50
49
|
|
|
@@ -58,8 +57,8 @@
|
|
|
58
57
|
| --- | --- | --- |
|
|
59
58
|
| `fcdev` | 71 | 64 kB |
|
|
60
59
|
| `create-fcdev` | 23 | 15 kB |
|
|
61
|
-
|
|
|
62
|
-
|
|
|
60
|
+
| `fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
|
|
61
|
+
| `ember-debug-sdk` | 30 | 88 kB |
|
|
63
62
|
|
|
64
63
|
体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
|
|
65
64
|
|
|
@@ -69,8 +68,8 @@
|
|
|
69
68
|
|
|
70
69
|
| 命令 | 作用 |
|
|
71
70
|
| --- | --- |
|
|
72
|
-
| `npm run release:prepare -- <版本号>` |
|
|
73
|
-
| `npm run release:publish -- --dry-run` |
|
|
74
|
-
| `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、四个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4
|
|
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 在终端里询问 |
|
|
75
74
|
|
|
76
75
|
两个命令都可以加 `--allow-dirty`,允许工作区有未提交的改动,只用于演练。
|
|
@@ -49,4 +49,4 @@ NES(任天堂红白机)目标复用 `cc65` 自带的 `nes` 目标,在它
|
|
|
49
49
|
|
|
50
50
|
## 6. 运行
|
|
51
51
|
|
|
52
|
-
`npx fcdev run`
|
|
52
|
+
`npx fcdev run` 启动 Ember 直接加载 `.nes`,不需要固件;`--debug` 启动调试模式,程序载入后停在开机状态,继续用 `npx fcdev debug`,见 [05-模拟器与调试](../05-模拟器与调试.md)。验证记录见 [08-测试与验证](../08-测试与验证.md):NES 程序在 Ember 的调试模式里运行 60 帧并截图。
|
|
@@ -127,10 +127,10 @@ int main(void)
|
|
|
127
127
|
```bash
|
|
128
128
|
npx fcdev build src # 生成 build/sb2000/<NAME>.EXE
|
|
129
129
|
npx fcdev disk src # 另外生成 build/sb2000/<NAME>.img,软盘里只有这个程序
|
|
130
|
-
npx fcdev run src #
|
|
130
|
+
npx fcdev run src # 构建后在 Ember 里运行(需要 firmware);加 --debug 停在开机状态
|
|
131
131
|
```
|
|
132
132
|
|
|
133
|
-
`npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS
|
|
133
|
+
`npx fcdev run` 需要在 `fcdev.json` 里用 `firmware` 指定 BIOS 文件(仓库里有一份:`reference/rom/SB2K_BIOS.NES`),没有设置时在构建之前报错。它把程序做成磁盘镜像挂到软驱,开机后自动在 SB-DOS 里跳过日期与时间、输入程序名运行(程序名只能用字母与数字);`--debug` 停在开机状态,由自己用 `fcdev debug` 操作,细节见 [05-模拟器与调试](../05-模拟器与调试.md) 第 3 节与第 7 节。本文下面写到的调试操作用 Ember 调试服务的请求表示。
|
|
134
134
|
|
|
135
135
|
## 6. 头文件与函数
|
|
136
136
|
|
|
@@ -228,11 +228,11 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
|
228
228
|
| `copy` | 复制文件(文件不超过 64K) | `cp 源 目标` |
|
|
229
229
|
| `peek` | 按十六进制偏移读文件 30 字节 | `peek 文件名 偏移` |
|
|
230
230
|
| `poke` | 按十六进制偏移把文字写进已有文件(最长 60 个字符,大写) | `poke 文件名 偏移 文字` |
|
|
231
|
-
| `pad` | 等手柄按键,显示键码与两个手柄的状态 | `pad
|
|
232
|
-
| `mouse` | 复位鼠标、设坐标范围,等 250 帧后显示坐标 | `mouse
|
|
231
|
+
| `pad` | 等手柄按键,显示键码与两个手柄的状态 | `pad`(模拟器里用调试请求 `input.pad port=0 buttons=掩码` 按键) |
|
|
232
|
+
| `mouse` | 复位鼠标、设坐标范围,等 250 帧后显示坐标 | `mouse`(模拟器里用调试请求 `input.mouse kind=move dx=横向 dy=纵向` 移动) |
|
|
233
233
|
| `play` | 把 NES 游戏装入并运行(mapper 0 与 4,PRG、CHR 各不超过 128K) | `play 文件名.nes`(放进软盘镜像的文件名要符合 8.3) |
|
|
234
234
|
| `newcall` | 调用 BIOS 里新增的系统调用 $35,显示扩展版本号;原始 BIOS 不支持时显示 NOT SUPPORTED(演示给自己修改的 BIOS 做功能检测) | `newcall` |
|
|
235
|
-
| `syscall` | 系统调用实验:由调试器把功能号和参数写进 ERAM $7E00 的请求块,程序代为调用并写回结果,用来在模拟器里核对没有封装的系统服务 | `syscall
|
|
235
|
+
| `syscall` | 系统调用实验:由调试器把功能号和参数写进 ERAM $7E00 的请求块,程序代为调用并写回结果,用来在模拟器里核对没有封装的系统服务 | `syscall`(之后用调试请求 `inspector.writeMemory space=cpu address=0x7E00 bytes=[...]` 写请求块,格式见源码文件头) |
|
|
236
236
|
|
|
237
237
|
## 11. 限制与没做过的事
|
|
238
238
|
|
|
@@ -252,8 +252,8 @@ npx fcdev run src # 构建,挂载镜像,在模拟器里运行
|
|
|
252
252
|
|
|
253
253
|
## 12. 运行库的测试
|
|
254
254
|
|
|
255
|
-
运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及直接操作硬件的 `dma.c`、`ppu.c`、`timer.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12
|
|
255
|
+
运行库的每个函数都在模拟器里测过:`packages/fcdev/test/sb2000-library.test.mjs` 按模块运行 `test/fixtures/sb2000/` 下的测试程序(`system.c`、`memory.c`、`text.c`、`input.c`、`file-read.c`、`file-write.c`、`dir.c`、`disk.c`、`math.c`、`sound.c`、`display.c`、`peripheral.c`,以及直接操作硬件的 `dma.c`、`ppu.c`、`timer.c`,以及换页的 `bank.c`、`bank-pages.c`、`bank-top.c`),公共部分是 `sb2000-runner.mjs` 与 `sb-test.h`。测试程序用 `SB_CHECK`、`SB_CHECK_EQ` 记录检查结果,结束时调用 `sb_test_done`,需要宿主操作(按键、手柄、鼠标)时调用 `sb_test_sync` 停下等脚本;脚本读出结果并断言,文件与磁盘类测试还把镜像读回,用独立的 FAT12 解析核对。测试经 Ember 的调试服务运行:`sb2000-runner.mjs` 随机取空闲端口启动 Ember,依次添加 BIOS(环境变量 `FCDEV_TEST_FIRMWARE`,没有时用仓库里的 `reference/rom/SB2K_BIOS.NES`)、开机、放入镜像,运行到 SB-DOS 询问日期,回车跳过后输入程序名;按键用 `input.key`,手柄与鼠标用 `input.pad`、`input.mouse`,读内存用 `inspector.readMemory`,存回镜像用 `media.floppySave`,截图用 `output.screenshot`,结束时只结束自己启动的 Ember。需要 Ember(环境变量 `FCDEV_EMULATOR`)、cc65 与已构建的调试 SDK,缺一整组跳过。
|
|
256
256
|
|
|
257
|
-
停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`
|
|
257
|
+
停靠点用写断点实现:`sb_test_done`、`sb_test_sync` 往全局变量 `sb_test_stop` 写 1、2,脚本对这个地址设写断点(`inspector.addBreakpoint kind=write`),再读它的值判断停在哪里。不对函数入口设执行断点,是因为 DOS 外壳的某个等待循环可能正好经过同一地址,每转一圈停一次,模拟器几乎不前进(实测遇到过,表现为程序像是没启动)。窗口里的文件头不是 `AA 55` 时的停止(DOS 外壳写同一地址)会被忽略,`crt0.s` 清 `BSS` 时写的 0 也会被忽略。
|
|
258
258
|
|
|
259
259
|
接口检查与参考文档的测试在 `test/sb2000-api.test.mjs`,`fcdev api` 命令的测试在 `packages/fcdev/test/api-command.test.mjs`。
|
|
@@ -24,7 +24,10 @@
|
|
|
24
24
|
|
|
25
25
|
| 事项 | 说明 |
|
|
26
26
|
| --- | --- |
|
|
27
|
-
| 内核集成进 VS Code 面板 |
|
|
27
|
+
| 内核集成进 VS Code 面板 | 只要 Ember 的调试服务协议不变,`fcdev` 不用改 |
|
|
28
|
+
| 学习机 hello 的屏幕文字核对 | `fcdev run` 已能在 Ember 里运行学习机程序,运行库测试也已恢复;还没有把 C、汇编 hello 运行后的屏幕文字核对做成自动测试用例 |
|
|
29
|
+
| 已有 Ember 时 `fcdev run` 载入不进程序 | Ember 单实例,第二个进程只把已有窗口提到前面,不处理 `--cartridge`;需要 Ember 的 `second-instance` 处理它,或 `fcdev` 改用已开启的调试服务载入 |
|
|
30
|
+
| 存档(`savestate`、`loadstate`) | 旧模拟器有、Ember 没有,已登记在 Ember 的待办里,做完后通过 `fcdev debug call` 直接可用 |
|
|
28
31
|
| 外设读数与真机对齐 | `hwtest` 在真机与模拟器上仍有差异的读数(`$4015` 位 4、`$4022` 开机值、`$4026`、`$4016`、`$4017`、`$4033` 位 6、`$3FFF`),具体数值见 [03-硬件说明](sb2000/03-硬件说明.md) 的“真机与模拟器仍有差异的行为”;程序不应依赖这些值,是否对齐由用户决定。|
|
|
29
32
|
| `runnes` 与 `play` 的 DMA 写法 | 两个程序借用程序窗口 2(`$A000`)做 DMA 目的,真机上失败,模拟器对齐真机后也失败(`runnes` 现在用库函数 `sb_dma_to_cpu`,目的在窗口时函数直接返回出错、不复制);改成先 DMA 到 ERAM 缓冲再用 CPU 搬(参考 `apps/sb2000/bbk-loader`) |
|
|
30
33
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fcdev",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "6502 兼容机(NES、学习机等)的开发工具:用 cc65 构建 C 与汇编程序",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "sungbin <sungbin@3578.cn>",
|
|
@@ -30,8 +30,10 @@
|
|
|
30
30
|
"src",
|
|
31
31
|
"targets"
|
|
32
32
|
],
|
|
33
|
+
"dependencies": {
|
|
34
|
+
"ember-debug-sdk": "0.7.0"
|
|
35
|
+
},
|
|
33
36
|
"optionalDependencies": {
|
|
34
|
-
"
|
|
35
|
-
"@rujianjs/fcdev-emulator": "0.5.0"
|
|
37
|
+
"fcdev-cc65": "0.7.0"
|
|
36
38
|
}
|
|
37
39
|
}
|
package/src/cli/args-parser.mjs
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
// 备注:debug
|
|
7
|
+
// 备注:debug 命令把命令名之后的全部参数原样交给 ember-debug,不再解析选项。
|
|
8
8
|
// ------------------------------------------------------------------------
|
|
9
9
|
import { FcdevError } from '../shared/index.mjs';
|
|
10
10
|
|
|
@@ -1,73 +1,35 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:debug-command.mjs
|
|
3
|
-
// 说明:debug
|
|
3
|
+
// 说明:debug 命令:把参数原样交给调试 SDK 的终端客户端 ember-debug,由它连接 Ember 的调试服务。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
//
|
|
7
|
+
// 备注:fcdev 不解析调试命令;端口取环境变量 FCDEV_DEBUG_PORT,默认 5699,找到 run --debug 启动的 Ember;
|
|
8
|
+
// ember-debug 的退出码原样作为 fcdev 的退出码,输出边读边转,watch 这类长时间运行的命令也能看到实时结果。
|
|
8
9
|
// ------------------------------------------------------------------------
|
|
9
|
-
import
|
|
10
|
-
import {
|
|
10
|
+
import { spawn } from 'node:child_process';
|
|
11
|
+
import { debugEnvironment, resolveDebugCli } from '../../emulator/index.mjs';
|
|
11
12
|
import { FcdevError } from '../../shared/index.mjs';
|
|
12
13
|
|
|
13
|
-
/** 耗时长的命令使用的应答超时,单位毫秒 */
|
|
14
|
-
const LONG_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
|
|
15
|
-
|
|
16
|
-
/** 耗时长的命令 */
|
|
17
|
-
const LONG_COMMANDS = new Set(['run', 'step']);
|
|
18
|
-
|
|
19
|
-
/** 命令里路径参数的位置(命令名之后的第几个词,从 1 起);disk 的路径可含空格,取剩余全部 */
|
|
20
|
-
const PATH_POSITIONS = {
|
|
21
|
-
shot: 1,
|
|
22
|
-
disk: 1,
|
|
23
|
-
trace: 1,
|
|
24
|
-
io: 1,
|
|
25
|
-
disklog: 1,
|
|
26
|
-
calllog: 1,
|
|
27
|
-
savestate: 1,
|
|
28
|
-
loadstate: 1,
|
|
29
|
-
};
|
|
30
|
-
|
|
31
|
-
/**
|
|
32
|
-
* 把命令里的相对路径换成绝对路径。
|
|
33
|
-
* @param {string[]} tokens 命令的各个词
|
|
34
|
-
* @param {string} cwd 终端当前目录
|
|
35
|
-
* @returns {string[]} 处理后的词
|
|
36
|
-
*/
|
|
37
|
-
export function resolveCommandPaths(tokens, cwd) {
|
|
38
|
-
const [name, ...rest] = tokens;
|
|
39
|
-
if (name === 'cdl' && rest[0] === 'save' && rest[1]) {
|
|
40
|
-
return [name, rest[0], path.resolve(cwd, rest[1]), ...rest.slice(2)];
|
|
41
|
-
}
|
|
42
|
-
if (name === 'tape' && (rest[0] === 'play' || rest[0] === 'rec') && rest[1]) {
|
|
43
|
-
return [name, rest[0], path.resolve(cwd, rest.slice(1).join(' '))];
|
|
44
|
-
}
|
|
45
|
-
const position = PATH_POSITIONS[name];
|
|
46
|
-
if (position === undefined || rest.length < position || rest[position - 1] === 'off') return tokens;
|
|
47
|
-
if (name === 'disk') return [name, path.resolve(cwd, rest.join(' '))];
|
|
48
|
-
const resolved = [...rest];
|
|
49
|
-
resolved[position - 1] = path.resolve(cwd, rest[position - 1]);
|
|
50
|
-
return [name, ...resolved];
|
|
51
|
-
}
|
|
52
|
-
|
|
53
14
|
/**
|
|
54
15
|
* 执行 debug 命令。
|
|
55
|
-
* @param {{positionals: string[], context: import('../index.mjs').CliContext}} input
|
|
56
|
-
* @returns {Promise<number>}
|
|
57
|
-
* @throws {FcdevError}
|
|
16
|
+
* @param {{positionals: string[], context: import('../index.mjs').CliContext}} input ember-debug 的各个参数与运行环境
|
|
17
|
+
* @returns {Promise<number>} ember-debug 的退出码
|
|
18
|
+
* @throws {FcdevError} 没有给命令,或终端客户端不可用
|
|
58
19
|
*/
|
|
59
20
|
export async function runDebugCommand({ positionals, context }) {
|
|
60
21
|
if (positionals.length === 0) {
|
|
61
|
-
throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug status、npx fcdev debug
|
|
62
|
-
}
|
|
63
|
-
const port = Number(context.env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
|
|
64
|
-
const tokens = resolveCommandPaths(positionals, context.cwd);
|
|
65
|
-
const client = await DebugClient.connect({ port });
|
|
66
|
-
try {
|
|
67
|
-
const reply = await client.send(tokens.join(' '), { timeoutMs: LONG_COMMANDS.has(tokens[0]) ? LONG_COMMAND_TIMEOUT_MS : undefined });
|
|
68
|
-
context.stdout.write(`${[reply.head, ...reply.lines].join('\n')}\n`);
|
|
69
|
-
return reply.ok ? 0 : 1;
|
|
70
|
-
} finally {
|
|
71
|
-
client.close();
|
|
22
|
+
throw new FcdevError('debug 需要一条调试命令', { code: 'ARGUMENT_INVALID', hint: '例如:npx fcdev debug call runtime.status、npx fcdev debug screenshot out.png;npx fcdev debug --help 查看全部命令' });
|
|
72
23
|
}
|
|
24
|
+
const cli = resolveDebugCli();
|
|
25
|
+
const env = debugEnvironment(context.env);
|
|
26
|
+
return new Promise((resolve, reject) => {
|
|
27
|
+
const child = spawn(process.execPath, [cli, ...positionals], { cwd: context.cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
|
|
28
|
+
child.stdout.setEncoding('utf8');
|
|
29
|
+
child.stderr.setEncoding('utf8');
|
|
30
|
+
child.stdout.on('data', (chunk) => context.stdout.write(chunk));
|
|
31
|
+
child.stderr.on('data', (chunk) => context.stderr.write(chunk));
|
|
32
|
+
child.once('error', (error) => reject(new FcdevError('无法运行调试 SDK 的终端客户端', { code: 'DEBUG_CLI_START_FAILED', cause: error })));
|
|
33
|
+
child.once('close', (code) => resolve(code ?? 1));
|
|
34
|
+
});
|
|
73
35
|
}
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:run-command.mjs
|
|
3
|
-
// 说明:run
|
|
3
|
+
// 说明:run 命令:构建程序后在 Ember 里运行;--debug 时启动调试模式,由 debug 命令继续操作。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
|
-
// 备注:运行方案由目标的 run 字段声明:rom 直接加载产物;firmware-disk
|
|
8
|
-
//
|
|
7
|
+
// 备注:运行方案由目标的 run 字段声明:rom 直接加载产物;firmware-disk(学习机)加载 fcdev.json 的 firmware 指定的固件,
|
|
8
|
+
// 把程序放进磁盘镜像挂到软驱并开机,自由模式再在 SB-DOS 里输入程序名运行,调试模式停在开机状态。
|
|
9
9
|
// ------------------------------------------------------------------------
|
|
10
10
|
import path from 'node:path';
|
|
11
|
-
import { buildDiskImage, buildPath } from '../../build/index.mjs';
|
|
11
|
+
import { buildDiskImage, buildPath, createBuildPlan } from '../../build/index.mjs';
|
|
12
12
|
import { DEFAULT_DEBUG_PORT, launchEmulator, locateEmulator } from '../../emulator/index.mjs';
|
|
13
13
|
import { FcdevError } from '../../shared/index.mjs';
|
|
14
14
|
|
|
@@ -16,53 +16,50 @@ import { FcdevError } from '../../shared/index.mjs';
|
|
|
16
16
|
* 执行 run 命令。
|
|
17
17
|
* @param {{positionals: string[], options: {target?: string, debug: boolean, port?: number}, context: import('../index.mjs').CliContext}} input 参数与运行环境
|
|
18
18
|
* @returns {Promise<number>} 退出码
|
|
19
|
-
* @throws {FcdevError}
|
|
19
|
+
* @throws {FcdevError} 目标没有运行方案、学习机没有配置固件、找不到 Ember 或构建失败
|
|
20
20
|
*/
|
|
21
21
|
export async function runRunCommand({ positionals, options, context }) {
|
|
22
22
|
if (positionals.length > 1) {
|
|
23
23
|
throw new FcdevError('run 只接受一个路径参数', { code: 'ARGUMENT_INVALID', hint: '用法:npx fcdev run [目录或文件]' });
|
|
24
24
|
}
|
|
25
|
+
const input = { pathArg: positionals[0], cwd: context.cwd, targetOverride: options.target, env: context.env };
|
|
26
|
+
const { target, config } = createBuildPlan(input);
|
|
27
|
+
if (!target.run) {
|
|
28
|
+
throw new FcdevError(`目标 ${target.name} 没有运行方案`, { code: 'TARGET_NO_RUN' });
|
|
29
|
+
}
|
|
30
|
+
const withFirmware = target.run.mode === 'firmware-disk';
|
|
31
|
+
if (withFirmware && !config.firmware) {
|
|
32
|
+
throw new FcdevError(`${target.name} 目标运行需要固件,fcdev.json 里没有设置 firmware`, {
|
|
33
|
+
code: 'FIRMWARE_MISSING',
|
|
34
|
+
hint: '在 fcdev.json 里用 firmware 指向学习机的 BIOS 文件(iNES 格式),例如 "firmware": "SB2K_BIOS.NES"',
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
const emulator = locateEmulator({ configured: config.emulator, env: context.env });
|
|
38
|
+
const port = options.port ?? DEFAULT_DEBUG_PORT;
|
|
39
|
+
|
|
25
40
|
const reporter = {
|
|
26
41
|
log: (message) => context.stdout.write(`${message}\n`),
|
|
27
42
|
write: (text) => context.stderr.write(text),
|
|
28
43
|
};
|
|
29
|
-
const { plan, result } = await buildPath(
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
)
|
|
33
|
-
const run = plan.target.run;
|
|
34
|
-
if (!run) {
|
|
35
|
-
throw new FcdevError(`目标 ${plan.target.name} 没有运行方案`, { code: 'TARGET_NO_RUN' });
|
|
36
|
-
}
|
|
37
|
-
const emulator = locateEmulator({ configured: plan.config.emulator, env: context.env });
|
|
38
|
-
const port = options.port ?? DEFAULT_DEBUG_PORT;
|
|
39
|
-
|
|
40
|
-
if (run.mode === 'rom') {
|
|
41
|
-
const { pid, client } = await launchEmulator({ executable: emulator.executable, romFile: result.outputFile, debug: options.debug, port });
|
|
42
|
-
client?.close();
|
|
43
|
-
context.stdout.write(`已启动模拟器(进程 ${pid}),加载 ${result.outputFile}\n`);
|
|
44
|
-
} else {
|
|
45
|
-
if (!plan.config.firmware) {
|
|
46
|
-
throw new FcdevError(`目标 ${plan.target.name} 的运行需要固件(BIOS)`, {
|
|
47
|
-
code: 'FIRMWARE_MISSING',
|
|
48
|
-
hint: '在 fcdev.json 里用 firmware 指定固件文件;fcdev 不提供任何 BIOS 或 ROM',
|
|
49
|
-
});
|
|
50
|
-
}
|
|
44
|
+
const { plan, result } = await buildPath(input, reporter);
|
|
45
|
+
let launch;
|
|
46
|
+
let description;
|
|
47
|
+
if (withFirmware) {
|
|
51
48
|
const { imageFile } = buildDiskImage(plan, result);
|
|
52
|
-
const
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
} finally {
|
|
59
|
-
client.close();
|
|
60
|
-
}
|
|
61
|
-
context.stdout.write(`已启动模拟器(进程 ${pid}),固件 ${plan.config.firmware},磁盘镜像 ${imageFile}\n`);
|
|
62
|
-
context.stdout.write(`等 DOS 启动后,在提示符下输入 ${path.basename(result.outputFile, path.extname(result.outputFile))} 运行程序\n`);
|
|
49
|
+
const programName = path.basename(result.outputFile, path.extname(result.outputFile));
|
|
50
|
+
launch = { sb2000: { firmware: config.firmware, diskImage: imageFile, programName } };
|
|
51
|
+
description = `磁盘镜像 ${imageFile}(程序 ${programName})`;
|
|
52
|
+
} else {
|
|
53
|
+
launch = { romFile: result.outputFile };
|
|
54
|
+
description = result.outputFile;
|
|
63
55
|
}
|
|
56
|
+
const { pid, client } = await launchEmulator({ executable: emulator.executable, ...launch, debug: options.debug, port });
|
|
57
|
+
client?.close();
|
|
58
|
+
context.stdout.write(`已启动 Ember(进程 ${pid}),加载 ${description}\n`);
|
|
64
59
|
if (options.debug) {
|
|
65
|
-
context.stdout.write(
|
|
60
|
+
context.stdout.write(withFirmware
|
|
61
|
+
? `调试模式:端口 ${port},固件已加载、磁盘已放入软驱、整机已开机,但没有运行;程序要在 SB-DOS 里输入程序名才会运行,继续操作用 debug 命令,例如 npx fcdev debug call runtime.run frames=60 wait=true\n`
|
|
62
|
+
: `调试模式:端口 ${port},程序已载入并上电,但没有运行;继续操作用 debug 命令,例如 npx fcdev debug call runtime.run frames=60 wait=true\n`);
|
|
66
63
|
}
|
|
67
64
|
return 0;
|
|
68
65
|
}
|
package/src/cli/index.mjs
CHANGED
|
@@ -47,10 +47,10 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
|
|
|
47
47
|
|
|
48
48
|
命令:
|
|
49
49
|
build [目录或文件] 构建:无参数为当前目录;目录整体构成一个程序;文件单独构成一个程序
|
|
50
|
-
run [目录或文件]
|
|
50
|
+
run [目录或文件] 构建后在 Ember 里运行(--debug 启动调试模式)
|
|
51
51
|
disk [目录或文件] 构建后把程序放进磁盘镜像(只有支持磁盘的目标可用)
|
|
52
52
|
disasm <文件> 反汇编 NES 程序或平铺二进制为 ca65 源码,并回读校验
|
|
53
|
-
debug
|
|
53
|
+
debug <参数> 交给 Ember 调试 SDK 的终端客户端 ember-debug,如 debug call runtime.status、debug screenshot out.png
|
|
54
54
|
sync 生成 IDE 的 C/C++ 配置
|
|
55
55
|
info [--json] 显示目标、工具链与头文件目录
|
|
56
56
|
api [词] [--json] 查询目标的 C 接口文档:函数名、模块名、$功能号或关键词;不带词列出全部模块
|
|
@@ -58,7 +58,7 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
|
|
|
58
58
|
|
|
59
59
|
选项:
|
|
60
60
|
--target <名> 指定目标,覆盖 fcdev.json
|
|
61
|
-
--debug run
|
|
61
|
+
--debug run 以调试模式启动 Ember
|
|
62
62
|
--port <端口> run 的调试端口,默认 5699;debug 命令读环境变量 FCDEV_DEBUG_PORT,默认也是 5699
|
|
63
63
|
--json info 输出机器可读格式
|
|
64
64
|
|
|
@@ -67,7 +67,7 @@ disasm 的选项:
|
|
|
67
67
|
--base <地址> 平铺二进制的加载地址(十六进制)
|
|
68
68
|
--entry <地址> 追踪代码的入口,可重复;iNES 会自动使用中断向量
|
|
69
69
|
--cdl <文件> CDL(FCEUX、Mesen 格式),代码段的起点也当作入口
|
|
70
|
-
--trace <文件>
|
|
70
|
+
--trace <文件> Ember 的 inspector.traceStart(instruction)记录的指令轨迹,执行过的指令地址都当作入口
|
|
71
71
|
--symbols <文件> 符号文件,每行“名字 = $地址”
|
|
72
72
|
--out <目录> 输出目录,默认 build/disasm/<文件名>
|
|
73
73
|
-h, --help 显示帮助
|
|
@@ -39,7 +39,7 @@ const KEY_TYPES = {
|
|
|
39
39
|
* @property {string[]} include 额外头文件目录的绝对路径
|
|
40
40
|
* @property {string|undefined} toolchain 自备 cc65 根目录的绝对路径
|
|
41
41
|
* @property {string|undefined} firmware 固件文件的绝对路径
|
|
42
|
-
* @property {string|undefined} emulator
|
|
42
|
+
* @property {string|undefined} emulator Ember 可执行文件的路径
|
|
43
43
|
* @property {Record<string, unknown>} targetOptions 目标专用选项
|
|
44
44
|
*/
|
|
45
45
|
|
|
@@ -47,7 +47,7 @@ function detectFormat(buffer, format) {
|
|
|
47
47
|
|
|
48
48
|
/**
|
|
49
49
|
* 反汇编一个文件,并回读校验。
|
|
50
|
-
* @param {{inputFile: string, format?: string, base?: number, entries?: number[], cdlFile?: string, traceFile?: string, symbolsFile?: string, outDir: string, toolchain: import('../toolchain/index.mjs').Toolchain, includes?: string[]}} input 输入文件、格式、加载地址、入口、CDL
|
|
50
|
+
* @param {{inputFile: string, format?: string, base?: number, entries?: number[], cdlFile?: string, traceFile?: string, symbolsFile?: string, outDir: string, toolchain: import('../toolchain/index.mjs').Toolchain, includes?: string[]}} input 输入文件、格式、加载地址、入口、CDL、Ember 轨迹、符号文件、输出目录、工具链与 da65 要读的符号定义文件
|
|
51
51
|
* @returns {Promise<DisassemblyReport>} 报告
|
|
52
52
|
* @throws {FcdevError} 输入不合法、da65 失败,或回读校验不一致
|
|
53
53
|
*/
|
package/src/disasm/trace.mjs
CHANGED
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:trace.mjs
|
|
3
|
-
//
|
|
3
|
+
// 说明:读取 Ember 的 inspector.traceStart(kind 为 instruction)记录的指令轨迹:每行是 nestest 日志的写法,行首是四位十六进制的指令地址。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
7
|
// 备注:轨迹里的每个地址都是被真实执行过的指令开头,比 CDL 的“代码字节”更精确;用作追踪代码的入口。
|
|
8
|
+
// io、irq 与调用记录的行不是指令行,一律忽略;只认 Ember 的格式,不兼容旧模拟器的 T 行。
|
|
8
9
|
// ------------------------------------------------------------------------
|
|
9
10
|
|
|
10
|
-
/**
|
|
11
|
-
const TRACE_LINE = /^
|
|
11
|
+
/** 指令行:四位十六进制的地址、两个空格,后面是至少一个两位十六进制的字节(调用记录的“8123 A:01”不符合) */
|
|
12
|
+
const TRACE_LINE = /^([0-9A-F]{4}) {2}[0-9A-F]{2}(?: |$)/;
|
|
12
13
|
|
|
13
14
|
/**
|
|
14
15
|
* 取出轨迹里被执行过的指令地址。
|
package/src/docs/doc-topics.mjs
CHANGED
|
@@ -1,38 +1,38 @@
|
|
|
1
|
-
// ------------------------------------------------------------------------
|
|
2
|
-
// 名称:doc-topics.mjs
|
|
3
|
-
// 说明:开发文档的主题登记表:每份文档的主题名、相对 docs 目录的文件、标题和一句话说明。
|
|
4
|
-
// 作者:sungbin
|
|
5
|
-
// 邮箱:sungbin@3578.cn
|
|
6
|
-
// 日期:2026-11-11
|
|
7
|
-
// 备注:新增、改名或删除文档时同步改这里与 docs/01-软件架构设计.md 第 9 节;主题名只用小写字母、数字与连字符,便于在任何终端里输入。
|
|
8
|
-
// ------------------------------------------------------------------------
|
|
9
|
-
|
|
10
|
-
/**
|
|
11
|
-
* @typedef {object} DocTopic
|
|
12
|
-
* @property {string} topic 主题名
|
|
13
|
-
* @property {string} file 文件路径,用 / 分隔;默认相对 docs 目录,`inPackage` 为 true 时相对主包根目录
|
|
14
|
-
* @property {boolean} [inPackage] 文件不在 docs 目录里、而在主包其他目录下(如目标目录里由头文件生成的接口参考)
|
|
15
|
-
* @property {string} title 标题
|
|
16
|
-
* @property {string} summary 一句话说明
|
|
17
|
-
*/
|
|
18
|
-
|
|
19
|
-
/** @type {DocTopic[]} */
|
|
20
|
-
export const DOC_TOPICS = [
|
|
21
|
-
{ topic: 'architecture', file: '01-软件架构设计.md', title: '软件架构设计', summary: '包的划分、目录、分层规则、设计决策与文档清单' },
|
|
22
|
-
{ topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
|
|
23
|
-
{ topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
|
|
24
|
-
{ topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与工具链包' },
|
|
25
|
-
{ topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '
|
|
26
|
-
{ topic: 'disasm', file: '06-反汇编.md', title: '反汇编', summary: '反汇编前端的流程、输入与限制' },
|
|
27
|
-
{ topic: 'create', file: '07-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
|
|
28
|
-
{ topic: 'testing', file: '08-测试与验证.md', title: '测试与验证', summary: '测试分层、环境变量与运行方法' },
|
|
29
|
-
{ topic: 'release', file: '09-发布.md', title: '发布', summary: '发布顺序、前提与检查' },
|
|
30
|
-
{ topic: 'vscode', file: '10-VS Code扩展.md', title: 'VS Code 扩展', summary: '智能感知、语法高亮、项目信息来源、目录分层与打包' },
|
|
31
|
-
{ topic: 'nes', file: 'nes/01-NES目标.md', title: 'NES 目标', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
|
|
32
|
-
{ topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
|
|
33
|
-
{ topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
|
|
34
|
-
{ topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
|
|
35
|
-
{ topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
|
|
36
|
-
{ topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
|
|
37
|
-
{ topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
|
|
38
|
-
];
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:doc-topics.mjs
|
|
3
|
+
// 说明:开发文档的主题登记表:每份文档的主题名、相对 docs 目录的文件、标题和一句话说明。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-11
|
|
7
|
+
// 备注:新增、改名或删除文档时同步改这里与 docs/01-软件架构设计.md 第 9 节;主题名只用小写字母、数字与连字符,便于在任何终端里输入。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* @typedef {object} DocTopic
|
|
12
|
+
* @property {string} topic 主题名
|
|
13
|
+
* @property {string} file 文件路径,用 / 分隔;默认相对 docs 目录,`inPackage` 为 true 时相对主包根目录
|
|
14
|
+
* @property {boolean} [inPackage] 文件不在 docs 目录里、而在主包其他目录下(如目标目录里由头文件生成的接口参考)
|
|
15
|
+
* @property {string} title 标题
|
|
16
|
+
* @property {string} summary 一句话说明
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/** @type {DocTopic[]} */
|
|
20
|
+
export const DOC_TOPICS = [
|
|
21
|
+
{ topic: 'architecture', file: '01-软件架构设计.md', title: '软件架构设计', summary: '包的划分、目录、分层规则、设计决策与文档清单' },
|
|
22
|
+
{ topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
|
|
23
|
+
{ topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
|
|
24
|
+
{ topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与工具链包' },
|
|
25
|
+
{ topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、Ember 定位、调试服务与 debug 命令' },
|
|
26
|
+
{ topic: 'disasm', file: '06-反汇编.md', title: '反汇编', summary: '反汇编前端的流程、输入与限制' },
|
|
27
|
+
{ topic: 'create', file: '07-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
|
|
28
|
+
{ topic: 'testing', file: '08-测试与验证.md', title: '测试与验证', summary: '测试分层、环境变量与运行方法' },
|
|
29
|
+
{ topic: 'release', file: '09-发布.md', title: '发布', summary: '发布顺序、前提与检查' },
|
|
30
|
+
{ topic: 'vscode', file: '10-VS Code扩展.md', title: 'VS Code 扩展', summary: '智能感知、语法高亮、项目信息来源、目录分层与打包' },
|
|
31
|
+
{ topic: 'nes', file: 'nes/01-NES目标.md', title: 'NES 目标', summary: 'NES 目标的内存与映射器、fcnes 函数、字库、运行' },
|
|
32
|
+
{ topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
|
|
33
|
+
{ topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
|
|
34
|
+
{ topic: 'hardware', file: 'sb2000/03-硬件说明.md', title: 'SB2000 硬件说明', summary: 'SB2000 的硬件行为与寄存器' },
|
|
35
|
+
{ topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
|
|
36
|
+
{ topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
|
|
37
|
+
{ topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
|
|
38
|
+
];
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:debug-cli.mjs
|
|
3
|
+
// 说明:debug 命令的底层:找到调试 SDK 随包提供的终端客户端 ember-debug,并决定它找 Ember 调试服务的环境变量。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-15
|
|
7
|
+
// 备注:fcdev 自己不实现任何调试命令,全部交给 ember-debug;没有显式指定地址、令牌、端点文件或用户数据目录时,
|
|
8
|
+
// 按调试端口(环境变量 FCDEV_DEBUG_PORT,默认 5699)找到 fcdev 用 run --debug 启动的那个 Ember。
|
|
9
|
+
// ------------------------------------------------------------------------
|
|
10
|
+
import { existsSync } from 'node:fs';
|
|
11
|
+
import { fileURLToPath } from 'node:url';
|
|
12
|
+
import { FcdevError } from '../shared/index.mjs';
|
|
13
|
+
import { DEFAULT_DEBUG_PORT, debugUserDataDirectory } from './emulator-launcher.mjs';
|
|
14
|
+
|
|
15
|
+
/** 用户显式指定调试服务位置的环境变量,设置了任何一个就不再按端口推算 */
|
|
16
|
+
const EXPLICIT_ENV_NAMES = ['EMBER_DEBUG_URL', 'EMBER_DEBUG_TOKEN', 'EMBER_DEBUG_ENDPOINT', 'EMBER_USER_DATA'];
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* 调试 SDK 的终端客户端(ember-debug)的入口文件。
|
|
20
|
+
* @returns {string} 入口文件的绝对路径
|
|
21
|
+
* @throws {FcdevError} SDK 没有安装或没有构建
|
|
22
|
+
*/
|
|
23
|
+
export function resolveDebugCli() {
|
|
24
|
+
let file = null;
|
|
25
|
+
try {
|
|
26
|
+
file = fileURLToPath(new URL('./cli.js', import.meta.resolve('ember-debug-sdk')));
|
|
27
|
+
} catch {
|
|
28
|
+
// 下面统一报错
|
|
29
|
+
}
|
|
30
|
+
if (file === null || !existsSync(file)) {
|
|
31
|
+
throw new FcdevError('找不到调试 SDK(ember-debug-sdk)的终端客户端', {
|
|
32
|
+
code: 'DEBUG_SDK_MISSING',
|
|
33
|
+
hint: '在本仓库里先运行 npm run build -w packages/ember-debug-sdk;用 npm 安装的 fcdev 会自带',
|
|
34
|
+
});
|
|
35
|
+
}
|
|
36
|
+
return file;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* 运行终端客户端时用的环境变量。
|
|
41
|
+
* @param {NodeJS.ProcessEnv} env 当前环境变量
|
|
42
|
+
* @returns {NodeJS.ProcessEnv} 新的环境变量;没有显式指定位置时加上 fcdev 启动的 Ember 的用户数据目录
|
|
43
|
+
*/
|
|
44
|
+
export function debugEnvironment(env) {
|
|
45
|
+
if (EXPLICIT_ENV_NAMES.some((name) => env[name])) return env;
|
|
46
|
+
const port = Number(env.FCDEV_DEBUG_PORT) || DEFAULT_DEBUG_PORT;
|
|
47
|
+
return { ...env, EMBER_USER_DATA: debugUserDataDirectory(port) };
|
|
48
|
+
}
|