fcdev 0.5.0 → 0.6.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 +11 -1
- package/README.md +4 -4
- package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +11 -14
- package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +2 -2
- package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +1 -1
- 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 +6 -16
- package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +3 -3
- package/docs/09-/345/217/221/345/270/203.md +19 -25
- package/package.json +2 -3
- package/src/docs/doc-topics.mjs +1 -1
- package/src/emulator/emulator-locator.mjs +4 -18
- package/src/emulator/index.mjs +1 -1
- 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/sb2000/lib/crt0.o +0 -0
- package/targets/sb2000/lib/sb2000.lib +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,16 @@
|
|
|
1
1
|
# 更新记录
|
|
2
2
|
|
|
3
|
-
适用于 `fcdev`、`create-fcdev
|
|
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` 指定。
|
|
4
14
|
|
|
5
15
|
## 0.5.0(2026-11-13)
|
|
6
16
|
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# fcdev
|
|
2
2
|
|
|
3
|
-
6502 兼容机(NES、小霸王学习机等)的开发工具:用 cc65 把 C 或 ca65
|
|
3
|
+
6502 兼容机(NES、小霸王学习机等)的开发工具:用 cc65 把 C 或 ca65 汇编构建成机型对应的程序,可在模拟器里运行与调试,并能把已有程序反汇编回 ca65 源码。首批支持 NES 与小霸王学习机 SB2000,更多机型按“目标”扩展。
|
|
4
4
|
|
|
5
5
|
通常不需要手动安装:用 `npm create fcdev@latest` 创建项目时会自动装好。
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
npm install --save-dev fcdev
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
要求 Node.js 22 及以上。cc65
|
|
13
|
+
要求 Node.js 22 及以上。cc65 编译器在依赖包 `fcdev-cc65` 里,npm 会自动安装;也可以用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。模拟器不随包提供,`run` 与 `debug` 需要自备:用环境变量 `FCDEV_EMULATOR` 或 `fcdev.json` 的 `emulator` 指定,调试命令要求该模拟器支持同样的调试服务。
|
|
14
14
|
|
|
15
15
|
## 使用
|
|
16
16
|
|
|
@@ -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` | 空 |
|
|
68
|
+
| `emulator` | 空 | 模拟器的路径,不设时读环境变量 `FCDEV_EMULATOR` |
|
|
69
69
|
| `targetOptions` | 空 | 目标专用选项,如 NES 的 `font`(是否链接 ASCII 字库,默认 `true`)、SB2000 的 `banks`(大程序的库页个数,默认 0) |
|
|
70
70
|
|
|
71
71
|
## 目标
|
|
@@ -100,4 +100,4 @@ npx fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号
|
|
|
100
100
|
|
|
101
101
|
## 许可证
|
|
102
102
|
|
|
103
|
-
Apache-2.0。cc65 部分为 zlib
|
|
103
|
+
Apache-2.0。cc65 部分为 zlib 许可,随工具链包附带许可文件。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 软件架构设计
|
|
2
2
|
|
|
3
|
-
fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65
|
|
3
|
+
fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板和反汇编前端,运行与调试用的模拟器需要自备。用 C 或 ca65 汇编开发,构建出各机型的可运行程序。首批目标是 NES 与小霸王学习机 SB2000,之后按“目标”加入步步高、裕兴等机型。
|
|
4
4
|
|
|
5
5
|
本文说明包的划分、目录、分层规则和设计决策。各部分的细节见第 9 节列出的文档。
|
|
6
6
|
|
|
@@ -8,7 +8,7 @@ fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境
|
|
|
8
8
|
|
|
9
9
|
范围内:
|
|
10
10
|
|
|
11
|
-
- 命令行构建工具、目标定义、cc65
|
|
11
|
+
- 命令行构建工具、目标定义、cc65 工具链包、创建包与模板、反汇编前端。
|
|
12
12
|
- 首批目标:NES、SB2000;其他机型按 [03-目标规范](03-目标规范.md) 加入。
|
|
13
13
|
- VS Code 扩展的智能感知与语法高亮:见 [10-VS Code扩展](10-VS%20Code扩展.md)。
|
|
14
14
|
|
|
@@ -25,15 +25,15 @@ fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境
|
|
|
25
25
|
|
|
26
26
|
| 编号 | 决策 | 原因 |
|
|
27
27
|
| --- | --- | --- |
|
|
28
|
-
| D01 | 用 npm
|
|
29
|
-
| D02 | 包名:主包 `fcdev`,创建包 `create-fcdev`,工具链包
|
|
28
|
+
| D01 | 用 npm 包发布命令行、目标、模板与编译器 | 项目锁定版本;终端、CI 与 Copilot 都能构建,不依赖 VS Code |
|
|
29
|
+
| D02 | 包名:主包 `fcdev`,创建包 `create-fcdev`,工具链包 `fcdev-cc65`;三个包都不带作用域,目录名与包名相同 | `npm create fcdev` 会自动运行 `create-fcdev`;工具链包只被主包依赖,使用者不直接输入名字 |
|
|
30
30
|
| D03 | 命令行与库用 Node 22 的 ESM(`.mjs`)加 JSDoc,运行时无依赖,不需要构建步骤 | 发布内容就是源码,便于核对 |
|
|
31
|
-
| D04 | 用 npm workspaces
|
|
31
|
+
| D04 | 用 npm workspaces 管理多个包,发布的三个包同一个版本号,同步发布;主包对工具链包写精确版本;工作区里的 `ember-debug-sdk` 是 Ember 调试服务的客户端,版本独立,不属于这三个包 | 命令行、目标与编译器必须配套 |
|
|
32
32
|
| D05 | 一种机型是一个“目标”,是主包内 `targets/<名>/` 一个目录;新增机型只加目录,不改构建流程 | 多机型扩展 |
|
|
33
33
|
| D06 | 目标声明可选能力:磁盘镜像、模拟器运行;没有该能力的目标,对应命令明确报错 | NES 没有磁盘,学习机有 |
|
|
34
34
|
| D07 | 构建由 `fcdev` 自己判断增量,不用 `make` | Windows 上不必另装 `make` |
|
|
35
35
|
| D08 | 目标运行库在发布前用 `cc65`、`ca65`、`ar65` 编译成 `.lib` 随包发布(C 与汇编源码都可以,一个函数一个目标文件) | 目标文件格式与平台无关,使用者不必再编译库 |
|
|
36
|
-
| D09 |
|
|
36
|
+
| D09 | 工具链是体积较大的二进制,放在独立的包里,主包用 `optionalDependencies` 引用 | 不适用的环境可以跳过安装,也不拖慢主包 |
|
|
37
37
|
| D10 | 许可证分区,见第 7 节 | 各自保留原许可证,作为独立程序互不影响 |
|
|
38
38
|
| D11 | cc65 与模拟器的源码放在仓库根目录的 `cc65/` 与 `virtuanes/`,由本仓库维护 | 以后在本仓库里直接修改与升级,来源仍可核对 |
|
|
39
39
|
| D12 | 反汇编不改 `da65` 的 C 代码,用前端脚本生成它的信息文件 | 只有实测发现信息文件无法表达时才改,见 [06-反汇编](06-反汇编.md) |
|
|
@@ -45,7 +45,6 @@ flowchart LR
|
|
|
45
45
|
CREATE[create-fcdev] -->|生成的项目依赖| CLI[fcdev 主包]
|
|
46
46
|
CLI --> TG[内置目标: nes、sb2000]
|
|
47
47
|
CLI -->|optionalDependencies| TC[fcdev-cc65 工具链包]
|
|
48
|
-
CLI -->|optionalDependencies| EM[fcdev-emulator 模拟器包]
|
|
49
48
|
EXT[VS Code 扩展] -.->|调用命令行| CLI
|
|
50
49
|
```
|
|
51
50
|
|
|
@@ -53,8 +52,7 @@ flowchart LR
|
|
|
53
52
|
| --- | --- | --- |
|
|
54
53
|
| `fcdev` | 命令行、构建核心、内置目标、反汇编前端 | 是 |
|
|
55
54
|
| `create-fcdev` | 创建项目的命令与四个模板 | 是 |
|
|
56
|
-
|
|
|
57
|
-
| `@rujianjs/fcdev-emulator` | 调试用模拟器可执行文件 | 只入库 `package.json`,其余由脚本生成 |
|
|
55
|
+
| `fcdev-cc65` | cc65、ca65、ld65、ar65、da65,头文件、库与链接配置 | 只入库 `package.json`,其余由脚本生成 |
|
|
58
56
|
|
|
59
57
|
- 主包不引用具体机型的代码,只读取 `targets/` 下的目标定义。
|
|
60
58
|
- 主包找不到工具链或模拟器时,不去 `PATH` 里猜,报错并说明可选的解决办法。
|
|
@@ -76,7 +74,7 @@ famiclone/
|
|
|
76
74
|
create-fcdev/ 创建包
|
|
77
75
|
bin/ src/ templates/ test/
|
|
78
76
|
fcdev-cc65/ 工具链包
|
|
79
|
-
|
|
77
|
+
ember-debug-sdk/ Ember 调试服务的 SDK(独立包,不随 fcdev 发布,说明见它的 README)
|
|
80
78
|
cc65/ cc65 源码(删减版,本仓库维护)
|
|
81
79
|
virtuanes/ 模拟器源码(VirtuaNES 调试版,本仓库维护)
|
|
82
80
|
vscode/ VS Code 扩展(独立的 npm 项目,不在工作区里),见 [10-VS Code扩展](10-VS%20Code扩展.md)
|
|
@@ -122,7 +120,7 @@ famiclone/
|
|
|
122
120
|
| --- | --- |
|
|
123
121
|
| 仓库与 `fcdev`、`create-fcdev` 自己的代码 | Apache-2.0,见根目录 `LICENSE` |
|
|
124
122
|
| `cc65/` 及工具链包 | zlib,见 `cc65/LICENSE` |
|
|
125
|
-
| `virtuanes/`
|
|
123
|
+
| `virtuanes/` | GPL-3.0-only,见 `virtuanes/LICENSE` |
|
|
126
124
|
|
|
127
125
|
模拟器源码里只有 `interp.h`、`nx_hq2x.h`、`nx_Scale2x.h` 三个文件头写“版本 2 或以后”,合并后按 GPLv3 发布。两个包都是独立程序,许可证互不影响。
|
|
128
126
|
|
|
@@ -130,8 +128,7 @@ famiclone/
|
|
|
130
128
|
|
|
131
129
|
| 脚本 | 作用 |
|
|
132
130
|
| --- | --- |
|
|
133
|
-
| `tools/build-cc65.mjs` | 构建 cc65 工具与运行库,组装
|
|
134
|
-
| `tools/build-emulator.mjs` | 构建模拟器,组装 `@rujianjs/fcdev-emulator`,见 [05-模拟器与调试](05-模拟器与调试.md) |
|
|
131
|
+
| `tools/build-cc65.mjs` | 构建 cc65 工具与运行库,组装 `fcdev-cc65`,见 [04-cc65工具链](04-cc65工具链.md) |
|
|
135
132
|
| `tools/build-libs.mjs` | 按各目标的 `lib-build.json` 用 `cc65`、`ca65`、`ar65` 编出 `lib/` 下的运行库(`.c` 与 `.s` 源码,目录项递归展开);`fcdev` 的 `prepack` 与 `npm test` 前自动运行 |
|
|
136
133
|
| `tools/gen-sb2000-header.mjs` | 由 `sb2000.inc` 生成 `sb2000-symbols.h` |
|
|
137
134
|
| `tools/check-sb2000-api.mjs` | 检查 SB2000 的 C 接口:函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 6 节 |
|
|
@@ -151,7 +148,7 @@ famiclone/
|
|
|
151
148
|
| `build` | [02-命令行与构建](02-命令行与构建.md) | 命令、构建规则、配置文件、构建流程 |
|
|
152
149
|
| `targets` | [03-目标规范](03-目标规范.md) | 目标定义、打包器、新增机型的步骤 |
|
|
153
150
|
| `toolchain` | [04-cc65工具链](04-cc65工具链.md) | cc65 源码、构建与工具链包 |
|
|
154
|
-
| `emulator` | [05-模拟器与调试](05-模拟器与调试.md) |
|
|
151
|
+
| `emulator` | [05-模拟器与调试](05-模拟器与调试.md) | 运行方案、模拟器定位、调试服务与命令表 |
|
|
155
152
|
| `disasm` | [06-反汇编](06-反汇编.md) | 反汇编前端的流程与限制 |
|
|
156
153
|
| `create` | [07-创建包与模板](07-创建包与模板.md) | 创建命令、模板与生成内容 |
|
|
157
154
|
| `testing` | [08-测试与验证](08-测试与验证.md) | 测试分层、环境变量与运行方法 |
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
| `include` | 字符串数组 | 空 | 额外头文件目录,相对项目根 |
|
|
63
63
|
| `toolchain` | 字符串 | 空 | 自备 cc65 的根目录,优先于工具链包 |
|
|
64
64
|
| `firmware` | 字符串 | 无 | 固件(BIOS、ROM)文件路径;目标的运行方案要求固件时必填 |
|
|
65
|
-
| `emulator` | 字符串 | 空 |
|
|
65
|
+
| `emulator` | 字符串 | 空 | 模拟器可执行文件路径,不设时读环境变量 `FCDEV_EMULATOR` |
|
|
66
66
|
| `targetOptions` | 对象 | 空 | 目标专用选项,由各目标定义并校验 |
|
|
67
67
|
|
|
68
68
|
- 配置里出现未知项、类型不对、`define` 的值不是字符串或数字时,报错并列出可用的项。
|
|
@@ -112,7 +112,7 @@
|
|
|
112
112
|
|
|
113
113
|
1. 配置项 `toolchain`。
|
|
114
114
|
2. 环境变量 `FCDEV_CC65_HOME`。
|
|
115
|
-
3. 工具链包
|
|
115
|
+
3. 工具链包 `fcdev-cc65`。
|
|
116
116
|
|
|
117
117
|
目录里必须有 `bin` 下的 `cc65`、`ca65`、`ld65`,否则报“不是完整的 cc65 目录”。都找不到时报错并写明三种解决办法。不使用 `PATH` 里的 cc65,避免版本不一致。
|
|
118
118
|
|
|
@@ -60,7 +60,7 @@ targets/<名>/
|
|
|
60
60
|
| `rom` | 模拟器直接加载产物 |
|
|
61
61
|
| `firmware-disk` | 加载 `fcdev.json` 里 `firmware` 指定的固件,挂载磁盘镜像后复位 |
|
|
62
62
|
|
|
63
|
-
`run.emulator` 必须是字符串,标识要用的模拟器;目前只有 `virtuanes
|
|
63
|
+
`run.emulator` 必须是字符串,标识要用的模拟器;目前只有 `virtuanes`,主包总是按 `virtuanes` 的调试服务控制模拟器(模拟器程序由配置项 `emulator` 或环境变量 `FCDEV_EMULATOR` 指定),该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。`firmware-disk` 需要目标同时声明 `disk`,否则运行时报“不支持磁盘镜像”。
|
|
64
64
|
|
|
65
65
|
### 2.3 多页(换页)程序
|
|
66
66
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# cc65 工具链
|
|
2
2
|
|
|
3
|
-
`fcdev` 用 cc65 编译与链接,不使用使用者机器上自带的 cc65。cc65 的源码在本仓库的 `cc65/` 目录,由本仓库维护;构建脚本把它编成工具与运行库,组装成工具链包
|
|
3
|
+
`fcdev` 用 cc65 编译与链接,不使用使用者机器上自带的 cc65。cc65 的源码在本仓库的 `cc65/` 目录,由本仓库维护;构建脚本把它编成工具与运行库,组装成工具链包 `fcdev-cc65` 随 npm 发布。工具链怎么被主包找到,见 [02-命令行与构建](02-命令行与构建.md) 第 4.4 节。
|
|
4
4
|
|
|
5
5
|
## 1. 源码目录 `cc65/`
|
|
6
6
|
|
|
@@ -38,7 +38,7 @@ node tools/build-cc65.mjs
|
|
|
38
38
|
|
|
39
39
|
## 3. 工具链包
|
|
40
40
|
|
|
41
|
-
- 包名
|
|
41
|
+
- 包名 `fcdev-cc65`(与目录名相同),主包把它列为 `optionalDependencies`,版本精确一致。
|
|
42
42
|
- 入库的只有 `package.json`;`bin/`、`include/`、`asminc/`、`lib/`、`cfg/`、`LICENSE`、`manifest.json` 都是生成物,由 `.gitignore` 排除。
|
|
43
43
|
- 主包找不到工具链包时,提示可用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。
|
|
44
44
|
- `npm run release:check` 校验工具链包里的文件与清单一致,且没有清单之外的文件;源码目录里的路径和清单由 `test/cc65-tools.test.mjs` 检查,见 [08-测试与验证](08-测试与验证.md)。
|
|
@@ -1,21 +1,12 @@
|
|
|
1
1
|
# 模拟器与调试
|
|
2
2
|
|
|
3
|
-
`fcdev`
|
|
3
|
+
`fcdev` 的 `run`、`debug` 命令经调试服务控制模拟器。模拟器不随 npm 包提供,需要自备,并且要支持第 5 节的调试服务。本仓库的 `virtuanes/` 是实现了这套服务的 VirtuaNES 调试版源码,能运行 NES 游戏,以及 SB2000 等学习机的固件与程序,由本仓库维护。模拟器的改动清单见 `virtuanes/README.md`,调试服务的命令表见第 5.1 节。
|
|
4
4
|
|
|
5
|
-
## 1.
|
|
5
|
+
## 1. 模拟器的获得
|
|
6
6
|
|
|
7
|
-
- 基于 Win32 与 DirectX
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
- 模拟器运行时会在 `bin/` 里写 `VirtuaNES.ini` 与 `save/`;模拟器包的 `files` 只列出 `manifest.json` 里的文件,所以这些文件不会发布,不用删。
|
|
11
|
-
|
|
12
|
-
构建:
|
|
13
|
-
|
|
14
|
-
```bash
|
|
15
|
-
node tools/build-emulator.mjs
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
`tools/build-emulator.mjs` 需要 Visual Studio(含“使用 C++ 的桌面开发”)。它调用 `virtuanes/build.ps1 -Configuration Release`(编译输出在仓库根目录的 `build/virtuanes/Release/bin/`),把 `VirtuaNES.exe` 与 `Chinese.vlp` 复制进 `bin/`,再用 `vswhere` 找到 Visual Studio 里 32 位的 VC++ 运行库一并放入,最后写 `LICENSE`、`manifest.json`(当前提交、`virtuanes/` 有无未提交改动 `sourceDirty`、各文件的 SHA-256)与 `package.json`。编译前只结束调试实例(调试服务监听 `127.0.0.1` 端口的 `VirtuaNES.exe`);用户自己打开的模拟器不会被结束,它们占用输出文件时编译报错,需先自行关闭。
|
|
7
|
+
- `virtuanes/` 基于 Win32 与 DirectX,许可证 GPL-3.0-only,是 32 位程序,运行需要 32 位的 VC++ 运行库。
|
|
8
|
+
- 编译需要 Visual Studio(含“使用 C++ 的桌面开发”),运行 `virtuanes/build.ps1 -Configuration Release`,输出在仓库根目录的 `build/virtuanes/Release/bin/VirtuaNES.exe`。编译前只结束调试实例(调试服务监听 `127.0.0.1` 端口的 `VirtuaNES.exe`);用户自己打开的模拟器不会被结束,它们占用输出文件时编译报错,需先自行关闭。
|
|
9
|
+
- 模拟器运行时会在程序所在目录里写 `VirtuaNES.ini` 与 `save/`。
|
|
19
10
|
|
|
20
11
|
## 2. 定位模拟器
|
|
21
12
|
|
|
@@ -23,9 +14,8 @@ node tools/build-emulator.mjs
|
|
|
23
14
|
|
|
24
15
|
1. 配置项 `emulator`。
|
|
25
16
|
2. 环境变量 `FCDEV_EMULATOR`。
|
|
26
|
-
3. 模拟器包 `@rujianjs/fcdev-emulator` 里的 `bin/VirtuaNES.exe`。
|
|
27
17
|
|
|
28
|
-
|
|
18
|
+
都没有设置时报“找不到模拟器”,指定的路径不存在时报“找不到模拟器:路径”。模拟器需要支持同样的调试服务才能用调试命令。
|
|
29
19
|
|
|
30
20
|
## 3. `fcdev run`
|
|
31
21
|
|
|
@@ -59,14 +59,14 @@ VS Code 扩展是独立的 npm 项目,测试在 `vscode/test/`,用 vitest;
|
|
|
59
59
|
|
|
60
60
|
`npm run release:verify`(`tools/verify-install.mjs`):
|
|
61
61
|
|
|
62
|
-
1.
|
|
62
|
+
1. 把三个包用 `npm pack` 打成 `.tgz`。
|
|
63
63
|
2. 在临时目录里从本地 `.tgz` 安装 `create-fcdev`,不访问 npm 仓库,也不执行 `npm publish`。
|
|
64
|
-
3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev`
|
|
64
|
+
3. 对四个模板分别:用 `create-fcdev` 创建项目(`--no-install`),从本地 `.tgz` 安装 `fcdev` 与工具链包,运行 `npm run build`,检查产物头部:NES 为 iNES 文件头,SB2000 为 `4C ?? ?? AA 55`。
|
|
65
65
|
4. 结束后删除临时目录;加 `--keep` 可保留,便于查看。
|
|
66
66
|
|
|
67
67
|
只验证构建,不启动模拟器。
|
|
68
68
|
|
|
69
69
|
## 7. 注意事项
|
|
70
70
|
|
|
71
|
-
-
|
|
71
|
+
- 带真实模拟器的用例运行后会在模拟器所在目录里生成 `VirtuaNES.ini` 与 `save/`,不用删。
|
|
72
72
|
- 没有目测的界面输出,汇报时写明。
|
|
@@ -1,52 +1,47 @@
|
|
|
1
1
|
# 发布
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
本文说明三个 npm 包的发布顺序、前提、检查和元数据。npm 的登录与 `npm publish` 由用户执行,不在代码或文档里记录任何凭据。
|
|
4
4
|
|
|
5
5
|
## 1. 包与版本
|
|
6
6
|
|
|
7
7
|
| 包 | 说明 |
|
|
8
8
|
| --- | --- |
|
|
9
|
-
|
|
|
10
|
-
|
|
|
11
|
-
| `fcdev` | 主包,对两个包写精确版本的 `optionalDependencies` |
|
|
9
|
+
| `fcdev-cc65` | 工具链包,目录 `packages/fcdev-cc65` |
|
|
10
|
+
| `fcdev` | 主包,对工具链包写精确版本的 `optionalDependencies` |
|
|
12
11
|
| `create-fcdev` | 创建包;生成的项目依赖与它同版本的 `fcdev` |
|
|
13
12
|
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
- 工具链包与模拟器包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs` 与 `node tools/build-emulator.mjs`。
|
|
13
|
+
- 三个包同一个版本号,由 `release-check` 检查;`fcdev` 对工具链包的依赖版本必须与之相同。工作区里的 `packages/ember-debug-sdk`(`ember-debug-sdk`)不在这三个包之列,版本独立,不由本文的发布脚本发布。
|
|
14
|
+
- `release-check` 会检查工具链包的包名是否在 `fcdev` 的 `optionalDependencies` 里。
|
|
15
|
+
- 工具链包的 `package.json` 由构建脚本生成,版本取主包的版本。修改版本号后,要重新运行 `node tools/build-cc65.mjs`。
|
|
18
16
|
- 每个包的 `package.json` 写 `license`、`engines`(`node >=22`)、`files`,不写 `repository`、`homepage`、`bugs`(源码不公开,写了也打不开)。作者与邮箱为 `sungbin`、`sungbin@3578.cn`。
|
|
19
17
|
|
|
20
18
|
## 2. 发布前提
|
|
21
19
|
|
|
22
20
|
1. 所有改动已提交。
|
|
23
|
-
2.
|
|
24
|
-
3.
|
|
25
|
-
4. `
|
|
26
|
-
5. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(四个包共用一份,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展与模拟器各有自己的 `CHANGELOG.md`(`vscode/`、`virtuanes/`),版本号独立,有改动才升。
|
|
21
|
+
2. 工具链包已构建:`node tools/build-cc65.mjs`;各目标的运行库已构建(`fcdev` 的 `prepack` 会自动重建)。
|
|
22
|
+
3. `npm run release:check` 通过。
|
|
23
|
+
4. `packages/fcdev/CHANGELOG.md` 里已经写好本版本的更新说明(三个包共用一份,标题写成 `## <版本号>(日期)`);只写面向使用者的功能性变化,按功能分组,一条一句话。VS Code 扩展与模拟器各有自己的 `CHANGELOG.md`(`vscode/`、`virtuanes/`),版本号独立,有改动才升。
|
|
27
24
|
|
|
28
25
|
## 3. 检查
|
|
29
26
|
|
|
30
27
|
`npm run release:check`(`tools/release-check.mjs`)只检查,不修改任何文件,也不执行 `npm publish`:
|
|
31
28
|
|
|
32
|
-
-
|
|
29
|
+
- 三个包的版本一致,都写了 `license`,`fcdev` 对工具链包的依赖版本一致;工具链包的包名在 `fcdev` 的依赖里,作用域包声明了公开发布。
|
|
33
30
|
- `fcdev` 的 `CHANGELOG.md` 在发布内容里,且有当前版本的标题。
|
|
34
31
|
- 每个目标都已构建运行库,且运行库在 `fcdev` 的发布内容里。
|
|
35
32
|
- `docs/` 目录下的全部开发文档都在 `fcdev` 的发布内容里(安装后在 `node_modules/fcdev/docs/`,`fcdev docs` 命令读取)。
|
|
36
|
-
- 工具链包里的文件与 `manifest.json` 记录的 SHA-256
|
|
37
|
-
- 模拟器清单的 `sourceDirty` 为 `true` 时报错;加 `--allow-dirty` 降为警告,只用于发布前的演练。
|
|
33
|
+
- 工具链包里的文件与 `manifest.json` 记录的 SHA-256 一致,没有清单之外的文件。
|
|
38
34
|
- 每个包的发布内容(`npm pack --dry-run`)包含 `LICENSE`、`package.json` 与必需的文件,且不含测试、`node_modules`、`.env`、密钥与证书文件、`.tgz`。
|
|
39
35
|
|
|
40
36
|
`npm run release:verify` 做安装验证,见 [08-测试与验证](08-测试与验证.md) 第 6 节。
|
|
41
37
|
|
|
42
38
|
## 4. 发布顺序
|
|
43
39
|
|
|
44
|
-
|
|
40
|
+
先发工具链包,再发 `fcdev`,最后发 `create-fcdev`:
|
|
45
41
|
|
|
46
|
-
1.
|
|
47
|
-
2.
|
|
48
|
-
3. `fcdev`
|
|
49
|
-
4. `create-fcdev`
|
|
42
|
+
1. `fcdev-cc65`
|
|
43
|
+
2. `fcdev`
|
|
44
|
+
3. `create-fcdev`
|
|
50
45
|
|
|
51
46
|
`npm publish` 需要先登录 npm,可能还要二次验证。可以先对每个包运行 `npm publish --dry-run`,核对内容清单与体积。
|
|
52
47
|
|
|
@@ -58,8 +53,7 @@
|
|
|
58
53
|
| --- | --- | --- |
|
|
59
54
|
| `fcdev` | 71 | 64 kB |
|
|
60
55
|
| `create-fcdev` | 23 | 15 kB |
|
|
61
|
-
|
|
|
62
|
-
| `@rujianjs/fcdev-emulator` | 7 | 0.7 MB(解压 1.8 MB) |
|
|
56
|
+
| `fcdev-cc65` | 223 | 1.9 MB(解压 6.2 MB) |
|
|
63
57
|
|
|
64
58
|
体积随内容变化,以实际运行 `npm publish --dry-run` 的结果为准。
|
|
65
59
|
|
|
@@ -69,8 +63,8 @@
|
|
|
69
63
|
|
|
70
64
|
| 命令 | 作用 |
|
|
71
65
|
| --- | --- |
|
|
72
|
-
| `npm run release:prepare -- <版本号>` | 升版本号:改主包与创建包的 `version
|
|
73
|
-
| `npm run release:publish -- --dry-run` |
|
|
74
|
-
| `npm run release:publish` | 正式发布:工作区必须已提交、`npm`
|
|
66
|
+
| `npm run release:prepare -- <版本号>` | 升版本号:改主包与创建包的 `version`、主包对工具链包的精确依赖,重新构建工具链包并生成它的 `package.json`,再运行 `npm install` 刷新锁文件。完成后由使用者自己提交 |
|
|
67
|
+
| `npm run release:publish -- --dry-run` | 演练:跑全部测试、`release:check`、`release:verify` 与各包的 `npm publish --dry-run`,不登录、不真正发布;已经发布过的版本只警告并跳过试发布 |
|
|
68
|
+
| `npm run release:publish` | 正式发布:工作区必须已提交、`npm` 已登录、三个包的该版本都未发布;通过同样的检查和试发布后,输入 `yes` 确认,再按第 4 节的顺序发布,发布后不再用 `npm view` 核对(新发布的包要等 npm 审核,马上查不到)。验证码由 npm 在终端里询问 |
|
|
75
69
|
|
|
76
70
|
两个命令都可以加 `--allow-dirty`,允许工作区有未提交的改动,只用于演练。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fcdev",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "6502 兼容机(NES、学习机等)的开发工具:用 cc65 构建 C 与汇编程序",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "sungbin <sungbin@3578.cn>",
|
|
@@ -31,7 +31,6 @@
|
|
|
31
31
|
"targets"
|
|
32
32
|
],
|
|
33
33
|
"optionalDependencies": {
|
|
34
|
-
"
|
|
35
|
-
"@rujianjs/fcdev-emulator": "0.5.0"
|
|
34
|
+
"fcdev-cc65": "0.6.0"
|
|
36
35
|
}
|
|
37
36
|
}
|
package/src/docs/doc-topics.mjs
CHANGED
|
@@ -22,7 +22,7 @@ export const DOC_TOPICS = [
|
|
|
22
22
|
{ topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
|
|
23
23
|
{ topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
|
|
24
24
|
{ topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与工具链包' },
|
|
25
|
-
{ topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '
|
|
25
|
+
{ topic: 'emulator', file: '05-模拟器与调试.md', title: '模拟器与调试', summary: '运行方案、模拟器定位、调试服务与命令表' },
|
|
26
26
|
{ topic: 'disasm', file: '06-反汇编.md', title: '反汇编', summary: '反汇编前端的流程、输入与限制' },
|
|
27
27
|
{ topic: 'create', file: '07-创建包与模板.md', title: '创建包与模板', summary: 'npm create fcdev 的命令、模板与生成内容' },
|
|
28
28
|
{ topic: 'testing', file: '08-测试与验证.md', title: '测试与验证', summary: '测试分层、环境变量与运行方法' },
|
|
@@ -1,27 +1,20 @@
|
|
|
1
1
|
// ------------------------------------------------------------------------
|
|
2
2
|
// 名称:emulator-locator.mjs
|
|
3
|
-
//
|
|
3
|
+
// 说明:定位模拟器程序:配置项、环境变量,按顺序查找。
|
|
4
4
|
// 作者:sungbin
|
|
5
5
|
// 邮箱:sungbin@3578.cn
|
|
6
6
|
// 日期:2026-11-10
|
|
7
7
|
// 备注:无
|
|
8
8
|
// ------------------------------------------------------------------------
|
|
9
9
|
import { existsSync } from 'node:fs';
|
|
10
|
-
import { createRequire } from 'node:module';
|
|
11
10
|
import path from 'node:path';
|
|
12
11
|
import { FcdevError } from '../shared/index.mjs';
|
|
13
12
|
|
|
14
|
-
/**
|
|
13
|
+
/** 环境变量:模拟器的路径 */
|
|
15
14
|
export const EMULATOR_ENV_NAME = 'FCDEV_EMULATOR';
|
|
16
15
|
|
|
17
|
-
/** 模拟器包的名称,放在 @rujianjs 作用域下 */
|
|
18
|
-
export const EMULATOR_PACKAGE_NAME = '@rujianjs/fcdev-emulator';
|
|
19
|
-
|
|
20
|
-
/** 模拟器包里模拟器程序的相对路径 */
|
|
21
|
-
const PACKAGE_EXECUTABLE = path.join('bin', 'VirtuaNES.exe');
|
|
22
|
-
|
|
23
16
|
/**
|
|
24
|
-
* 按顺序定位模拟器:配置项 emulator
|
|
17
|
+
* 按顺序定位模拟器:配置项 emulator、环境变量。
|
|
25
18
|
* @param {{configured?: string, env?: NodeJS.ProcessEnv}} [options] configured 为配置里的绝对路径
|
|
26
19
|
* @returns {{executable: string, source: string}} 模拟器程序与来源
|
|
27
20
|
* @throws {FcdevError} 都找不到
|
|
@@ -34,15 +27,8 @@ export function locateEmulator({ configured, env = process.env } = {}) {
|
|
|
34
27
|
}
|
|
35
28
|
return explicit;
|
|
36
29
|
}
|
|
37
|
-
try {
|
|
38
|
-
const packageJson = createRequire(import.meta.url).resolve(`${EMULATOR_PACKAGE_NAME}/package.json`);
|
|
39
|
-
const executable = path.join(path.dirname(packageJson), PACKAGE_EXECUTABLE);
|
|
40
|
-
if (existsSync(executable)) return { executable, source: 'package' };
|
|
41
|
-
} catch {
|
|
42
|
-
// 模拟器包没有安装,落到下面统一的报错
|
|
43
|
-
}
|
|
44
30
|
throw new FcdevError('找不到模拟器', {
|
|
45
31
|
code: 'EMULATOR_NOT_FOUND',
|
|
46
|
-
hint:
|
|
32
|
+
hint: `任选一种:设置环境变量 ${EMULATOR_ENV_NAME} 指向模拟器程序;在 fcdev.json 里用 emulator 指定`,
|
|
47
33
|
});
|
|
48
34
|
}
|
package/src/emulator/index.mjs
CHANGED
|
@@ -8,4 +8,4 @@
|
|
|
8
8
|
// ------------------------------------------------------------------------
|
|
9
9
|
export { DEFAULT_DEBUG_PORT, DebugClient, parseReply } from './debug-client.mjs';
|
|
10
10
|
export { assertPortFree, launchEmulator } from './emulator-launcher.mjs';
|
|
11
|
-
export { EMULATOR_ENV_NAME,
|
|
11
|
+
export { EMULATOR_ENV_NAME, locateEmulator } from './emulator-locator.mjs';
|
|
@@ -23,8 +23,8 @@ const REQUIRED_TOOLS = ['cc65', 'ca65', 'ld65'];
|
|
|
23
23
|
* @property {string} source 来源:config、env 或 package
|
|
24
24
|
*/
|
|
25
25
|
|
|
26
|
-
/**
|
|
27
|
-
export const TOOLCHAIN_PACKAGE_NAME = '
|
|
26
|
+
/** 工具链包的名称 */
|
|
27
|
+
export const TOOLCHAIN_PACKAGE_NAME = 'fcdev-cc65';
|
|
28
28
|
|
|
29
29
|
/**
|
|
30
30
|
* 工具程序的完整路径。
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|