fcdev 0.2.0 → 0.3.1
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/README.md +18 -0
- package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +164 -0
- package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +157 -0
- package/docs/03-/347/233/256/346/240/207/350/247/204/350/214/203.md +123 -0
- package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +51 -0
- package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +100 -0
- package/docs/06-/345/217/215/346/261/207/347/274/226.md +103 -0
- package/docs/07-/345/210/233/345/273/272/345/214/205/344/270/216/346/250/241/346/235/277.md +74 -0
- package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +72 -0
- package/docs/09-/345/217/221/345/270/203.md +67 -0
- package/docs/10-VS Code/346/211/251/345/261/225.md" +131 -0
- package/docs/nes/01-NES/347/233/256/346/240/207.md +52 -0
- package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +252 -0
- package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +797 -0
- package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +27 -0
- package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +46 -0
- package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +10 -0
- package/package.json +4 -3
- package/src/cli/commands/docs-command.mjs +58 -0
- package/src/cli/index.mjs +3 -0
- package/src/docs/doc-index.mjs +101 -0
- package/src/docs/doc-topics.mjs +38 -0
- package/src/docs/index.mjs +10 -0
- 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/README.md
CHANGED
|
@@ -24,6 +24,7 @@ fcdev disasm game.nes # 反汇编成 ca65 源码,并回读校验
|
|
|
24
24
|
fcdev sync # 生成 IDE 的 C/C++ 配置
|
|
25
25
|
fcdev info --json # 显示目标、工具链与头文件目录
|
|
26
26
|
fcdev api sb_file_open # 查询目标的 C 接口文档(函数名、模块名、$功能号或关键词;不带词列出全部模块)
|
|
27
|
+
fcdev docs syscall # 查开发文档的本机路径与在线地址(主题名或关键词;不带词列出全部主题)
|
|
27
28
|
```
|
|
28
29
|
|
|
29
30
|
入口是 `main`(汇编程序写 `.export _main`)。产物放在项目根的 `build/<目标>/`,中间文件在 `build/obj/`。
|
|
@@ -72,6 +73,23 @@ fcdev disasm game.nes --cdl game.cdl --symbols sym.txt # 加 CDL 与符号文
|
|
|
72
73
|
| `nes` | `.nes` | `nes.h`(cc65)、`fcnes.h` | NROM,16K PRG 加 8K CHR;`fcnes.h` 提供调色板、文字显示与等待垂直消隐 |
|
|
73
74
|
| `sb2000` | `.EXE` | `sb2000.h` | 程序从 `$8000` 起装入,默认最大 16K,设 `targetOptions.banks` 后可换页做到约 468K;C 栈在窗口顶端;运行库把 DOS 的系统调用封装成 180 多个 C 函数(文字、键盘手柄鼠标、文件目录、软驱、显示、声音、数学、打印机、输入法等),用 `fcdev api` 查询,整本文档见 `targets/sb2000/api-reference.md` |
|
|
74
75
|
|
|
76
|
+
## 文档
|
|
77
|
+
|
|
78
|
+
完整的使用手册与开发文档随本包发布,装好后在 `node_modules/fcdev/docs/`,也可以在 Gitee 上阅读。终端里运行 `fcdev docs` 列出全部主题,`fcdev docs <主题>` 给出该文档的本机路径与在线地址。
|
|
79
|
+
|
|
80
|
+
| 想做什么 | 主题 | 文档 |
|
|
81
|
+
| --- | --- | --- |
|
|
82
|
+
| 查命令、`fcdev.json` 配置与构建流程 | `build` | [命令行与构建](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/02-命令行与构建.md) |
|
|
83
|
+
| 开发 NES 程序 | `nes` | [NES 目标](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/nes/01-NES目标.md) |
|
|
84
|
+
| 开发 SB2000(SB-DOS)程序 | `sb2000` | [SB2000 开发指南](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/sb2000/01-开发指南.md) |
|
|
85
|
+
| 查 SB-DOS 系统调用与出错码 | `syscall` | [SB-DOS 系统调用手册](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/sb2000/02-系统调用手册.md) |
|
|
86
|
+
| 查 SB2000 的硬件行为 | `hardware` | [SB2000 硬件说明](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/sb2000/03-硬件说明.md) |
|
|
87
|
+
| 查 SB2000 运行库的 C 函数 | `api` | [SB2000 C 接口参考](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/targets/sb2000/api-reference.md)(也可以用 `fcdev api` 查询) |
|
|
88
|
+
| 在模拟器里运行与调试,查调试命令 | `emulator` | [模拟器与调试](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/05-模拟器与调试.md) |
|
|
89
|
+
| 反汇编已有程序 | `disasm` | [反汇编](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/06-反汇编.md) |
|
|
90
|
+
| 创建项目与模板 | `create` | [创建包与模板](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/07-创建包与模板.md) |
|
|
91
|
+
| 新增机型的目标 | `targets` | [目标规范](https://gitee.com/sungbin/fcdev/blob/master/packages/fcdev/docs/03-目标规范.md) |
|
|
92
|
+
|
|
75
93
|
## 限制
|
|
76
94
|
|
|
77
95
|
- 反汇编目前只支持 NROM 与平铺二进制;静态追踪追不到 RTS 跳转表等间接调用的代码,这部分按数据输出,回读仍然一致。
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# 软件架构设计
|
|
2
|
+
|
|
3
|
+
fcdev 是 6502 兼容机的开发工具集:一套用 npm 发布的开发环境,包括命令行、cc65 编译器、各机型的头文件与运行库、项目模板、调试用模拟器和反汇编前端。用 C 或 ca65 汇编开发,构建出各机型的可运行程序。首批目标是 NES 与小霸王学习机 SB2000,之后按“目标”加入步步高、裕兴等机型。
|
|
4
|
+
|
|
5
|
+
本文说明包的划分、目录、分层规则和设计决策。各部分的细节见第 9 节列出的文档。
|
|
6
|
+
|
|
7
|
+
## 1. 范围
|
|
8
|
+
|
|
9
|
+
范围内:
|
|
10
|
+
|
|
11
|
+
- 命令行构建工具、目标定义、cc65 工具链包、调试模拟器包、创建包与模板、反汇编前端。
|
|
12
|
+
- 首批目标:NES、SB2000;其他机型按 [03-目标规范](03-目标规范.md) 加入。
|
|
13
|
+
- VS Code 扩展的智能感知与语法高亮:见 [10-VS Code扩展](10-VS%20Code扩展.md)。
|
|
14
|
+
|
|
15
|
+
范围外:
|
|
16
|
+
|
|
17
|
+
- VS Code 扩展的任务、命令与调试:登记在 [待办备忘](待办备忘.md)。
|
|
18
|
+
- BIOS 与固件的反汇编整理,BIOS 迁移到 ca65:不在本仓库范围。
|
|
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`,工具链包 `@rujianjs/fcdev-cc65-<系统>-<架构>`,模拟器包 `@rujianjs/fcdev-emulator-<系统>-<架构>`;主包与创建包不带作用域,平台包放进 `@rujianjs` 作用域,目录名仍是 `fcdev-cc65-<系统>-<架构>`、`fcdev-emulator-<系统>-<架构>` | `npm create fcdev` 会自动运行 `create-fcdev`;不带作用域的平台包名发布时被 npm 的垃圾包名检测拦截(403);平台包只被主包依赖,使用者不直接输入名字,带作用域没有影响;作用域包要在 `package.json` 里写 `publishConfig.access` 为 `public` |
|
|
30
|
+
| D03 | 命令行与库用 Node 22 的 ESM(`.mjs`)加 JSDoc,运行时无依赖,不需要构建步骤 | 发布内容就是源码,便于核对 |
|
|
31
|
+
| D04 | 用 npm workspaces 管理多个包,所有包同一个版本号,同步发布;主包对平台包写精确版本 | 命令行、目标、编译器与模拟器必须配套 |
|
|
32
|
+
| D05 | 一种机型是一个“目标”,是主包内 `targets/<名>/` 一个目录;新增机型只加目录,不改构建流程 | 多机型扩展 |
|
|
33
|
+
| D06 | 目标声明可选能力:磁盘镜像、模拟器运行;没有该能力的目标,对应命令明确报错 | NES 没有磁盘,学习机有 |
|
|
34
|
+
| D07 | 构建由 `fcdev` 自己判断增量,不用 `make` | Windows 上不必另装 `make` |
|
|
35
|
+
| D08 | 目标运行库在发布前用 `cc65`、`ca65`、`ar65` 编译成 `.lib` 随包发布(C 与汇编源码都可以,一个函数一个目标文件) | 目标文件格式与平台无关,使用者不必再编译库 |
|
|
36
|
+
| D09 | 工具与模拟器按平台分包,用 `optionalDependencies` 让 npm 只装当前系统的那个 | 与 esbuild 等相同的成熟做法 |
|
|
37
|
+
| D10 | 许可证分区,见第 7 节 | 各自保留原许可证,作为独立程序互不影响 |
|
|
38
|
+
| D11 | cc65 与模拟器的源码放在仓库根目录的 `cc65/` 与 `virtuanes/`,由本仓库维护 | 以后在本仓库里直接修改与升级,来源仍可核对 |
|
|
39
|
+
| D12 | 反汇编不改 `da65` 的 C 代码,用前端脚本生成它的信息文件 | 只有实测发现信息文件无法表达时才改,见 [06-反汇编](06-反汇编.md) |
|
|
40
|
+
|
|
41
|
+
## 3. 包与依赖
|
|
42
|
+
|
|
43
|
+
```mermaid
|
|
44
|
+
flowchart LR
|
|
45
|
+
CREATE[create-fcdev] -->|生成的项目依赖| CLI[fcdev 主包]
|
|
46
|
+
CLI --> TG[内置目标: nes、sb2000]
|
|
47
|
+
CLI -->|optionalDependencies| TC[fcdev-cc65 平台包]
|
|
48
|
+
CLI -->|optionalDependencies| EM[fcdev-emulator 平台包]
|
|
49
|
+
EXT[VS Code 扩展] -.->|调用命令行| CLI
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
| 包 | 内容 | 是否入库 |
|
|
53
|
+
| --- | --- | --- |
|
|
54
|
+
| `fcdev` | 命令行、构建核心、内置目标、反汇编前端 | 是 |
|
|
55
|
+
| `create-fcdev` | 创建项目的命令与四个模板 | 是 |
|
|
56
|
+
| `@rujianjs/fcdev-cc65-win32-x64` | cc65、ca65、ld65、ar65、da65,头文件、库与链接配置 | 只入库 `package.json`,其余由脚本生成 |
|
|
57
|
+
| `@rujianjs/fcdev-emulator-win32-x64` | 调试用模拟器可执行文件 | 只入库 `package.json` 与 `SOURCE.txt`,其余由脚本生成 |
|
|
58
|
+
|
|
59
|
+
- 主包不引用具体机型的代码,只读取 `targets/` 下的目标定义。
|
|
60
|
+
- 主包找不到工具链或模拟器时,不去 `PATH` 里猜,报错并说明可选的解决办法。
|
|
61
|
+
|
|
62
|
+
## 4. 仓库目录
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
fcdev/
|
|
66
|
+
LICENSE Apache-2.0
|
|
67
|
+
README.md 使用说明
|
|
68
|
+
package.json 工作区根(private)
|
|
69
|
+
packages/
|
|
70
|
+
fcdev/ 主包
|
|
71
|
+
bin/fcdev.mjs
|
|
72
|
+
docs/ 本目录的文档,随主包发布;nes/、sb2000/ 是各目标的文档
|
|
73
|
+
src/ 见第 5 节
|
|
74
|
+
targets/ 内置目标:nes、sb2000
|
|
75
|
+
test/
|
|
76
|
+
create-fcdev/ 创建包
|
|
77
|
+
bin/ src/ templates/ test/
|
|
78
|
+
fcdev-cc65-win32-x64/ 工具链平台包
|
|
79
|
+
fcdev-emulator-win32-x64/ 模拟器平台包
|
|
80
|
+
cc65/ cc65 源码(删减版,本仓库维护)
|
|
81
|
+
virtuanes/ 模拟器源码(改造版,本仓库维护)
|
|
82
|
+
vscode/ VS Code 扩展(独立的 npm 项目,不在工作区里),见 [10-VS Code扩展](10-VS%20Code扩展.md)
|
|
83
|
+
tools/ 维护脚本,见第 8 节
|
|
84
|
+
examples/ 示例项目(examples/sb2000:SB-DOS 程序),不在工作区里,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 10 节
|
|
85
|
+
test/ 仓库级测试:目录结构、cc65 平台包、SB2000 头文件
|
|
86
|
+
build/ 构建中间目录(不入库)
|
|
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` | 定位与启动模拟器、调试客户端 | `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](https://gitee.com/sungbin/fcdev/blob/master/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 工具与运行库,组装 `@rujianjs/fcdev-cc65-<系统>-<架构>`,见 [04-cc65工具链](04-cc65工具链.md) |
|
|
133
|
+
| `tools/build-emulator.mjs` | 构建模拟器,组装 `@rujianjs/fcdev-emulator-win32-x64`,见 [05-模拟器与调试](05-模拟器与调试.md) |
|
|
134
|
+
| `tools/build-libs.mjs` | 按各目标的 `lib-build.json` 用 `cc65`、`ca65`、`ar65` 编出 `lib/` 下的运行库(`.c` 与 `.s` 源码,目录项递归展开);`fcdev` 的 `prepack` 与 `npm test` 前自动运行 |
|
|
135
|
+
| `tools/gen-sb2000-header.mjs` | 由 `sb2000.inc` 生成 `sb2000-symbols.h` |
|
|
136
|
+
| `tools/check-sb2000-api.mjs` | 检查 SB2000 的 C 接口:函数文档完整、有且只有一处实现、每个功能号被封装或写明不封装的原因,见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 6 节 |
|
|
137
|
+
| `tools/gen-sb2000-api-doc.mjs` | 由头文件文档注释生成 `targets/sb2000/api-reference.md` |
|
|
138
|
+
| `tools/check-structure.mjs` | 检查主包各层的依赖方向(`npm run boundaries`) |
|
|
139
|
+
| `tools/release-check.mjs` | 发布前检查(`npm run release:check`),见 [09-发布](09-发布.md) |
|
|
140
|
+
| `tools/verify-install.mjs` | 打包后在临时目录里创建、安装并构建四个模板(`npm run release:verify`) |
|
|
141
|
+
|
|
142
|
+
## 9. 文档清单
|
|
143
|
+
|
|
144
|
+
文档放在主包的 `docs/` 目录,在这里维护,随 `fcdev` 包一起发布:安装后在 `node_modules/fcdev/docs/`,在线在 Gitee 仓库的 `packages/fcdev/docs/`。`fcdev docs` 列出全部主题并给出本机路径与在线地址,主题登记在 `src/docs/doc-topics.mjs`;新增、改名或删除文档时同步改登记,测试会核对登记与目录一致。文档里指向主包内文件的链接用相对路径,指向仓库其他目录(`tools/`、`virtuanes/`、`vscode/` 等,不随包发布)的链接用 Gitee 地址。`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) | 运行方案、调试服务与命令表、模拟器包 |
|
|
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 运行库全部函数的接口参考(由头文件文档注释生成,查询用 `fcdev api`) |
|
|
163
|
+
| `todo` | [待办备忘](待办备忘.md) | 已确定以后再做的事项 |
|
|
164
|
+
| `bugs` | [缺陷记录](缺陷记录.md) | 发现的缺陷及修复情况 |
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# 命令行与构建
|
|
2
|
+
|
|
3
|
+
本文说明 `fcdev` 的命令、构建规则、配置文件 `fcdev.json` 和构建流程。目标定义见 [03-目标规范](03-目标规范.md),模拟器相关命令的细节见 [05-模拟器与调试](05-模拟器与调试.md),反汇编见 [06-反汇编](06-反汇编.md)。
|
|
4
|
+
|
|
5
|
+
## 1. 命令
|
|
6
|
+
|
|
7
|
+
入口是 [packages/fcdev/bin/fcdev.mjs](../bin/fcdev.mjs),由 `cli/index.mjs` 的 `runCli` 分发。命令正常结束返回 0;出现 `FcdevError` 时向标准错误写“错误:”加说明与建议,返回 1。
|
|
8
|
+
|
|
9
|
+
| 命令 | 作用 |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `fcdev build [路径]` | 构建,规则见第 2 节 |
|
|
12
|
+
| `fcdev disk [路径]` | 构建并把产物放进磁盘镜像;只有声明了磁盘能力的目标可用,镜像放在产物旁边,文件名与程序名相同,扩展名为 `.img`,卷标为 `FCDEV` |
|
|
13
|
+
| `fcdev run [路径]` | 构建后在模拟器里运行 |
|
|
14
|
+
| `fcdev debug <调试命令…>` | 把命令原样转发给模拟器的调试服务 |
|
|
15
|
+
| `fcdev disasm <文件>` | 反汇编,并回读校验 |
|
|
16
|
+
| `fcdev sync` | 生成 IDE 配置,见第 6 节 |
|
|
17
|
+
| `fcdev info [--json]` | 显示目标、工具链与头文件目录 |
|
|
18
|
+
| `fcdev api [词] [--json]` | 查询目标的 C 接口文档,见第 5.1 节 |
|
|
19
|
+
| `fcdev docs [词] [--json]` | 查询开发文档的本机路径与在线地址,见第 5.2 节 |
|
|
20
|
+
|
|
21
|
+
通用选项:
|
|
22
|
+
|
|
23
|
+
| 选项 | 说明 |
|
|
24
|
+
| --- | --- |
|
|
25
|
+
| `--target <名>` | 指定目标,覆盖 `fcdev.json` 里的 `target` |
|
|
26
|
+
| `--debug` | `run` 以调试模式启动模拟器 |
|
|
27
|
+
| `--port <端口>` | `run` 的调试端口,1 到 65535,默认 5699 |
|
|
28
|
+
| `--json` | `info` 输出机器可读格式 |
|
|
29
|
+
| `-h`、`--help` | 显示帮助 |
|
|
30
|
+
| `-v`、`--version` | 显示版本 |
|
|
31
|
+
|
|
32
|
+
`--verbose` 能被解析,目前没有命令使用它。`disasm` 的选项见 [06-反汇编](06-反汇编.md)。`debug` 把命令名之后的全部参数原样交给调试服务,不再解析选项;它的端口取环境变量 `FCDEV_DEBUG_PORT`,默认 5699。
|
|
33
|
+
|
|
34
|
+
## 2. 构建单位
|
|
35
|
+
|
|
36
|
+
| 命令 | 含义 |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `fcdev build` | 等于 `fcdev build .`,以终端当前目录为项目 |
|
|
39
|
+
| `fcdev build abc` | 把目录 `abc` 作为一个项目:递归收集其中全部 `.c`、`.s`、`.asm`,编译后链接成一个程序,程序名取配置里的 `name`,未配置时取目录名 |
|
|
40
|
+
| `fcdev build abc/aaa.c` | 只编译并链接这一个文件,它自己是一个程序,程序名取文件名(不含扩展名) |
|
|
41
|
+
|
|
42
|
+
- 入口是 `main`(汇编写 `.export _main`),不设置入口文件。缺少或重复时 `ld65` 报错,`fcdev` 补一句提示。
|
|
43
|
+
- 收集目录时跳过 `build`、`node_modules`、以 `.` 开头的目录,以及配置里的输出目录;目录里没有源文件时报错。
|
|
44
|
+
- 程序名按目标的 `nameRule` 校验(例如 DOS 8.3),不符合就报错,不静默截断。
|
|
45
|
+
- 目标取自构建路径向上查找到的最近一个 `fcdev.json`,`--target` 可覆盖;两者都没有时报错,不默认猜测。
|
|
46
|
+
- 项目根是 `fcdev.json` 所在目录;找不到配置时是终端当前目录。
|
|
47
|
+
- 目录里有多个独立的单文件程序时,不能用一次 `build 目录` 批量构建,只能逐个指定文件。
|
|
48
|
+
|
|
49
|
+
`info` 与 `sync` 以终端当前目录向上查找 `fcdev.json`,不接受路径参数。
|
|
50
|
+
|
|
51
|
+
## 3. 配置文件 `fcdev.json`
|
|
52
|
+
|
|
53
|
+
| 项 | 类型 | 默认值 | 说明 |
|
|
54
|
+
| --- | --- | --- | --- |
|
|
55
|
+
| `target` | 字符串 | 无 | 目标名 |
|
|
56
|
+
| `name` | 字符串 | 目录名 | 目录构建时的程序名 |
|
|
57
|
+
| `out` | 字符串 | `build` | 输出目录,相对项目根 |
|
|
58
|
+
| `optimize` | 布尔 | `true` | 给 `cc65` 加 `-Oirs` |
|
|
59
|
+
| `define` | 对象 | 空 | 预定义宏,值为字符串或数字 |
|
|
60
|
+
| `include` | 字符串数组 | 空 | 额外头文件目录,相对项目根 |
|
|
61
|
+
| `toolchain` | 字符串 | 空 | 自备 cc65 的根目录,优先于平台包 |
|
|
62
|
+
| `firmware` | 字符串 | 无 | 固件(BIOS、ROM)文件路径;目标的运行方案要求固件时必填 |
|
|
63
|
+
| `emulator` | 字符串 | 空 | 自备模拟器可执行文件路径,优先于模拟器包 |
|
|
64
|
+
| `targetOptions` | 对象 | 空 | 目标专用选项,由各目标定义并校验 |
|
|
65
|
+
|
|
66
|
+
- 配置里出现未知项、类型不对、`define` 的值不是字符串或数字时,报错并列出可用的项。
|
|
67
|
+
- `out`、`include`、`toolchain`、`firmware`、`emulator` 里的相对路径都以配置文件所在目录为基准。
|
|
68
|
+
- `targetOptions` 里出现目标没有定义的选项、类型不对或超出目标规定的范围时报错。
|
|
69
|
+
|
|
70
|
+
## 4. 构建流程
|
|
71
|
+
|
|
72
|
+
### 4.1 产物位置
|
|
73
|
+
|
|
74
|
+
| 内容 | 位置 |
|
|
75
|
+
| --- | --- |
|
|
76
|
+
| 产物 | `<项目根>/<out>/<目标>/<程序名><扩展名>`,程序名按目标的 `nameRule` 规范化 |
|
|
77
|
+
| 中间文件 | `<项目根>/<out>/obj/<目标>/<程序名>/` |
|
|
78
|
+
|
|
79
|
+
中间文件目录里有每个源文件对应的 `.o`、依赖文件 `.d`,C 文件还有编译出的 `.s` 与汇编依赖文件 `.asm.d`;链接产物 `<程序名>.bin`、`<程序名>.map`、`<程序名>.dbg`;多页程序还有展开后的链接配置 `<程序名>.cfg`;以及指纹文件 `stamp.json`。`.o` 的文件名取源文件相对目录的路径,去掉扩展名,目录分隔符换成 `__`。
|
|
80
|
+
|
|
81
|
+
### 4.2 单个程序
|
|
82
|
+
|
|
83
|
+
1. 对每个 `.c`:`cc65` 输出 `.s` 与依赖文件(`--create-dep`)。
|
|
84
|
+
2. 对每个 `.s`(含上一步生成的):`ca65` 汇编成 `.o`,同样输出依赖文件。
|
|
85
|
+
3. `ld65`:按目标的链接配置,依次链接启动代码、用户的 `.o`、开启的目标选项所带的目标文件,最后链接目标声明的库;生成 `.bin`、`.map`、`.dbg`。目标声明了 `forceImports` 时,用 `-u` 强制引入这些符号。目标声明了多页(换页)程序(`banked`)且库页个数大于 0 时,链接配置由目标的模板按库页个数展开,写在中间文件目录里,打包器也不再检查映像大小上限,见 [03-目标规范](03-目标规范.md) 第 2.3 节。
|
|
86
|
+
4. 打包器把 `.bin` 做成最终产物。
|
|
87
|
+
|
|
88
|
+
工具参数:
|
|
89
|
+
|
|
90
|
+
| 工具 | 参数 |
|
|
91
|
+
| --- | --- |
|
|
92
|
+
| `cc65` | `-t <cc65Target> --cpu <cpu> -g`,`optimize` 为真时加 `-Oirs`,每个头文件目录一个 `-I`,每个宏一个 `-D 名=值`,`--create-dep`,`-o` |
|
|
93
|
+
| `ca65` | `-t`、`--cpu`、`-g`,每个汇编引入目录同时给 `-I` 与 `--bin-include-dir`,`-D`,`--create-dep`,`-o` |
|
|
94
|
+
| `ld65` | `-C <链接配置> -m <map> --dbgfile <dbg> -o <bin>`,再接 `-u` 强制引入、目标文件、库 |
|
|
95
|
+
|
|
96
|
+
头文件目录依次是:目标的 `include`、配置的 `include`、源文件的公共根目录;汇编引入目录同理,用目标的 `asminclude`。预定义宏是目标的 `defines` 加配置的 `define`,后者覆盖前者。
|
|
97
|
+
|
|
98
|
+
工具的输出(`文件(行): Error: 信息` 格式)原样写到标准错误,供 VS Code 问题匹配器使用。调用工具时设置环境变量 `CC65_HOME` 为工具链根目录。
|
|
99
|
+
|
|
100
|
+
### 4.3 增量构建
|
|
101
|
+
|
|
102
|
+
- 某个 `.o` 存在,且比它的源文件与依赖文件里列出的所有文件都新,就不重编。
|
|
103
|
+
- 指纹由 `fcdev` 版本、工具链版本(`cc65 --version` 的输出)、整个目标定义、目标选项、`optimize`、`define`、`include` 和源文件列表算出,记在 `stamp.json`。指纹变了,先删掉整个中间文件目录再全部重编。
|
|
104
|
+
- 构建成功后才写 `stamp.json`。
|
|
105
|
+
- 构建结束输出产物大小,以及本次重新编译与沿用的文件数。
|
|
106
|
+
|
|
107
|
+
### 4.4 工具链定位
|
|
108
|
+
|
|
109
|
+
按顺序查找,找到即停:
|
|
110
|
+
|
|
111
|
+
1. 配置项 `toolchain`。
|
|
112
|
+
2. 环境变量 `FCDEV_CC65_HOME`。
|
|
113
|
+
3. 平台包 `@rujianjs/fcdev-cc65-<系统>-<架构>`。
|
|
114
|
+
|
|
115
|
+
目录里必须有 `bin` 下的 `cc65`、`ca65`、`ld65`,否则报“不是完整的 cc65 目录”。都找不到时报错并写明三种解决办法。不使用 `PATH` 里的 cc65,避免版本不一致。
|
|
116
|
+
|
|
117
|
+
## 5. 信息命令
|
|
118
|
+
|
|
119
|
+
`fcdev info` 输出项目根目录、配置文件、目标、工具链(目录、来源 `config`、`env` 或 `package`,版本)、输出目录、头文件目录和汇编引入目录。`--json` 输出同样内容的 JSON,供 VS Code 扩展等工具读取。
|
|
120
|
+
|
|
121
|
+
头文件目录依次是目标的 `include`、配置的 `include`、工具链的 `include`;汇编引入目录同理,最后是工具链的 `asminc`。
|
|
122
|
+
|
|
123
|
+
### 5.1 接口文档查询
|
|
124
|
+
|
|
125
|
+
`fcdev api` 读目标 `include` 目录下头文件里带 `/** */` 文档注释的函数(注释写法见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 6 节),不需要工具链。目标来自 `fcdev.json` 或 `--target`;目标没有带文档注释的函数时报“没有 C 接口文档”,目前只有 `sb2000` 有。
|
|
126
|
+
|
|
127
|
+
| 用法 | 结果 |
|
|
128
|
+
| --- | --- |
|
|
129
|
+
| `fcdev api` | 列出全部模块、各模块的函数个数与头文件 |
|
|
130
|
+
| `fcdev api <函数名>` | 完整文档:签名、所在头文件、系统调用、说明、每个参数、返回值 |
|
|
131
|
+
| `fcdev api <模块名>` 或 `fcdev api <头文件名>` | 该模块的函数与一行说明,如 `fcdev api file` |
|
|
132
|
+
| `fcdev api <功能号>` | 用到该系统调用的函数,写法 `$7B` 或 `$7B/$09`(不分大小写,`$` 可以省略) |
|
|
133
|
+
| `fcdev api <词>` | 名称或说明里包含该词的函数 |
|
|
134
|
+
|
|
135
|
+
查询依次按函数名、模块名、功能号、关键词匹配,先匹配上的为准;一个都没有匹配上时报“没有找到”。`--json` 输出机器可读的结果:不带查询词时是模块列表,否则是匹配到的函数。
|
|
136
|
+
|
|
137
|
+
### 5.2 文档查询
|
|
138
|
+
|
|
139
|
+
`fcdev docs` 查询随主包发布的开发文档(主包的 `docs/` 目录),只读、不联网、不需要 `fcdev.json` 和工具链。主题登记在 `src/docs/doc-topics.mjs`,主题名只用小写字母、数字与连字符,清单见 [01-软件架构设计](01-软件架构设计.md) 第 9 节。
|
|
140
|
+
|
|
141
|
+
| 用法 | 结果 |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| `fcdev docs` | 列出全部主题(主题名、标题、一句话说明)与本机文档目录 |
|
|
144
|
+
| `fcdev docs <主题>` | 该文档的标题、说明、本机绝对路径与在线地址,如 `fcdev docs syscall` |
|
|
145
|
+
| `fcdev docs <词>` | 按文件名(去掉序号与扩展名也可)或主题、标题、说明里的关键词查找;只匹配到一份时同上,多份时列出摘要 |
|
|
146
|
+
|
|
147
|
+
- 查询依次按主题名、文件名、关键词匹配,先匹配上的为准;一份都没有匹配上时报“没有找到”。`--json` 输出机器可读的结果:不带查询词时是全部文档,否则是匹配到的文档,每项含 `topic`、`title`、`summary`、`file`、`localPath`、`onlineUrl`。
|
|
148
|
+
- 在线地址由主包 `package.json` 的 `repository` 推出(仓库地址加 `directory`),分支固定为 `master`,路径里的中文与空格已编码。
|
|
149
|
+
- 登记项默认是 `docs/` 下的文件;登记项带 `inPackage` 时指向主包根目录下的文件,目前只有 `api` 主题(`targets/sb2000/api-reference.md`),它的在线地址不带 `docs/`。
|
|
150
|
+
- 文档目录不存在时报错,提示改读在线文档。
|
|
151
|
+
|
|
152
|
+
## 6. `fcdev sync`
|
|
153
|
+
|
|
154
|
+
生成 IDE 的 C/C++ 配置,让智能提示找到 cc65 与目标的头文件:
|
|
155
|
+
|
|
156
|
+
- `.vscode/c_cpp_properties.json`:只写或更新名为 `fcdev` 的配置,保留其他配置;该配置含 `includePath`、`defines`(`__CC65__`、`__<目标>__`、目标和配置里的宏,以及给编辑器用的空宏 `__fastcall__`、`__cdecl__`,它们不参与构建)、`cStandard` 为 `c89`。已有文件没有 `configurations` 数组时报错。
|
|
157
|
+
- 项目根的 `compile_flags.txt`:第一行是标记 `-DFCDEV_GENERATED`,之后是 `-I` 与 `-D` 行。已有同名文件但第一行不是该标记时,视为用户自己的文件,不覆盖。
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# 目标规范
|
|
2
|
+
|
|
3
|
+
一个“目标”对应一种机型。目标是主包里 `packages/fcdev/targets/<名>/` 下的一个目录,由 `target.json` 描述;新增机型只加目录,不改 `build` 的流程。本文说明目标的目录、`target.json` 的字段、打包器和新增机型的步骤。已有目标的文档在 [nes/](nes/01-NES目标.md) 与 [sb2000/](sb2000/01-开发指南.md) 下。
|
|
4
|
+
|
|
5
|
+
## 1. 目标目录
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
targets/<名>/
|
|
9
|
+
target.json 目标定义
|
|
10
|
+
include/ C 头文件
|
|
11
|
+
asminc/ 汇编引入文件
|
|
12
|
+
src/ 目标自己的运行库与启动代码源码
|
|
13
|
+
lib-build.json 运行库的构建清单(没有要编译的库时可省略)
|
|
14
|
+
lib/ 运行库的编译结果(构建生成,不入库)
|
|
15
|
+
link.cfg 等 目标自带的链接配置(也可以直接用工具链 cfg 里的)
|
|
16
|
+
link-banked.cfg 等 多页(换页)程序的链接配置模板,见第 2.3 节
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
目录名必须与 `target.json` 里的 `name` 一致;目标名只能用小写字母、数字和连字符。
|
|
20
|
+
|
|
21
|
+
## 2. `target.json`
|
|
22
|
+
|
|
23
|
+
| 字段 | 必填 | 说明 |
|
|
24
|
+
| --- | --- | --- |
|
|
25
|
+
| `name`、`title` | 是 | 标识与显示名 |
|
|
26
|
+
| `cpu` | 是 | CPU 型号,传给 `cc65` 与 `ca65`;首批目标都是 `6502` |
|
|
27
|
+
| `cc65Target` | 是 | 传给 `cc65`、`ca65` 的目标名(`-t`),如 `none`、`nes` |
|
|
28
|
+
| `linkConfig` | 是 | 链接配置,路径值 |
|
|
29
|
+
| `packager` | 是 | 程序打包器名,见第 3 节 |
|
|
30
|
+
| `extension` | 是 | 产物扩展名,含点,如 `.nes` |
|
|
31
|
+
| `startup` | 否 | 启动代码目标文件列表,路径值;空表示用 `cc65` 目标库自带的 |
|
|
32
|
+
| `forceImports` | 否 | 链接时用 `-u` 强制引入的符号;用于让库里的启动代码一定被链接,纯汇编程序也不例外 |
|
|
33
|
+
| `libraries` | 否 | 链接的库,按顺序,路径值 |
|
|
34
|
+
| `include`、`asminclude` | 否 | 头文件与汇编引入目录,路径值 |
|
|
35
|
+
| `defines` | 否 | 预定义宏,值为字符串或数字 |
|
|
36
|
+
| `packagerOptions` | 否 | 传给打包器的选项 |
|
|
37
|
+
| `nameRule` | 否 | 程序名规则;空表示不限制 |
|
|
38
|
+
| `disk` | 否 | 磁盘镜像能力,含 `packager`(磁盘打包器名) |
|
|
39
|
+
| `run` | 否 | 运行方案,含 `emulator` 与 `mode` |
|
|
40
|
+
| `options` | 否 | 目标专用选项,见第 4 节 |
|
|
41
|
+
| `banked` | 否 | 多页(换页)程序的定义,见第 2.3 节 |
|
|
42
|
+
|
|
43
|
+
路径值有两种写法:
|
|
44
|
+
|
|
45
|
+
- 相对目标目录,如 `lib/crt0.o`。
|
|
46
|
+
- 以 `toolchain:` 开头,表示相对工具链根目录,如 `toolchain:cfg/nes.cfg`。
|
|
47
|
+
|
|
48
|
+
缺少必填字段、字段类型不对时,报 `TARGET_INVALID`。
|
|
49
|
+
|
|
50
|
+
### 2.1 程序名规则
|
|
51
|
+
|
|
52
|
+
`nameRule` 目前只有 `dos-8.3`:主名为 1 到 8 个字母、数字、下划线或连字符,产物名转为大写;不符合时报错,不截断。写了未登记的规则也报错。规则在 `targets/name-rules.mjs` 登记。
|
|
53
|
+
|
|
54
|
+
### 2.2 运行方案
|
|
55
|
+
|
|
56
|
+
`run.mode` 取值:
|
|
57
|
+
|
|
58
|
+
| 值 | 含义 |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `rom` | 模拟器直接加载产物 |
|
|
61
|
+
| `firmware-disk` | 加载 `fcdev.json` 里 `firmware` 指定的固件,挂载磁盘镜像后复位 |
|
|
62
|
+
|
|
63
|
+
`run.emulator` 必须是字符串,标识要用的模拟器;目前只有 `virtuanes`,主包总是使用 `virtuanes` 的模拟器包,该字段只做校验。没有 `run` 的目标运行 `fcdev run` 时报错。`firmware-disk` 需要目标同时声明 `disk`,否则运行时报“不支持磁盘镜像”。
|
|
64
|
+
|
|
65
|
+
### 2.3 多页(换页)程序
|
|
66
|
+
|
|
67
|
+
目标的程序可以超过一个窗口时,用 `banked` 说明怎么生成链接配置。程序按“库页”换页,库页个数由 `options` 里的一个数字选项决定。`banked` 的字段:
|
|
68
|
+
|
|
69
|
+
| 字段 | 说明 |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| `option` | 数字选项名,值是库页个数;值为 0 时不用多页,按 `linkConfig` 链接,打包器选项不变 |
|
|
72
|
+
| `linkConfig` | 多页链接配置的模板,路径值;模板里单独一行的 `%BANK_MEMORY%` 与 `%BANK_SEGMENTS%` 由 fcdev 展开,缺少时报 `TARGET_INVALID` |
|
|
73
|
+
| `generatedFrom` | 模板里已经写出这一页之前的库页,从这一页起按个数生成 |
|
|
74
|
+
| `maxBanks` | 库页个数的上限;选项值超过上限、不是整数或小于 0 时报 `TARGET_OPTION_INVALID` |
|
|
75
|
+
| `memory`、`segment` | 一个库页的内存区行与段行,`{n}` 换成库页号 |
|
|
76
|
+
|
|
77
|
+
选项值大于 0 时,fcdev 把模板展开成 `<中间文件目录>/<程序名>.cfg` 交给 `ld65`,并去掉打包器选项里的 `maxSize`(大小由库页个数决定)。`ld65` 报某个库页的段没有内存区时,提示加大库页个数。`option` 必须是 `options` 里的数字选项,`generatedFrom` 与 `maxBanks` 是不小于 1 的整数,否则报 `TARGET_INVALID`。目前只有 `sb2000` 声明了 `banked`,用法见 [sb2000/01-开发指南](sb2000/01-开发指南.md) 第 3.1 节。
|
|
78
|
+
|
|
79
|
+
## 3. 打包器
|
|
80
|
+
|
|
81
|
+
链接得到 `.bin`,再由打包器做成最终产物。打包器在 `packagers/index.mjs` 登记。
|
|
82
|
+
|
|
83
|
+
| 打包器 | 类别 | 作用 | 选项 |
|
|
84
|
+
| --- | --- | --- | --- |
|
|
85
|
+
| `flat-exe` | 程序 | 平铺映像:校验文件头与大小,写成产物文件 | `header`:十六进制字符串,`??` 表示任意字节;`maxSize`:映像大小上限,字节 |
|
|
86
|
+
| `ines` | 程序 | 校验 iNES 头与文件长度,写成 `.nes` | 无 |
|
|
87
|
+
| `fat-floppy` | 磁盘 | 把一组文件放进 1.44MB 的 FAT12 软盘镜像根目录 | `label`:卷标 |
|
|
88
|
+
|
|
89
|
+
- 程序打包器接收 `{ binaryFile, outputFile, options }`,返回 `{ outputFile, size }`。
|
|
90
|
+
- 磁盘打包器接收 `{ files, outputFile, options }`,输入是一组 `{ name, data, mtime }`,输出一个镜像文件。
|
|
91
|
+
- `fat-floppy` 的几何参数是 512 字节扇区、2 面、80 磁道、每磁道 18 扇区,共 2880 个扇区,与模拟器的软驱控制器一致;文件只写在根目录,每簇 1 个扇区,文件名必须符合 8.3,不支持子目录;引导扇区只有 BIOS 参数块与签名,没有启动代码,镜像只用作数据盘。
|
|
92
|
+
|
|
93
|
+
## 4. 目标专用选项
|
|
94
|
+
|
|
95
|
+
`options` 里每一项是一个选项,字段:
|
|
96
|
+
|
|
97
|
+
| 字段 | 说明 |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| `type` | `boolean`、`string` 或 `number` |
|
|
100
|
+
| `default` | 默认值,类型必须与 `type` 一致 |
|
|
101
|
+
| `links` | 只用于布尔选项:值为 `true` 时额外链接的目标文件,路径值 |
|
|
102
|
+
|
|
103
|
+
用户在 `fcdev.json` 的 `targetOptions` 里设置;没有定义的选项或类型不对时报错。额外链接的目标文件排在用户目标文件之后、库之前。
|
|
104
|
+
|
|
105
|
+
## 5. 运行库的构建
|
|
106
|
+
|
|
107
|
+
目标自带的运行库与启动代码用 C 或汇编写,发布前编译好随包发布。`lib-build.json` 的字段:
|
|
108
|
+
|
|
109
|
+
| 字段 | 说明 |
|
|
110
|
+
| --- | --- |
|
|
111
|
+
| `libraries` | 库路径到源文件列表;每个源文件编成一个 `.o`(`.c` 先用 `cc65` 编成汇编,再汇编),用 `ar65 a` 合成库,再删除临时 `.o`;列表里以 `/` 结尾的项是目录,递归收录其中全部 `.c` 与 `.s`;同名文件报错 |
|
|
112
|
+
| `objects` | 目标文件路径到源文件,直接汇编成 `.o` |
|
|
113
|
+
| `binIncludeDirs` | `.incbin` 的搜索目录,相对目标目录 |
|
|
114
|
+
|
|
115
|
+
汇编时固定给 `-I <目标>/asminc`,`-t` 与 `--cpu` 取目标的定义;`.c` 用 `cc65 -t <cc65Target> --cpu <cpu> -Oirs`,头文件目录取目标的 `include`,并带上目标的 `defines`。一个函数一个源文件,库里就是一个函数一个目标文件,链接时只带入程序用到的函数。命令 `node tools/build-libs.mjs [目标名…]` 编译;不带参数时编译全部目标。`fcdev` 的 `prepack` 与根目录 `npm test` 的 `pretest` 都会自动运行它。
|
|
116
|
+
|
|
117
|
+
## 6. 新增机型的步骤
|
|
118
|
+
|
|
119
|
+
1. 在 `packages/fcdev/targets/` 下新建目录,写 `target.json`、链接配置、启动代码、头文件与运行库源码。头文件里的函数用 `/** */` 文档注释(说明、`@param`、`@return`),`fcdev api` 直接读它们作为接口文档,见 [02-命令行与构建](02-命令行与构建.md) 第 5.1 节。动手前先用资料与模拟器确认程序格式、内存布局、系统调用与固件要求,不凭猜测实现。
|
|
120
|
+
2. 需要新的打包器或程序名规则时,在 `packagers/index.mjs` 或 `targets/name-rules.mjs` 登记。
|
|
121
|
+
3. 有运行库要编译时写 `lib-build.json`,运行 `node tools/build-libs.mjs <目标名>`。
|
|
122
|
+
4. 在 `create-fcdev` 里加 C 与汇编两个模板,见 [07-创建包与模板](07-创建包与模板.md)。
|
|
123
|
+
5. 补测试,见 [08-测试与验证](08-测试与验证.md),并在主包的 `docs/<目标名>/` 下新增该目标的说明文档,更新 [01-软件架构设计](01-软件架构设计.md) 的文档清单与 `src/docs/doc-topics.mjs` 的主题登记。
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# cc65 工具链
|
|
2
|
+
|
|
3
|
+
`fcdev` 用 cc65 编译与链接,不使用使用者机器上自带的 cc65。cc65 的源码在本仓库的 `cc65/` 目录,由本仓库维护;构建脚本把它编成工具与运行库,组装成平台包 `@rujianjs/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](https://gitee.com/sungbin/fcdev/blob/master/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`(版本与主包同步,`os`、`cpu` 限定平台)。
|
|
36
|
+
|
|
37
|
+
Windows 用 `mingw32-make` 与 `gcc`,其他系统用 `make` 与 `cc`,环境变量 `FCDEV_MAKE` 可指定 make 程序。上游提交号常量 `CC65_COMMIT` 写在构建脚本里。
|
|
38
|
+
|
|
39
|
+
## 3. 平台包
|
|
40
|
+
|
|
41
|
+
- 包名 `@rujianjs/fcdev-cc65-<系统>-<架构>`(目录名不含作用域,仍是 `fcdev-cc65-<系统>-<架构>`),用 `os`、`cpu` 字段让 npm 只在对应系统安装,主包把它列为 `optionalDependencies`,版本精确一致。
|
|
42
|
+
- 入库的只有 `package.json`;`bin/`、`include/`、`asminc/`、`lib/`、`cfg/`、`LICENSE`、`manifest.json` 都是生成物,由 `.gitignore` 排除。
|
|
43
|
+
- 首批只发布 `win32-x64`。`darwin-arm64`、`linux-x64` 的构建脚本相同,但没有在这些系统上运行或验证,验证后再发布;发布前主包不列出它们。
|
|
44
|
+
- 主包在没有平台包的系统上运行时,提示可用环境变量 `FCDEV_CC65_HOME` 指向自备的 cc65 目录。
|
|
45
|
+
- `npm run release:check` 校验平台包里的文件与清单一致,且没有清单之外的文件;源码目录里的路径和清单由 `test/cc65-tools.test.mjs` 检查,见 [08-测试与验证](08-测试与验证.md)。
|
|
46
|
+
|
|
47
|
+
## 4. 升级与修改
|
|
48
|
+
|
|
49
|
+
- 修改 `cc65/` 里的源码后,重新运行 `node tools/build-cc65.mjs`,再运行 `npm test`。
|
|
50
|
+
- 要换到上游的新提交时:从上游取回上面“保留的内容”对应的文件,更新 `tools/build-cc65.mjs` 里的 `CC65_COMMIT` 和 `cc65/README-FCDEV.txt` 里的提交号,重新构建并运行全部测试。
|
|
51
|
+
- 统一换行符的脚本不要扫描 `cc65/`:里面有 Latin-1 和 Shift-JIS 编码的文件,按 UTF-8 读写会损坏。`virtuanes/` 也一样。
|