fcdev 0.3.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +35 -33
  3. package/docs/01-/350/275/257/344/273/266/346/236/266/346/236/204/350/256/276/350/256/241.md +27 -25
  4. package/docs/02-/345/221/275/344/273/244/350/241/214/344/270/216/346/236/204/345/273/272.md +8 -7
  5. package/docs/04-cc65/345/267/245/345/205/267/351/223/276.md +9 -10
  6. package/docs/05-/346/250/241/346/213/237/345/231/250/344/270/216/350/260/203/350/257/225.md +13 -11
  7. package/docs/06-/345/217/215/346/261/207/347/274/226.md +9 -4
  8. package/docs/08-/346/265/213/350/257/225/344/270/216/351/252/214/350/257/201.md +6 -6
  9. package/docs/09-/345/217/221/345/270/203.md +31 -22
  10. package/docs/10-VS Code/346/211/251/345/261/225.md" +1 -1
  11. package/docs/nes/01-NES/347/233/256/346/240/207.md +1 -1
  12. package/docs/sb2000/01-/345/274/200/345/217/221/346/214/207/345/215/227.md +16 -9
  13. package/docs/sb2000/02-/347/263/273/347/273/237/350/260/203/347/224/250/346/211/213/345/206/214.md +7 -7
  14. package/docs/sb2000/03-/347/241/254/344/273/266/350/257/264/346/230/216.md +17 -8
  15. package/docs//345/276/205/345/212/236/345/244/207/345/277/230.md +3 -2
  16. package/docs//347/274/272/351/231/267/350/256/260/345/275/225.md +1 -1
  17. package/package.json +4 -8
  18. package/src/cli/commands/api-command.mjs +2 -2
  19. package/src/cli/commands/build-command.mjs +1 -1
  20. package/src/cli/commands/debug-command.mjs +5 -2
  21. package/src/cli/commands/disasm-command.mjs +1 -1
  22. package/src/cli/commands/disk-command.mjs +1 -1
  23. package/src/cli/commands/docs-command.mjs +6 -6
  24. package/src/cli/commands/run-command.mjs +2 -2
  25. package/src/cli/index.mjs +1 -1
  26. package/src/disasm/address-tables.mjs +161 -0
  27. package/src/disasm/analysis.mjs +17 -11
  28. package/src/disasm/byte-kinds.mjs +20 -0
  29. package/src/disasm/disassembler.mjs +3 -2
  30. package/src/disasm/info-writer.mjs +3 -3
  31. package/src/docs/doc-index.mjs +5 -28
  32. package/src/docs/doc-topics.mjs +2 -2
  33. package/src/emulator/debug-client.mjs +1 -1
  34. package/src/emulator/emulator-locator.mjs +13 -27
  35. package/src/emulator/index.mjs +1 -1
  36. package/src/toolchain/index.mjs +1 -1
  37. package/src/toolchain/toolchain-locator.mjs +8 -17
  38. package/targets/nes/lib/fcnes.lib +0 -0
  39. package/targets/nes/lib/nes-font.o +0 -0
  40. package/targets/sb2000/api-reference.md +310 -1
  41. package/targets/sb2000/asminc/sb2000.inc +90 -1
  42. package/targets/sb2000/include/sb2000-dma.h +46 -0
  43. package/targets/sb2000/include/sb2000-ppu.h +106 -0
  44. package/targets/sb2000/include/sb2000-symbols.h +170 -0
  45. package/targets/sb2000/include/sb2000-timer.h +54 -0
  46. package/targets/sb2000/include/sb2000.h +3 -0
  47. package/targets/sb2000/lib/crt0.o +0 -0
  48. package/targets/sb2000/lib/sb2000.lib +0 -0
  49. package/targets/sb2000/src/lib/dma/sb-dma-page-address.c +16 -0
  50. package/targets/sb2000/src/lib/dma/sb-dma-to-cpu.c +19 -0
  51. package/targets/sb2000/src/lib/dma/sb-dma-to-vram.c +16 -0
  52. package/targets/sb2000/src/lib/dma/sbi-dma-run.c +34 -0
  53. package/targets/sb2000/src/lib/ppu/sb-ppu-address.c +20 -0
  54. package/targets/sb2000/src/lib/ppu/sb-ppu-fill.c +19 -0
  55. package/targets/sb2000/src/lib/ppu/sb-ppu-oam-clear.c +21 -0
  56. package/targets/sb2000/src/lib/ppu/sb-ppu-oam-put.c +20 -0
  57. package/targets/sb2000/src/lib/ppu/sb-ppu-palette-get.c +16 -0
  58. package/targets/sb2000/src/lib/ppu/sb-ppu-palette-set.c +16 -0
  59. package/targets/sb2000/src/lib/ppu/sb-ppu-peek.c +22 -0
  60. package/targets/sb2000/src/lib/ppu/sb-ppu-read.c +20 -0
  61. package/targets/sb2000/src/lib/ppu/sb-ppu-render.c +20 -0
  62. package/targets/sb2000/src/lib/ppu/sb-ppu-wait-vblank.c +25 -0
  63. package/targets/sb2000/src/lib/ppu/sb-ppu-write.c +21 -0
  64. package/targets/sb2000/src/lib/sb-internal.h +3 -0
  65. package/targets/sb2000/src/lib/timer/sb-timer-current.c +16 -0
  66. package/targets/sb2000/src/lib/timer/sb-timer-mask.c +16 -0
  67. package/targets/sb2000/src/lib/timer/sb-timer-pending.c +16 -0
  68. package/targets/sb2000/src/lib/timer/sb-timer-start.c +17 -0
  69. package/targets/sb2000/src/lib/timer/sb-timer-stop.c +16 -0
  70. package/targets/sb2000/src/lib/timer/sb-timer-unmask.c +16 -0
@@ -0,0 +1,161 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:address-tables.mjs
3
+ // 说明:在已追踪的代码里找经地址表分发的跳转:从表里读出目标地址,供静态追踪继续追下去。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-13
7
+ // 备注:识别的写法(窗口为紧随加载指令之后的 10 条顺序指令):
8
+ // 1. LDA 表,X/Y 与 LDA 表+1,X/Y 成对,窗口内有间接 JMP:字表,目标就是表里的值;
9
+ // 2. 一对加载指令,窗口内有两条 PHA 与一条 RTS:目标是表里的值加 1;表是字表(两个加载地址相差 1)或低、高字节分开的两张表;
10
+ // 3. 间接 JMP 的地址指向映像内未识别的字节:表项是目标。
11
+ // 表项必须落在映像里、是官方操作码、不在已识别指令的中间,否则表在这一项结束;单张表最多 128 项。
12
+ // ------------------------------------------------------------------------
13
+ import { KIND_ADDRESS, KIND_OPCODE, KIND_UNKNOWN } from './byte-kinds.mjs';
14
+ import { OPCODES } from './opcode-table.mjs';
15
+
16
+ const LDA_ABS_Y = 0xb9;
17
+ const LDA_ABS_X = 0xbd;
18
+ const PHA = 0x48;
19
+ const RTS = 0x60;
20
+ const JMP_INDIRECT = 0x6c;
21
+
22
+ /** 加载指令之后检查的顺序指令条数 */
23
+ const WINDOW = 10;
24
+
25
+ /** 单张表的最大项数 */
26
+ const MAX_ENTRIES = 128;
27
+
28
+ /**
29
+ * @typedef {object} AddressTable
30
+ * @property {string} key 表的标识,同一张表只返回一次
31
+ * @property {number|null} wordOffset 字表在映像里的偏移;分开的两张表为 null
32
+ * @property {number[]} targets 表里读出的目标地址
33
+ */
34
+
35
+ /**
36
+ * 判断一个目标地址能不能作为代码入口。
37
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array}} image 映像与分类
38
+ * @param {number} target 目标地址
39
+ * @returns {boolean} 在映像内、是官方操作码、不在已识别指令中间
40
+ */
41
+ function isCodeTarget({ bytes, base, kinds }, target) {
42
+ const offset = target - base;
43
+ if (offset < 0 || offset >= bytes.length) return false;
44
+ if (OPCODES[bytes[offset]] === null) return false;
45
+ return kinds[offset] === KIND_UNKNOWN || kinds[offset] === KIND_OPCODE;
46
+ }
47
+
48
+ /**
49
+ * 从字表的偏移处读出连续的目标,遇到不能当入口的值或已识别的字节就停止。
50
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array}} image 映像与分类
51
+ * @param {number} start 表在映像里的偏移
52
+ * @param {number} adjust 加到每个值上的偏移,RTS 表为 1
53
+ * @returns {number[]} 目标地址
54
+ */
55
+ function readWordTable(image, start, adjust) {
56
+ const { bytes, kinds } = image;
57
+ const targets = [];
58
+ for (let offset = start; offset + 1 < bytes.length && targets.length < MAX_ENTRIES; offset += 2) {
59
+ if (kinds[offset] !== KIND_UNKNOWN || kinds[offset + 1] !== KIND_UNKNOWN) break;
60
+ const target = (bytes.readUInt16LE(offset) + adjust) & 0xffff;
61
+ if (!isCodeTarget(image, target)) break;
62
+ targets.push(target);
63
+ }
64
+ return targets;
65
+ }
66
+
67
+ /**
68
+ * 读出低、高字节分开的两张表。
69
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array}} image 映像与分类
70
+ * @param {number} lowOffset 低字节表的偏移
71
+ * @param {number} highOffset 高字节表的偏移
72
+ * @returns {number[]} 目标地址(已加 1)
73
+ */
74
+ function readSplitTable(image, lowOffset, highOffset) {
75
+ const { bytes, kinds } = image;
76
+ const targets = [];
77
+ while (targets.length < MAX_ENTRIES) {
78
+ const low = lowOffset + targets.length;
79
+ const high = highOffset + targets.length;
80
+ if (low >= bytes.length || high >= bytes.length || kinds[low] !== KIND_UNKNOWN || kinds[high] !== KIND_UNKNOWN) break;
81
+ const target = ((bytes[high] << 8) | bytes[low]) + 1;
82
+ if (!isCodeTarget(image, target & 0xffff)) break;
83
+ targets.push(target & 0xffff);
84
+ }
85
+ return targets;
86
+ }
87
+
88
+ /**
89
+ * 取出某条指令之后的顺序指令的偏移,遇到未识别的字节就停止。
90
+ * @param {{bytes: Buffer, kinds: Uint8Array}} image 映像与分类
91
+ * @param {number} offset 起点指令的偏移
92
+ * @returns {number[]} 起点之后最多 WINDOW 条指令的偏移
93
+ */
94
+ function followingInstructions({ bytes, kinds }, offset) {
95
+ const result = [];
96
+ let current = offset + OPCODES[bytes[offset]][1];
97
+ while (result.length < WINDOW && current < bytes.length && kinds[current] === KIND_OPCODE) {
98
+ result.push(current);
99
+ current += OPCODES[bytes[current]][1];
100
+ }
101
+ return result;
102
+ }
103
+
104
+ /**
105
+ * 查找经地址表分发的跳转,只返回还没有返回过的表。
106
+ * @param {{bytes: Buffer, base: number, kinds: Uint8Array, seen: Set<string>}} input 映像、分类与已返回过的表的标识
107
+ * @returns {AddressTable[]} 新找到的表
108
+ */
109
+ export function findAddressTables({ bytes, base, kinds, seen }) {
110
+ const image = { bytes, base, kinds };
111
+ const found = [];
112
+ const add = (key, wordOffset, targets) => {
113
+ if (seen.has(key) || targets.length === 0) return;
114
+ seen.add(key);
115
+ found.push({ key, wordOffset, targets });
116
+ };
117
+
118
+ for (let offset = 0; offset < bytes.length; offset += 1) {
119
+ if (kinds[offset] !== KIND_OPCODE) continue;
120
+ const opcode = bytes[offset];
121
+
122
+ if (opcode === JMP_INDIRECT) {
123
+ const tableOffset = bytes.readUInt16LE(offset + 1) - base;
124
+ if (tableOffset >= 0 && tableOffset < bytes.length) add(`w:${tableOffset}:0`, tableOffset, readWordTable(image, tableOffset, 0));
125
+ continue;
126
+ }
127
+ if (opcode !== LDA_ABS_X && opcode !== LDA_ABS_Y) continue;
128
+
129
+ const window = followingInstructions(image, offset);
130
+ const loads = [offset, ...window.filter((index) => bytes[index] === LDA_ABS_X || bytes[index] === LDA_ABS_Y)];
131
+ if (loads.length < 2) continue;
132
+ const addresses = loads.map((index) => bytes.readUInt16LE(index + 1) - base);
133
+ const pushes = window.filter((index) => bytes[index] === PHA).length;
134
+ const returns = window.some((index) => bytes[index] === RTS);
135
+ const indirect = window.some((index) => bytes[index] === JMP_INDIRECT);
136
+
137
+ if (indirect) {
138
+ // 两条加载的地址相差 1:字表在较小的地址上
139
+ const low = Math.min(addresses[0], addresses[1]);
140
+ if (Math.abs(addresses[0] - addresses[1]) === 1 && low >= 0 && low < bytes.length) add(`w:${low}:0`, low, readWordTable(image, low, 0));
141
+ } else if (pushes >= 2 && returns) {
142
+ // 先压入高字节再压入低字节,RTS 返回到“表里的值加 1”
143
+ const high = addresses[0];
144
+ const low = addresses[1];
145
+ if (high < 0 || low < 0 || high >= bytes.length || low >= bytes.length) continue;
146
+ if (Math.abs(high - low) === 1 && low < high) add(`w:${low}:1`, low, readWordTable(image, low, 1));
147
+ else if (Math.abs(high - low) > 1) add(`s:${low}:${high}`, null, readSplitTable(image, low, high));
148
+ }
149
+ }
150
+ return found;
151
+ }
152
+
153
+ /**
154
+ * 把字表占的字节标成地址。
155
+ * @param {Uint8Array} kinds 每个字节的分类
156
+ * @param {AddressTable} table 字表
157
+ */
158
+ export function markWordTable(kinds, table) {
159
+ if (table.wordOffset === null) return;
160
+ for (let index = 0; index < table.targets.length * 2; index += 1) kinds[table.wordOffset + index] = KIND_ADDRESS;
161
+ }
@@ -1,23 +1,19 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:analysis.mjs
3
- // 说明:静态追踪:从入口出发沿控制流标出哪些字节是指令的操作码、哪些是操作数;CDL 里的代码段起点也当作入口。
3
+ // 说明:静态追踪:从入口出发沿控制流标出哪些字节是指令的操作码、哪些是操作数;CDL 里的代码段起点也当作入口;追完后再从地址表里找新入口。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
- // 日期:2026-11-10
6
+ // 日期:2026-11-13
7
7
  // 备注:处理规则:顺序执行继续,条件分支两路都追,JMP 只追目标,JSR 追目标并假定会返回,RTS、RTI、BRK、间接 JMP 结束这一路;
8
8
  // 遇到非法操作码、越界或与已识别指令重叠时放弃这一路并记入警告。没被追到的字节都算数据,这不影响回读校验(da65 对非法操作码输出 .byte)。
9
+ // 待办的入口追完后,查找经地址表分发的跳转(见 address-tables.mjs),表里的目标成为新入口,直到没有新表。
9
10
  // ------------------------------------------------------------------------
11
+ import { findAddressTables, markWordTable } from './address-tables.mjs';
12
+ import { KIND_OPCODE, KIND_OPERAND, KIND_UNKNOWN } from './byte-kinds.mjs';
10
13
  import { CDL_CODE } from './cdl.mjs';
11
14
  import { OPCODES } from './opcode-table.mjs';
12
15
 
13
- /** 字节分类:没有被标成指令 */
14
- export const KIND_UNKNOWN = 0;
15
-
16
- /** 字节分类:指令的第一个字节 */
17
- export const KIND_OPCODE = 1;
18
-
19
- /** 字节分类:指令的操作数 */
20
- export const KIND_OPERAND = 2;
16
+ export { KIND_ADDRESS, KIND_OPCODE, KIND_OPERAND, KIND_UNKNOWN } from './byte-kinds.mjs';
21
17
 
22
18
  /**
23
19
  * @typedef {object} Analysis
@@ -53,7 +49,17 @@ export function analyzeCode({ bytes, base, entries, cdl = null }) {
53
49
  }
54
50
  }
55
51
 
56
- while (pending.length > 0) {
52
+ const seenTables = new Set();
53
+ const discoverTables = () => {
54
+ const tables = findAddressTables({ bytes, base, kinds, seen: seenTables });
55
+ for (const table of tables) {
56
+ markWordTable(kinds, table);
57
+ pending.push(...table.targets);
58
+ }
59
+ return tables.length > 0;
60
+ };
61
+
62
+ while (pending.length > 0 || discoverTables()) {
57
63
  let address = pending.pop();
58
64
  // 沿着顺序执行一路走下去,遇到分支目标或调用目标就放进待办
59
65
  for (;;) {
@@ -0,0 +1,20 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:byte-kinds.mjs
3
+ // 说明:反汇编分析里每个字节的分类常量。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-13
7
+ // 备注:无
8
+ // ------------------------------------------------------------------------
9
+
10
+ /** 字节分类:没有被标成指令或地址表 */
11
+ export const KIND_UNKNOWN = 0;
12
+
13
+ /** 字节分类:指令的第一个字节 */
14
+ export const KIND_OPCODE = 1;
15
+
16
+ /** 字节分类:指令的操作数 */
17
+ export const KIND_OPERAND = 2;
18
+
19
+ /** 字节分类:地址表里的字节,两个字节一个地址 */
20
+ export const KIND_ADDRESS = 3;
@@ -10,7 +10,8 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
10
10
  import path from 'node:path';
11
11
  import { FcdevError } from '../shared/index.mjs';
12
12
  import { runTool } from '../toolchain/index.mjs';
13
- import { KIND_UNKNOWN, analyzeCode } from './analysis.mjs';
13
+ import { analyzeCode } from './analysis.mjs';
14
+ import { KIND_OPCODE, KIND_OPERAND } from './byte-kinds.mjs';
14
15
  import { parseCdl } from './cdl.mjs';
15
16
  import { buildRanges, renderInfo } from './info-writer.mjs';
16
17
  import { loadBinary, loadInes } from './loaders.mjs';
@@ -99,7 +100,7 @@ export async function disassemble({ inputFile, format, base, entries = [], cdlFi
99
100
  });
100
101
  }
101
102
 
102
- const codeBytes = analysis.kinds.reduce((count, value) => count + (value === KIND_UNKNOWN ? 0 : 1), 0);
103
+ const codeBytes = analysis.kinds.reduce((count, value) => count + (value === KIND_OPCODE || value === KIND_OPERAND ? 1 : 0), 0);
103
104
  return {
104
105
  sourceFile,
105
106
  infoFile,
@@ -7,7 +7,7 @@
7
7
  // 备注:信息文件语法见 da65 的文档;RANGE 的结束地址包含在内;各段首尾相接、互不重叠,没有遗漏,da65 才不会把没说明的字节按默认当成代码。
8
8
  // ------------------------------------------------------------------------
9
9
  import { FcdevError } from '../shared/index.mjs';
10
- import { KIND_UNKNOWN } from './analysis.mjs';
10
+ import { KIND_ADDRESS, KIND_UNKNOWN } from './byte-kinds.mjs';
11
11
 
12
12
  /** ca65 标识符 */
13
13
  const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -24,14 +24,14 @@ export const VECTOR_TABLE_SIZE = 6;
24
24
 
25
25
  /**
26
26
  * 把映像划分成连续的段。
27
- * @param {{kinds: Uint8Array, base: number, hasVectors: boolean}} input 每个字节的分类、起始地址与是否有向量表(占最后 6 字节)
27
+ * @param {{kinds: Uint8Array, base: number, hasVectors: boolean}} input 每个字节的分类(含地址表)、起始地址与是否有向量表(占最后 6 字节)
28
28
  * @returns {Range[]} 覆盖整个映像的段,按地址排序
29
29
  */
30
30
  export function buildRanges({ kinds, base, hasVectors }) {
31
31
  const body = hasVectors ? kinds.length - VECTOR_TABLE_SIZE : kinds.length;
32
32
  const ranges = [];
33
33
  for (let offset = 0; offset < body; offset += 1) {
34
- const type = kinds[offset] === KIND_UNKNOWN ? 'ByteTable' : 'Code';
34
+ const type = kinds[offset] === KIND_UNKNOWN ? 'ByteTable' : (kinds[offset] === KIND_ADDRESS ? 'AddrTable' : 'Code');
35
35
  const last = ranges.at(-1);
36
36
  if (last && last.type === type) last.end = base + offset;
37
37
  else ranges.push({ start: base + offset, end: base + offset, type });
@@ -1,19 +1,15 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:doc-index.mjs
3
- // 说明:开发文档的查询:列出全部主题,按主题名、文件名或关键词查找,给出每份文档的本机路径与在线地址。
3
+ // 说明:开发文档的查询:列出全部主题,按主题名、文件名或关键词查找,给出每份文档的本机路径。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-11
7
- // 备注:文档随主包发布在包根的 docs 目录;在线地址由 package.json 的 repository 推出,分支固定为 master。
7
+ // 备注:文档随主包发布在包根的 docs 目录。
8
8
  // ------------------------------------------------------------------------
9
9
  import path from 'node:path';
10
10
  import { fileURLToPath } from 'node:url';
11
- import { FcdevError, readJsonFile } from '../shared/index.mjs';
12
11
  import { DOC_TOPICS } from './doc-topics.mjs';
13
12
 
14
- /** 在线文档所在的分支 */
15
- const ONLINE_BRANCH = 'master';
16
-
17
13
  /** 主包根目录 */
18
14
  const PACKAGE_DIR = fileURLToPath(new URL('../../', import.meta.url));
19
15
 
@@ -25,7 +21,6 @@ const PACKAGE_DIR = fileURLToPath(new URL('../../', import.meta.url));
25
21
  * @property {string} file 文件路径:相对 docs 目录,`inPackage` 为 true 时相对主包根目录
26
22
  * @property {boolean} [inPackage] 文件在主包根目录下的其他位置,不在 docs 目录里
27
23
  * @property {string} localPath 本机的绝对路径
28
- * @property {string} onlineUrl 在线地址
29
24
  */
30
25
 
31
26
  /**
@@ -37,32 +32,15 @@ export function docsDirectory() {
37
32
  }
38
33
 
39
34
  /**
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
- * 把登记项补全成带路径与地址的文档信息。
35
+ * 把登记项补全成带本机路径的文档信息。
56
36
  * @param {import('./doc-topics.mjs').DocTopic} entry 登记项
57
- * @param {string} base 主包在线目录的地址
58
37
  * @returns {DocInfo} 文档信息
59
38
  */
60
- function describe(entry, base) {
39
+ function describe(entry) {
61
40
  const segments = entry.file.split('/');
62
41
  return {
63
42
  ...entry,
64
43
  localPath: path.join(entry.inPackage ? PACKAGE_DIR : docsDirectory(), ...segments),
65
- onlineUrl: base + (entry.inPackage ? '' : 'docs/') + segments.map(encodeURIComponent).join('/'),
66
44
  };
67
45
  }
68
46
 
@@ -71,8 +49,7 @@ function describe(entry, base) {
71
49
  * @returns {DocInfo[]} 按登记顺序
72
50
  */
73
51
  export function listDocs() {
74
- const base = onlineBase();
75
- return DOC_TOPICS.map((entry) => describe(entry, base));
52
+ return DOC_TOPICS.map((entry) => describe(entry));
76
53
  }
77
54
 
78
55
  /**
@@ -21,7 +21,7 @@ export const DOC_TOPICS = [
21
21
  { topic: 'architecture', file: '01-软件架构设计.md', title: '软件架构设计', summary: '包的划分、目录、分层规则、设计决策与文档清单' },
22
22
  { topic: 'build', file: '02-命令行与构建.md', title: '命令行与构建', summary: '命令、构建规则、配置文件 fcdev.json、构建流程' },
23
23
  { topic: 'targets', file: '03-目标规范.md', title: '目标规范', summary: '目标定义、打包器、新增机型的步骤' },
24
- { topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与平台包' },
24
+ { topic: 'toolchain', file: '04-cc65工具链.md', title: 'cc65 工具链', summary: 'cc65 源码、构建与工具链包' },
25
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 的命令、模板与生成内容' },
@@ -32,7 +32,7 @@ export const DOC_TOPICS = [
32
32
  { topic: 'sb2000', file: 'sb2000/01-开发指南.md', title: 'SB2000 开发指南', summary: '程序格式、内存布局、运行库、大程序换页、常用做法、易错点与示例' },
33
33
  { topic: 'syscall', file: 'sb2000/02-系统调用手册.md', title: 'SB-DOS 系统调用手册', summary: '系统调用的参数、结果、出错码与可靠程度' },
34
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' },
35
+ { topic: 'api', file: 'targets/sb2000/api-reference.md', inPackage: true, title: 'SB2000 C 接口参考', summary: '运行库全部函数的签名、参数、返回值与系统调用,由头文件文档注释生成,查询用 npx fcdev api' },
36
36
  { topic: 'todo', file: '待办备忘.md', title: '待办备忘', summary: '已确定以后再做的事项' },
37
37
  { topic: 'bugs', file: '缺陷记录.md', title: '缺陷记录', summary: '发现的缺陷及修复情况' },
38
38
  ];
@@ -79,7 +79,7 @@ export class DebugClient {
79
79
  clearTimeout(timer);
80
80
  reject(new FcdevError(`无法连接调试服务(端口 ${port})`, {
81
81
  code: 'DEBUG_CONNECT_FAILED',
82
- hint: '先用 fcdev run --debug 启动模拟器,或检查端口是否一致',
82
+ hint: '先用 npx fcdev run --debug 启动模拟器,或检查端口是否一致',
83
83
  cause: error,
84
84
  }));
85
85
  });
@@ -1,10 +1,10 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:emulator-locator.mjs
3
- // 说明:定位模拟器程序:配置项、环境变量、平台包,按顺序查找。
3
+ // 说明:定位模拟器程序:配置项、环境变量、模拟器包,按顺序查找。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
7
- // 备注:模拟器只有 Windows 版;其他系统明确报错,不影响构建。
7
+ // 备注:无
8
8
  // ------------------------------------------------------------------------
9
9
  import { existsSync } from 'node:fs';
10
10
  import { createRequire } from 'node:module';
@@ -14,26 +14,19 @@ import { FcdevError } from '../shared/index.mjs';
14
14
  /** 环境变量:自备模拟器的路径 */
15
15
  export const EMULATOR_ENV_NAME = 'FCDEV_EMULATOR';
16
16
 
17
- /** 平台包里模拟器程序的相对路径 */
18
- const PACKAGE_EXECUTABLE = path.join('bin', 'VirtuaNES.exe');
17
+ /** 模拟器包的名称,放在 @rujianjs 作用域下 */
18
+ export const EMULATOR_PACKAGE_NAME = '@rujianjs/fcdev-emulator';
19
19
 
20
- /**
21
- * 模拟器平台包的名称,放在 @rujianjs 作用域下。
22
- * @param {string} [platform] 系统,默认当前系统
23
- * @param {string} [arch] 架构,默认当前架构
24
- * @returns {string} 包名
25
- */
26
- export function getEmulatorPackageName(platform = process.platform, arch = process.arch) {
27
- return `@rujianjs/fcdev-emulator-${platform}-${arch}`;
28
- }
20
+ /** 模拟器包里模拟器程序的相对路径 */
21
+ const PACKAGE_EXECUTABLE = path.join('bin', 'VirtuaNES.exe');
29
22
 
30
23
  /**
31
- * 按顺序定位模拟器:配置项 emulator、环境变量、平台包。
32
- * @param {{configured?: string, env?: NodeJS.ProcessEnv, platform?: string}} [options] configured 为配置里的绝对路径
24
+ * 按顺序定位模拟器:配置项 emulator、环境变量、模拟器包。
25
+ * @param {{configured?: string, env?: NodeJS.ProcessEnv}} [options] configured 为配置里的绝对路径
33
26
  * @returns {{executable: string, source: string}} 模拟器程序与来源
34
- * @throws {FcdevError} 系统不支持,或都找不到
27
+ * @throws {FcdevError} 都找不到
35
28
  */
36
- export function locateEmulator({ configured, env = process.env, platform = process.platform } = {}) {
29
+ export function locateEmulator({ configured, env = process.env } = {}) {
37
30
  const explicit = configured ? { executable: configured, source: 'config' } : env[EMULATOR_ENV_NAME] ? { executable: path.resolve(env[EMULATOR_ENV_NAME]), source: 'env' } : null;
38
31
  if (explicit) {
39
32
  if (!existsSync(explicit.executable)) {
@@ -41,22 +34,15 @@ export function locateEmulator({ configured, env = process.env, platform = proce
41
34
  }
42
35
  return explicit;
43
36
  }
44
- if (platform !== 'win32') {
45
- throw new FcdevError('模拟器只支持 Windows', {
46
- code: 'EMULATOR_UNSUPPORTED',
47
- hint: `其他系统可用 ${EMULATOR_ENV_NAME} 或 fcdev.json 的 emulator 指定自备的模拟器;构建不受影响`,
48
- });
49
- }
50
- const packageName = getEmulatorPackageName(platform);
51
37
  try {
52
- const packageJson = createRequire(import.meta.url).resolve(`${packageName}/package.json`);
38
+ const packageJson = createRequire(import.meta.url).resolve(`${EMULATOR_PACKAGE_NAME}/package.json`);
53
39
  const executable = path.join(path.dirname(packageJson), PACKAGE_EXECUTABLE);
54
40
  if (existsSync(executable)) return { executable, source: 'package' };
55
41
  } catch {
56
- // 平台包没有安装,落到下面统一的报错
42
+ // 模拟器包没有安装,落到下面统一的报错
57
43
  }
58
44
  throw new FcdevError('找不到模拟器', {
59
45
  code: 'EMULATOR_NOT_FOUND',
60
- hint: `任选一种:安装平台包 ${packageName};设置环境变量 ${EMULATOR_ENV_NAME} 指向模拟器程序;在 fcdev.json 里用 emulator 指定`,
46
+ hint: `任选一种:安装模拟器包 ${EMULATOR_PACKAGE_NAME};设置环境变量 ${EMULATOR_ENV_NAME} 指向模拟器程序;在 fcdev.json 里用 emulator 指定`,
61
47
  });
62
48
  }
@@ -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, getEmulatorPackageName, locateEmulator } from './emulator-locator.mjs';
11
+ export { EMULATOR_ENV_NAME, EMULATOR_PACKAGE_NAME, locateEmulator } from './emulator-locator.mjs';
@@ -8,8 +8,8 @@
8
8
  // ------------------------------------------------------------------------
9
9
  export {
10
10
  TOOLCHAIN_ENV_NAME,
11
+ TOOLCHAIN_PACKAGE_NAME,
11
12
  getToolPath,
12
- getToolchainPackageName,
13
13
  getToolchainVersion,
14
14
  locateToolchain,
15
15
  runTool,
@@ -1,6 +1,6 @@
1
1
  // ------------------------------------------------------------------------
2
2
  // 名称:toolchain-locator.mjs
3
- // 说明:定位 cc65 工具链并启动其中的工具:配置项、环境变量、平台包,按顺序查找。
3
+ // 说明:定位 cc65 工具链并启动其中的工具:配置项、环境变量、工具链包,按顺序查找。
4
4
  // 作者:sungbin
5
5
  // 邮箱:sungbin@3578.cn
6
6
  // 日期:2026-11-10
@@ -23,15 +23,8 @@ const REQUIRED_TOOLS = ['cc65', 'ca65', 'ld65'];
23
23
  * @property {string} source 来源:config、env 或 package
24
24
  */
25
25
 
26
- /**
27
- * 工具链平台包的名称,放在 @rujianjs 作用域下。
28
- * @param {string} [platform] 系统,默认当前系统
29
- * @param {string} [arch] 架构,默认当前架构
30
- * @returns {string} 包名
31
- */
32
- export function getToolchainPackageName(platform = process.platform, arch = process.arch) {
33
- return `@rujianjs/fcdev-cc65-${platform}-${arch}`;
34
- }
26
+ /** 工具链包的名称,放在 @rujianjs 作用域下 */
27
+ export const TOOLCHAIN_PACKAGE_NAME = '@rujianjs/fcdev-cc65';
35
28
 
36
29
  /**
37
30
  * 工具程序的完整路径。
@@ -40,8 +33,7 @@ export function getToolchainPackageName(platform = process.platform, arch = proc
40
33
  * @returns {string} 可执行文件路径
41
34
  */
42
35
  export function getToolPath(toolchain, tool) {
43
- const fileName = process.platform === 'win32' ? `${tool}.exe` : tool;
44
- return path.join(toolchain.home, 'bin', fileName);
36
+ return path.join(toolchain.home, 'bin', `${tool}.exe`);
45
37
  }
46
38
 
47
39
  /**
@@ -54,7 +46,7 @@ function isToolchainHome(home) {
54
46
  }
55
47
 
56
48
  /**
57
- * 按顺序定位工具链:配置项 toolchain、环境变量、平台包。
49
+ * 按顺序定位工具链:配置项 toolchain、环境变量、工具链包。
58
50
  * @param {{configured?: string, env?: NodeJS.ProcessEnv}} [options] configured 为配置里的 toolchain 绝对路径
59
51
  * @returns {Toolchain} 工具链
60
52
  * @throws {FcdevError} 都找不到,或指定的目录不完整
@@ -67,17 +59,16 @@ export function locateToolchain({ configured, env = process.env } = {}) {
67
59
  }
68
60
  return explicit;
69
61
  }
70
- const packageName = getToolchainPackageName();
71
62
  try {
72
- const packageJson = createRequire(import.meta.url).resolve(`${packageName}/package.json`);
63
+ const packageJson = createRequire(import.meta.url).resolve(`${TOOLCHAIN_PACKAGE_NAME}/package.json`);
73
64
  const home = path.dirname(packageJson);
74
65
  if (isToolchainHome(home)) return { home, source: 'package' };
75
66
  } catch {
76
- // 平台包没有安装,落到下面统一的报错
67
+ // 工具链包没有安装,落到下面统一的报错
77
68
  }
78
69
  throw new FcdevError('找不到 cc65 工具链', {
79
70
  code: 'TOOLCHAIN_NOT_FOUND',
80
- hint: `任选一种:安装平台包 ${packageName};设置环境变量 ${TOOLCHAIN_ENV_NAME} 指向自备的 cc65 目录;在 fcdev.json 里用 toolchain 指定目录`,
71
+ hint: `任选一种:安装工具链包 ${TOOLCHAIN_PACKAGE_NAME};设置环境变量 ${TOOLCHAIN_ENV_NAME} 指向自备的 cc65 目录;在 fcdev.json 里用 toolchain 指定目录`,
81
72
  });
82
73
  }
83
74
 
Binary file
Binary file