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
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# SB2000 硬件说明
|
|
2
|
+
|
|
3
|
+
本文是 SB2000(小霸王学生电脑)硬件行为的结论,来源是模拟器源码(fcdev 仓库 `virtuanes/VirtuaNES/NES/Mapper/MapperSB2K.cpp` 等)和实际运行观察。“已确认”指来自模拟器源码或实际运行,真机均未测试;程序接口见 [系统调用手册](02-系统调用手册.md)。
|
|
4
|
+
|
|
5
|
+
| 项目 | 结论 | 状态 |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| CPU | 标准 6502(含非官方指令),不是新指令集;“6576”是映射器 ASIC 的工作模式 | 已确认 |
|
|
8
|
+
| 进入 6576 模式 | 依次向 `$4031` 写入 `$65`、`$76`;BIOS 启动后自行完成 | 已确认 |
|
|
9
|
+
| 返回 FC 兼容模式 | 向 `$4301` 写 `$55`:复位 6576、`RAM 启动`,`$8000` 以上改走 MMC3 仿真 | 已确认 |
|
|
10
|
+
| 程序窗口 | `$4040-$4047` 各选一个 4K 页,对应 `$8000-$FFFF` 的 8 个窗口;值小于 `$80` 是 BIOS ROM 页(512KB,共 128 页),不小于 `$80` 是扩展 RAM 页(512KB) | 已确认 |
|
|
11
|
+
| 启动后的窗口 | `$C000-$FFFF` 固定为 ROM 第 4-7 页,`$8000-$BFFF` 由 BIOS 换页 | 已确认 |
|
|
12
|
+
| 向量 | NMI `$C084`,RESET `$C000`,IRQ `$C12B`(ROM 偏移 `$7FFA` 起) | 已确认 |
|
|
13
|
+
| 内部 RAM | 6576 模式下 `$0000-$1FFF` 为 8K 且不镜像;`$5000-$5FFF` 为 2K 工作 RAM,`$6000-$7FFF` 为 8K 扩展 RAM | 已确认 |
|
|
14
|
+
| DMA | `$4048-$404F`;写 `$4048` 的最高位启动;源为 ROM 或扩展 RAM,目的为工作 RAM 或显存 | 已确认 |
|
|
15
|
+
| 软驱控制器 | `$4200-$4207`;1.44MB(每道 18 扇区、2 面、80 道),LBA = 磁道×36 + 磁头×18 + 扇区 − 1 | 已确认 |
|
|
16
|
+
| 键盘 | 经 `$4020-$4022` 串行收发,扫描码与 DirectInput 的 DIK 值一致 | 已确认 |
|
|
17
|
+
| 显存 | 512KB,经 `$4300` 选 32KB 的 bank | 已确认 |
|
|
18
|
+
| 中断屏蔽与状态 | `$4032` 读写屏蔽寄存器:写入值中为 1 的位屏蔽(禁止)该中断源,同时把 `$4033` 里对应的待处理标志清除(`$4033 &= ~写入值`),为 0 的位允许该中断源。位 7 定时器、位 6 鼠标、位 5 键盘、位 3 软驱,复位时为 `$FF`(全部屏蔽);`$4033` 只读,位含义相同,为 1 表示该源有待处理中断 | 已确认(模拟器源码) |
|
|
19
|
+
| 并口打印机 | 模拟器实现了 Epson ESC/P 虪拟打印机(`LPT.cpp`)。数据写 `$4025`;写 `$4016` 的位 0 为 #选中打印机、位 1 为 #换行、位 2 为复位;写 `$4026` 的位 2 为 #选通(strobe);读 `$4017` 位 2 为出错、位 3 为 #忙;读 `$4026` 位 3、4、5 依次是应答、缺纸、已选中(模拟器里状态固定为“不忙、已应答、有纸、已选中、无错”)。收到 `ESC @`(`$1B $40`)开始一页,弹出“Print to...”对话框,可选系统打印机或输出 PDF、PNG 文件;收到换页 `$0C`、复位或约 6 秒没有数据就结束这一页 | 已确认(模拟器源码) |
|
|
20
|
+
| 语音端口 `$4302` | 读:位 7 为 1 表示可以接收下一个字节(缓冲未满),语音播完时低 4 位为 `$F`。写:把一个语音数据字节送进环形缓冲,由模拟器的 LPC 语音线程解码播放。`$4026` 位 6 的上升沿复位语音(清缓冲)。BIOS 的 `$74`、`$75`(`API_74_PORT4302_CONTROL`、`API_75_PORT4302_SEND`)就是操作它 | 已确认(模拟器源码);`$74`、`$75` 的发送序列与“播完”结束都已实测(见 [系统调用手册](02-系统调用手册.md) 5.13 节);模拟器曾缺 `case 0x4302:`,已修复 |
|
|
21
|
+
|
|
22
|
+
## 软件环境
|
|
23
|
+
|
|
24
|
+
| 项目 | 结论 | 状态 |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| 版本 | `SB-DOS V2.00`,`SUBOR 1989-1998`,启动后依次询问日期与时间,提示符 `A:\>` | 已确认 |
|
|
27
|
+
| 软盘格式 | 标准 1.44MB FAT12(本工具生成的镜像能被 `dir` 读出并运行 `ATTRIB.EXE`、`EDIT.EXE`) | 已确认 |
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# 待办备忘
|
|
2
|
+
|
|
3
|
+
已确定以后再做的事项。做完一项,就把它写进对应的文档,并从本文删掉。
|
|
4
|
+
|
|
5
|
+
## 1. 发布
|
|
6
|
+
|
|
7
|
+
| 事项 | 说明 |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| 发布四个 npm 包 | 由用户登录 npm 后按 [09-发布](09-发布.md) 的顺序执行 |
|
|
10
|
+
| `darwin-arm64`、`linux-x64` 平台包 | 构建脚本已写,需要在这些系统上运行并验证后再发布;模拟器只支持 Windows,不做这两个系统的模拟器包 |
|
|
11
|
+
|
|
12
|
+
## 2. VS Code 扩展
|
|
13
|
+
|
|
14
|
+
扩展的智能感知与 ca65 语法高亮已完成,见 [10-VS Code扩展](10-VS%20Code扩展.md)。发布到 VS Code 市场需要发布者账号,由用户操作,本仓库只负责生成 `.vsix`。下面是还没做的功能:
|
|
15
|
+
|
|
16
|
+
| 功能 | 说明 |
|
|
17
|
+
| --- | --- |
|
|
18
|
+
| 任务 | 任务提供者 `fcdev`:构建、运行;问题匹配器识别 `cc65`、`ca65` 的 `文件(行): Error: 信息`,报错可跳转到源码行 |
|
|
19
|
+
| 命令 | 新建项目(调用 `create-fcdev`)、构建当前文件、构建当前目录、构建项目、运行、切换目标;状态栏显示当前目标 |
|
|
20
|
+
| 找工具 | 项目里没有安装 `fcdev` 时提示一键安装;现在只在日志里写明原因 |
|
|
21
|
+
| 调试 | 首版不做;调试适配器协议(DAP)另写设计 |
|
|
22
|
+
| 真实 VS Code 里的显示效果 | 扩展已做完,类型检查、测试与构建通过;悬停、补全、高亮在真实 VS Code 里的显示效果待用户核对 |
|
|
23
|
+
|
|
24
|
+
## 3. 模拟器
|
|
25
|
+
|
|
26
|
+
| 事项 | 说明 |
|
|
27
|
+
| --- | --- |
|
|
28
|
+
| 内核集成进 VS Code 面板 | 只要调试服务协议不变,`fcdev` 不用改 |
|
|
29
|
+
|
|
30
|
+
## 4. 目标
|
|
31
|
+
|
|
32
|
+
| 事项 | 说明 |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| 步步高、裕兴的目标 | 缺少资料,动手前先用资料与模拟器确认程序格式、内存布局、系统调用与固件要求 |
|
|
35
|
+
| NES 的其他映射器 | 现在只支持 `nes.cfg` 的 NROM |
|
|
36
|
+
| SB2000 的退出码 | `main` 的返回值没有实现为退出码:`$6308` 是运行库显示消息用的 `LIB_GROUP`,DOS 外壳不读取程序返回时的它,系统里没有退出码这个约定;要不要提供自己的约定(如写到某个 ERAM 单元)以后再定 |
|
|
37
|
+
| SB2000 没封装的系统调用 | 见 [api-reference.md](../targets/sb2000/api-reference.md) 末尾的覆盖表与 `api-unwrapped.json`:文件系统内部步骤、`$41`-`$44`、`$31`、`$34`、`$66`、`$65` 与 `$6D` 的部分子功能、`$74`/`$75` 的 NMI 发送与播放列表等;有需要时再封装并补测试 |
|
|
38
|
+
|
|
39
|
+
## 5. 反汇编
|
|
40
|
+
|
|
41
|
+
| 事项 | 说明 |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| 其他映射器 | 现在只支持 NROM 与平铺二进制;其他映射器需要目标提供地址映射 |
|
|
44
|
+
| 跳转表识别 | 例程内联的跳转表(如 `RTS` 跳转表)追踪不到,这部分按数据输出 |
|
|
45
|
+
| 地址表与字符串识别 | 现在没追到的字节都是 `ByteTable` |
|
|
46
|
+
| SB2000 固件页的 CDL 验证 | 没有做;模拟器自带 CDL 只对 SB2K 映射器有效 |
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# 缺陷记录
|
|
2
|
+
|
|
3
|
+
发现的缺陷及修复情况。发现缺陷时先登记,修复后填写修复说明。
|
|
4
|
+
|
|
5
|
+
| 编号 | 发现日期 | 缺陷 | 影响 | 状态 | 修复说明 |
|
|
6
|
+
| --- | --- | --- | --- | --- | --- |
|
|
7
|
+
| B001 | 2026-11-10 | 根 `.gitignore` 的 `build/` 规则把 `packages/fcdev/src/build/`(构建核心的 7 个源文件)排除在版本库之外,`git ls-files` 里没有它们 | 已提交的仓库缺少构建核心,别人克隆后无法使用 `fcdev build`;发布时因为 `files` 白名单仍会打进包,所以现有包内容不受影响 | 已修复 | 把 `.gitignore` 里的 `build/` 改为只忽略仓库根的 `/build/` 与各包根目录下的 `packages/*/build/`;修改后 `git check-ignore` 不再匹配 `packages/fcdev/src/build/`,该目录显示为未跟踪,需要用户自己暂存并提交 |
|
|
8
|
+
| B002 | 2026-11-10 | [virtuanes/README.md](https://gitee.com/sungbin/fcdev/blob/master/virtuanes/README.md) 的目录图根写成 `emulator/`,一处链接指向不存在的文件 | 链接失效,目录图与实际不符 | 已修复 | 目录图改为 `virtuanes/`,删掉失效链接与不属于本仓库的说明 |
|
|
9
|
+
| B003 | 2026-11-10 | `fcdev` 接受 `--verbose` 选项,但没有任何命令使用它 | 选项无效果;文档与帮助文字都没有提到它 | 待修复 | |
|
|
10
|
+
| B004 | 2026-11-12 | `npm run check` 里需要启动模拟器的 SB2000 测试(`sb2000-library.test.mjs`)偶发失败:有时报“调试命令 run 300 超过 120000 毫秒没有应答”,有时报“等待调试服务就绪超时”,失败的用例每次不同;单独重跑通过 | 全量检查偶发 1 个失败,与代码改动无关 | 待修复 | |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fcdev",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "6502 兼容机(NES、学习机等)的开发工具:用 cc65 构建 C 与汇编程序",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "sungbin <sungbin@3578.cn>",
|
|
@@ -30,11 +30,12 @@
|
|
|
30
30
|
},
|
|
31
31
|
"files": [
|
|
32
32
|
"bin",
|
|
33
|
+
"docs",
|
|
33
34
|
"src",
|
|
34
35
|
"targets"
|
|
35
36
|
],
|
|
36
37
|
"optionalDependencies": {
|
|
37
|
-
"@rujianjs/fcdev-cc65-win32-x64": "0.
|
|
38
|
-
"@rujianjs/fcdev-emulator-win32-x64": "0.
|
|
38
|
+
"@rujianjs/fcdev-cc65-win32-x64": "0.3.1",
|
|
39
|
+
"@rujianjs/fcdev-emulator-win32-x64": "0.3.1"
|
|
39
40
|
}
|
|
40
41
|
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:docs-command.mjs
|
|
3
|
+
// 说明:docs 命令:列出开发文档的主题,查询某份文档的本机路径与在线地址。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-11
|
|
7
|
+
// 备注:只读、不联网、不需要 fcdev.json;--json 输出机器可读格式。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import { existsSync } from 'node:fs';
|
|
10
|
+
import { docsDirectory, listDocs, queryDocs } from '../../docs/index.mjs';
|
|
11
|
+
import { FcdevError } from '../../shared/index.mjs';
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* 执行 docs 命令。
|
|
15
|
+
* @param {{positionals: string[], options: {json: boolean}, context: import('../index.mjs').CliContext}} input 参数、选项与运行环境
|
|
16
|
+
* @returns {Promise<number>} 退出码
|
|
17
|
+
*/
|
|
18
|
+
export async function runDocsCommand({ positionals, options, context }) {
|
|
19
|
+
const directory = docsDirectory();
|
|
20
|
+
if (!existsSync(directory)) {
|
|
21
|
+
throw new FcdevError(`找不到文档目录:${directory}`, { code: 'DOCS_MISSING', hint: '这份 fcdev 不带文档,请改读在线文档,地址见 package.json 的 repository' });
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
const query = positionals.join(' ').trim();
|
|
25
|
+
if (query === '') {
|
|
26
|
+
const docs = listDocs();
|
|
27
|
+
if (options.json) {
|
|
28
|
+
context.stdout.write(`${JSON.stringify(docs, null, 2)}\n`);
|
|
29
|
+
return 0;
|
|
30
|
+
}
|
|
31
|
+
const width = Math.max(...docs.map((doc) => doc.topic.length));
|
|
32
|
+
const lines = [`fcdev 开发文档:${docs.length} 份`, `本机目录:${directory}`, ''];
|
|
33
|
+
for (const doc of docs) lines.push(` ${doc.topic.padEnd(width)} ${doc.title}:${doc.summary}`);
|
|
34
|
+
lines.push('', '查询:fcdev docs <主题>(本机路径与在线地址)、fcdev docs <词>(按主题、文件名、标题与说明搜索)');
|
|
35
|
+
context.stdout.write(`${lines.join('\n')}\n`);
|
|
36
|
+
return 0;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const { kind, matches } = queryDocs(query);
|
|
40
|
+
if (matches.length === 0) {
|
|
41
|
+
throw new FcdevError(`没有找到“${query}”`, { code: 'DOCS_NOT_FOUND', hint: '不带查询词运行 fcdev docs 可以看到全部主题' });
|
|
42
|
+
}
|
|
43
|
+
if (options.json) {
|
|
44
|
+
context.stdout.write(`${JSON.stringify(matches, null, 2)}\n`);
|
|
45
|
+
return 0;
|
|
46
|
+
}
|
|
47
|
+
if (matches.length === 1) {
|
|
48
|
+
const [doc] = matches;
|
|
49
|
+
context.stdout.write(`${doc.title}(主题 ${doc.topic})\n说明:${doc.summary}\n本机:${doc.localPath}\n在线:${doc.onlineUrl}\n`);
|
|
50
|
+
return 0;
|
|
51
|
+
}
|
|
52
|
+
const width = Math.max(...matches.map((doc) => doc.topic.length));
|
|
53
|
+
const lines = [`包含“${query}”的文档:${matches.length} 份(${kind === 'file' ? '按文件名' : '按关键词'})`];
|
|
54
|
+
for (const doc of matches) lines.push(` ${doc.topic.padEnd(width)} ${doc.title}:${doc.summary}`);
|
|
55
|
+
lines.push('', '用 fcdev docs <主题> 查看某份文档的本机路径与在线地址');
|
|
56
|
+
context.stdout.write(`${lines.join('\n')}\n`);
|
|
57
|
+
return 0;
|
|
58
|
+
}
|
package/src/cli/index.mjs
CHANGED
|
@@ -14,6 +14,7 @@ import { runBuildCommand } from './commands/build-command.mjs';
|
|
|
14
14
|
import { runDebugCommand } from './commands/debug-command.mjs';
|
|
15
15
|
import { runDiskCommand } from './commands/disk-command.mjs';
|
|
16
16
|
import { runDisasmCommand } from './commands/disasm-command.mjs';
|
|
17
|
+
import { runDocsCommand } from './commands/docs-command.mjs';
|
|
17
18
|
import { runInfoCommand } from './commands/info-command.mjs';
|
|
18
19
|
import { runRunCommand } from './commands/run-command.mjs';
|
|
19
20
|
import { runSyncCommand } from './commands/sync-command.mjs';
|
|
@@ -33,6 +34,7 @@ const COMMANDS = {
|
|
|
33
34
|
debug: runDebugCommand,
|
|
34
35
|
disasm: runDisasmCommand,
|
|
35
36
|
disk: runDiskCommand,
|
|
37
|
+
docs: runDocsCommand,
|
|
36
38
|
info: runInfoCommand,
|
|
37
39
|
run: runRunCommand,
|
|
38
40
|
sync: runSyncCommand,
|
|
@@ -52,6 +54,7 @@ const HELP_TEXT = `fcdev:6502 兼容机的开发工具
|
|
|
52
54
|
sync 生成 IDE 的 C/C++ 配置
|
|
53
55
|
info [--json] 显示目标、工具链与头文件目录
|
|
54
56
|
api [词] [--json] 查询目标的 C 接口文档:函数名、模块名、$功能号或关键词;不带词列出全部模块
|
|
57
|
+
docs [词] [--json] 查询开发文档:主题名或关键词,给出本机路径与在线地址;不带词列出全部主题
|
|
55
58
|
|
|
56
59
|
选项:
|
|
57
60
|
--target <名> 指定目标,覆盖 fcdev.json
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:doc-index.mjs
|
|
3
|
+
// 说明:开发文档的查询:列出全部主题,按主题名、文件名或关键词查找,给出每份文档的本机路径与在线地址。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-11
|
|
7
|
+
// 备注:文档随主包发布在包根的 docs 目录;在线地址由 package.json 的 repository 推出,分支固定为 master。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import path from 'node:path';
|
|
10
|
+
import { fileURLToPath } from 'node:url';
|
|
11
|
+
import { FcdevError, readJsonFile } from '../shared/index.mjs';
|
|
12
|
+
import { DOC_TOPICS } from './doc-topics.mjs';
|
|
13
|
+
|
|
14
|
+
/** 在线文档所在的分支 */
|
|
15
|
+
const ONLINE_BRANCH = 'master';
|
|
16
|
+
|
|
17
|
+
/** 主包根目录 */
|
|
18
|
+
const PACKAGE_DIR = fileURLToPath(new URL('../../', import.meta.url));
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* @typedef {object} DocInfo
|
|
22
|
+
* @property {string} topic 主题名
|
|
23
|
+
* @property {string} title 标题
|
|
24
|
+
* @property {string} summary 一句话说明
|
|
25
|
+
* @property {string} file 文件路径:相对 docs 目录,`inPackage` 为 true 时相对主包根目录
|
|
26
|
+
* @property {boolean} [inPackage] 文件在主包根目录下的其他位置,不在 docs 目录里
|
|
27
|
+
* @property {string} localPath 本机的绝对路径
|
|
28
|
+
* @property {string} onlineUrl 在线地址
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* docs 目录的绝对路径。
|
|
33
|
+
* @returns {string} 目录路径
|
|
34
|
+
*/
|
|
35
|
+
export function docsDirectory() {
|
|
36
|
+
return path.join(PACKAGE_DIR, 'docs');
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* 主包在线目录的地址,以 / 结尾。
|
|
41
|
+
* @returns {string} 地址
|
|
42
|
+
* @throws {FcdevError} package.json 里没有仓库地址
|
|
43
|
+
*/
|
|
44
|
+
function onlineBase() {
|
|
45
|
+
const { repository } = readJsonFile(path.join(PACKAGE_DIR, 'package.json'));
|
|
46
|
+
if (!repository?.url) {
|
|
47
|
+
throw new FcdevError('package.json 里没有 repository 地址,无法给出在线地址', { code: 'DOCS_NO_REPOSITORY' });
|
|
48
|
+
}
|
|
49
|
+
const repositoryUrl = repository.url.replace(/\.git$/, '');
|
|
50
|
+
const directory = (repository.directory ?? '').replace(/^\/+|\/+$/g, '');
|
|
51
|
+
return `${repositoryUrl}/blob/${ONLINE_BRANCH}/${directory ? `${directory}/` : ''}`;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* 把登记项补全成带路径与地址的文档信息。
|
|
56
|
+
* @param {import('./doc-topics.mjs').DocTopic} entry 登记项
|
|
57
|
+
* @param {string} base 主包在线目录的地址
|
|
58
|
+
* @returns {DocInfo} 文档信息
|
|
59
|
+
*/
|
|
60
|
+
function describe(entry, base) {
|
|
61
|
+
const segments = entry.file.split('/');
|
|
62
|
+
return {
|
|
63
|
+
...entry,
|
|
64
|
+
localPath: path.join(entry.inPackage ? PACKAGE_DIR : docsDirectory(), ...segments),
|
|
65
|
+
onlineUrl: base + (entry.inPackage ? '' : 'docs/') + segments.map(encodeURIComponent).join('/'),
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* 列出全部文档。
|
|
71
|
+
* @returns {DocInfo[]} 按登记顺序
|
|
72
|
+
*/
|
|
73
|
+
export function listDocs() {
|
|
74
|
+
const base = onlineBase();
|
|
75
|
+
return DOC_TOPICS.map((entry) => describe(entry, base));
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* 文件名去掉序号前缀与扩展名后的部分,如 `sb2000/02-系统调用手册.md` 得到 `系统调用手册`。
|
|
80
|
+
* @param {string} file 相对 docs 目录的文件路径
|
|
81
|
+
* @returns {string} 名称
|
|
82
|
+
*/
|
|
83
|
+
function fileLabel(file) {
|
|
84
|
+
return path.posix.basename(file, '.md').replace(/^\d+-/, '');
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* 按词查找文档:先按主题名精确匹配,再按文件名,最后按主题、标题与说明里的关键词。
|
|
89
|
+
* @param {string} query 查询词,不分大小写
|
|
90
|
+
* @returns {{kind: 'topic'|'file'|'text'|'none', matches: DocInfo[]}} 匹配方式与结果
|
|
91
|
+
*/
|
|
92
|
+
export function queryDocs(query) {
|
|
93
|
+
const word = query.trim().toLowerCase();
|
|
94
|
+
const docs = listDocs();
|
|
95
|
+
const byTopic = docs.filter((doc) => doc.topic === word);
|
|
96
|
+
if (byTopic.length > 0) return { kind: 'topic', matches: byTopic };
|
|
97
|
+
const byFile = docs.filter((doc) => path.posix.basename(doc.file, '.md').toLowerCase() === word || fileLabel(doc.file).toLowerCase() === word);
|
|
98
|
+
if (byFile.length > 0) return { kind: 'file', matches: byFile };
|
|
99
|
+
const byText = docs.filter((doc) => [doc.topic, doc.title, doc.summary].some((text) => text.toLowerCase().includes(word)));
|
|
100
|
+
return { kind: byText.length > 0 ? 'text' : 'none', matches: byText };
|
|
101
|
+
}
|
|
@@ -0,0 +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: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 fcdev api' },
|
|
36
|
+
{ topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
|
|
37
|
+
{ topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
|
|
38
|
+
];
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:index.mjs
|
|
3
|
+
// 说明:docs 目录的对外入口:开发文档的主题登记与查询。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-11
|
|
7
|
+
// 备注:其他目录只能经这个文件引用 docs。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
export { docsDirectory, listDocs, queryDocs } from './doc-index.mjs';
|
|
10
|
+
export { DOC_TOPICS } from './doc-topics.mjs';
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|