fcdev 0.0.0-stage → 0.1.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/LICENSE +201 -0
- package/README.md +81 -2
- package/bin/fcdev.mjs +17 -0
- package/package.json +38 -4
- package/src/build/build-plan.mjs +92 -0
- package/src/build/dependency-file.mjs +24 -0
- package/src/build/disk-builder.mjs +36 -0
- package/src/build/index.mjs +31 -0
- package/src/build/program-builder.mjs +209 -0
- package/src/build/source-collector.mjs +54 -0
- package/src/build/tool-arguments.mjs +83 -0
- package/src/cli/args-parser.mjs +84 -0
- package/src/cli/commands/build-command.mjs +34 -0
- package/src/cli/commands/debug-command.mjs +70 -0
- package/src/cli/commands/disasm-command.mjs +65 -0
- package/src/cli/commands/disk-command.mjs +34 -0
- package/src/cli/commands/info-command.mjs +33 -0
- package/src/cli/commands/project-info.mjs +57 -0
- package/src/cli/commands/run-command.mjs +68 -0
- package/src/cli/commands/sync-command.mjs +85 -0
- package/src/cli/index.mjs +100 -0
- package/src/config/config-loader.mjs +132 -0
- package/src/config/index.mjs +9 -0
- package/src/disasm/analysis.mjs +97 -0
- package/src/disasm/cdl.mjs +35 -0
- package/src/disasm/disassembler.mjs +114 -0
- package/src/disasm/index.mjs +16 -0
- package/src/disasm/info-writer.mjs +72 -0
- package/src/disasm/loaders.mjs +69 -0
- package/src/disasm/opcode-table.mjs +268 -0
- package/src/disasm/roundtrip.mjs +69 -0
- package/src/disasm/symbols.mjs +30 -0
- package/src/disasm/trace.mjs +25 -0
- package/src/emulator/debug-client.mjs +125 -0
- package/src/emulator/emulator-launcher.mjs +80 -0
- package/src/emulator/emulator-locator.mjs +62 -0
- package/src/emulator/index.mjs +11 -0
- package/src/packagers/fat-floppy.mjs +22 -0
- package/src/packagers/fat12-image.mjs +245 -0
- package/src/packagers/flat-binary.mjs +53 -0
- package/src/packagers/index.mjs +54 -0
- package/src/packagers/ines.mjs +38 -0
- package/src/shared/errors.mjs +25 -0
- package/src/shared/fs-utils.mjs +66 -0
- package/src/shared/index.mjs +11 -0
- package/src/shared/process.mjs +50 -0
- package/src/targets/index.mjs +17 -0
- package/src/targets/name-rules.mjs +33 -0
- package/src/targets/target-registry.mjs +187 -0
- package/src/toolchain/index.mjs +16 -0
- package/src/toolchain/toolchain-locator.mjs +104 -0
- package/targets/nes/asminc/fcnes.inc +16 -0
- package/targets/nes/chr/ascii-8x8.chr +0 -0
- package/targets/nes/chr/font8x8_basic.h +152 -0
- package/targets/nes/include/fcnes.h +45 -0
- package/targets/nes/lib/fcnes.lib +0 -0
- package/targets/nes/lib/nes-font.o +0 -0
- package/targets/nes/lib-build.json +9 -0
- package/targets/nes/src/fcnes.s +91 -0
- package/targets/nes/src/nes-font.s +12 -0
- package/targets/nes/target.json +27 -0
- package/targets/sb2000/asminc/sb2000.inc +216 -0
- package/targets/sb2000/include/sb2000-symbols.h +380 -0
- package/targets/sb2000/include/sb2000.h +52 -0
- package/targets/sb2000/lib/crt0.o +0 -0
- package/targets/sb2000/lib/sb2000.lib +0 -0
- package/targets/sb2000/lib-build.json +8 -0
- package/targets/sb2000/link.cfg +35 -0
- package/targets/sb2000/src/crt0.s +37 -0
- package/targets/sb2000/src/sb2000.s +67 -0
- package/targets/sb2000/target.json +28 -0
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:ines.mjs
|
|
3
|
+
// 说明:iNES 打包器:校验链接输出以 iNES 文件头开头,写成 .nes 文件。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:iNES 头由 cc65 的 nes.cfg 生成,这里只校验,不改写内容。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import { readFileSync, writeFileSync } from 'node:fs';
|
|
10
|
+
import { FcdevError } from '../shared/index.mjs';
|
|
11
|
+
|
|
12
|
+
/** iNES 文件头的前 4 个字节:“NES”加 $1A */
|
|
13
|
+
const INES_MAGIC = Buffer.from([0x4e, 0x45, 0x53, 0x1a]);
|
|
14
|
+
|
|
15
|
+
/** iNES 文件头的长度 */
|
|
16
|
+
const INES_HEADER_SIZE = 16;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* 校验并写出 .nes 文件。
|
|
20
|
+
* @param {{binaryFile: string, outputFile: string}} input 链接输出与产物路径
|
|
21
|
+
* @returns {{outputFile: string, size: number}} 产物路径与大小
|
|
22
|
+
* @throws {FcdevError} 文件头不是 iNES,或文件长度与头里声明的不符
|
|
23
|
+
*/
|
|
24
|
+
export function packInes({ binaryFile, outputFile }) {
|
|
25
|
+
const image = readFileSync(binaryFile);
|
|
26
|
+
if (image.length < INES_HEADER_SIZE || !image.subarray(0, 4).equals(INES_MAGIC)) {
|
|
27
|
+
throw new FcdevError('链接输出不是 iNES 格式(缺少 “NES” 文件头)', {
|
|
28
|
+
code: 'PACKAGE_HEADER_MISMATCH',
|
|
29
|
+
hint: '检查链接配置是否生成 iNES 头',
|
|
30
|
+
});
|
|
31
|
+
}
|
|
32
|
+
const expectedSize = INES_HEADER_SIZE + image[4] * 0x4000 + image[5] * 0x2000;
|
|
33
|
+
if (image.length !== expectedSize) {
|
|
34
|
+
throw new FcdevError(`iNES 文件长度 ${image.length} 字节,与文件头声明的 ${expectedSize} 字节不符`, { code: 'PACKAGE_SIZE_MISMATCH' });
|
|
35
|
+
}
|
|
36
|
+
writeFileSync(outputFile, image);
|
|
37
|
+
return { outputFile, size: image.length };
|
|
38
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:errors.mjs
|
|
3
|
+
// 说明:fcdev 的统一错误类型:带错误码与下一步建议,命令行据此给用户输出可操作的提示。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:无
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* 可预期的使用错误(配置有误、找不到工具、构建失败等)。
|
|
12
|
+
* 程序自身的缺陷不用这个类,直接抛出原始异常。
|
|
13
|
+
*/
|
|
14
|
+
export class FcdevError extends Error {
|
|
15
|
+
/**
|
|
16
|
+
* @param {string} message 说明发生了什么
|
|
17
|
+
* @param {{code?: string, hint?: string, cause?: unknown}} [options] code 为错误码;hint 为下一步怎么做;cause 为原始原因
|
|
18
|
+
*/
|
|
19
|
+
constructor(message, { code = 'FCDEV_ERROR', hint = '', cause } = {}) {
|
|
20
|
+
super(message, cause === undefined ? undefined : { cause });
|
|
21
|
+
this.name = 'FcdevError';
|
|
22
|
+
this.code = code;
|
|
23
|
+
this.hint = hint;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:fs-utils.mjs
|
|
3
|
+
// 说明:文件系统小工具:读 JSON、取修改时间、递归创建目录。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:无
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import { mkdirSync, readFileSync, statSync } from 'node:fs';
|
|
10
|
+
import { FcdevError } from './errors.mjs';
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* 读取并解析 JSON 文件。
|
|
14
|
+
* @param {string} file 文件路径
|
|
15
|
+
* @returns {unknown} 解析后的值
|
|
16
|
+
* @throws {FcdevError} 文件不存在或内容不是合法的 JSON
|
|
17
|
+
*/
|
|
18
|
+
export function readJsonFile(file) {
|
|
19
|
+
let text;
|
|
20
|
+
try {
|
|
21
|
+
text = readFileSync(file, 'utf8');
|
|
22
|
+
} catch (error) {
|
|
23
|
+
throw new FcdevError(`无法读取文件 ${file}`, { code: 'FILE_READ_FAILED', cause: error });
|
|
24
|
+
}
|
|
25
|
+
try {
|
|
26
|
+
return JSON.parse(text);
|
|
27
|
+
} catch (error) {
|
|
28
|
+
throw new FcdevError(`${file} 不是合法的 JSON`, { code: 'JSON_INVALID', cause: error });
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* 取文件的修改时间。
|
|
34
|
+
* @param {string} file 文件路径
|
|
35
|
+
* @returns {number|null} 毫秒时间戳;文件不存在时为 null
|
|
36
|
+
*/
|
|
37
|
+
export function getModifiedTime(file) {
|
|
38
|
+
try {
|
|
39
|
+
return statSync(file).mtimeMs;
|
|
40
|
+
} catch (error) {
|
|
41
|
+
if (error.code === 'ENOENT') return null;
|
|
42
|
+
throw error;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* 判断路径是否是已存在的目录。
|
|
48
|
+
* @param {string} target 路径
|
|
49
|
+
* @returns {boolean} 是目录时为 true;不存在时为 false
|
|
50
|
+
*/
|
|
51
|
+
export function isDirectory(target) {
|
|
52
|
+
try {
|
|
53
|
+
return statSync(target).isDirectory();
|
|
54
|
+
} catch (error) {
|
|
55
|
+
if (error.code === 'ENOENT') return false;
|
|
56
|
+
throw error;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* 递归创建目录,已存在时不报错。
|
|
62
|
+
* @param {string} dir 目录路径
|
|
63
|
+
*/
|
|
64
|
+
export function ensureDirectory(dir) {
|
|
65
|
+
mkdirSync(dir, { recursive: true });
|
|
66
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:index.mjs
|
|
3
|
+
// 说明:shared 目录的对外入口。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:其他目录只能经这个文件引用 shared。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
export { FcdevError } from './errors.mjs';
|
|
10
|
+
export { DEFAULT_TOOL_TIMEOUT_MS, runProcess } from './process.mjs';
|
|
11
|
+
export { ensureDirectory, getModifiedTime, isDirectory, readJsonFile } from './fs-utils.mjs';
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:process.mjs
|
|
3
|
+
// 说明:启动外部程序并收集输出:不经过 shell,参数逐个传递,带超时。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:编译、链接这类工具的输出原样保留,供上层透传给用户或问题匹配器。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import { spawn } from 'node:child_process';
|
|
10
|
+
import { FcdevError } from './errors.mjs';
|
|
11
|
+
|
|
12
|
+
/** 外部工具默认的超时时间,单位毫秒 */
|
|
13
|
+
export const DEFAULT_TOOL_TIMEOUT_MS = 120_000;
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* @typedef {object} ProcessResult
|
|
17
|
+
* @property {number} code 退出码
|
|
18
|
+
* @property {string} stdout 标准输出
|
|
19
|
+
* @property {string} stderr 标准错误
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* 运行外部程序并等待结束。
|
|
24
|
+
* @param {string} file 可执行文件路径
|
|
25
|
+
* @param {string[]} args 参数列表
|
|
26
|
+
* @param {{cwd?: string, env?: NodeJS.ProcessEnv, timeoutMs?: number}} [options] 工作目录、环境变量与超时
|
|
27
|
+
* @returns {Promise<ProcessResult>} 程序以非零退出码结束时不抛错,由调用者判断
|
|
28
|
+
* @throws {FcdevError} 程序无法启动或超时
|
|
29
|
+
*/
|
|
30
|
+
export function runProcess(file, args, { cwd, env, timeoutMs = DEFAULT_TOOL_TIMEOUT_MS } = {}) {
|
|
31
|
+
return new Promise((resolve, reject) => {
|
|
32
|
+
const child = spawn(file, args, { cwd, env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
|
|
33
|
+
const stdout = [];
|
|
34
|
+
const stderr = [];
|
|
35
|
+
const timer = setTimeout(() => {
|
|
36
|
+
child.kill();
|
|
37
|
+
reject(new FcdevError(`${file} 运行超过 ${timeoutMs} 毫秒,已终止`, { code: 'PROCESS_TIMEOUT' }));
|
|
38
|
+
}, timeoutMs);
|
|
39
|
+
child.stdout.on('data', (chunk) => stdout.push(chunk));
|
|
40
|
+
child.stderr.on('data', (chunk) => stderr.push(chunk));
|
|
41
|
+
child.on('error', (error) => {
|
|
42
|
+
clearTimeout(timer);
|
|
43
|
+
reject(new FcdevError(`无法启动 ${file}`, { code: 'PROCESS_START_FAILED', cause: error }));
|
|
44
|
+
});
|
|
45
|
+
child.on('close', (code) => {
|
|
46
|
+
clearTimeout(timer);
|
|
47
|
+
resolve({ code: code ?? -1, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') });
|
|
48
|
+
});
|
|
49
|
+
});
|
|
50
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:index.mjs
|
|
3
|
+
// 说明:targets 目录的对外入口。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:无
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
export { applyNameRule } from './name-rules.mjs';
|
|
10
|
+
export {
|
|
11
|
+
BUILTIN_TARGETS_DIR,
|
|
12
|
+
listTargetNames,
|
|
13
|
+
loadTarget,
|
|
14
|
+
parseTarget,
|
|
15
|
+
resolveTargetOptions,
|
|
16
|
+
resolveTargetPath,
|
|
17
|
+
} from './target-registry.mjs';
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:name-rules.mjs
|
|
3
|
+
// 说明:程序名规则:按目标声明的规则校验并规范化程序名。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:目前只有 DOS 8.3 一条规则;超长或含非法字符时报错,不静默截断。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import { FcdevError } from '../shared/index.mjs';
|
|
10
|
+
|
|
11
|
+
/** DOS 8.3 的主名:1 到 8 个字母、数字、下划线或连字符 */
|
|
12
|
+
const DOS_BASE_NAME = /^[A-Za-z0-9_-]{1,8}$/;
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* 按目标的程序名规则校验并规范化程序名。
|
|
16
|
+
* @param {string} name 程序名(不含扩展名)
|
|
17
|
+
* @param {string|null} rule 目标声明的规则;null 表示不限制
|
|
18
|
+
* @returns {string} 规范化后的程序名
|
|
19
|
+
* @throws {FcdevError} 程序名不符合规则
|
|
20
|
+
*/
|
|
21
|
+
export function applyNameRule(name, rule) {
|
|
22
|
+
if (rule === null) return name;
|
|
23
|
+
if (rule === 'dos-8.3') {
|
|
24
|
+
if (!DOS_BASE_NAME.test(name)) {
|
|
25
|
+
throw new FcdevError(`程序名“${name}”不符合 DOS 8.3 规则:主名为 1 到 8 个字母、数字、下划线或连字符`, {
|
|
26
|
+
code: 'NAME_INVALID',
|
|
27
|
+
hint: '在 fcdev.json 里用 name 指定程序名,或改文件名',
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
return name.toUpperCase();
|
|
31
|
+
}
|
|
32
|
+
throw new FcdevError(`未知的程序名规则:${rule}`, { code: 'TARGET_INVALID' });
|
|
33
|
+
}
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:target-registry.mjs
|
|
3
|
+
// 说明:目标注册表:读取 targets/<名>/target.json,校验字段,解析目标专用选项与路径。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:目标定义的字段含义见 docs/03-目标规范.md 第 2 节;新增机型只需新增目标目录,不改这里。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import { readdirSync } from 'node:fs';
|
|
10
|
+
import path from 'node:path';
|
|
11
|
+
import { fileURLToPath } from 'node:url';
|
|
12
|
+
import { FcdevError, isDirectory, readJsonFile } from '../shared/index.mjs';
|
|
13
|
+
|
|
14
|
+
/** 内置目标所在的目录 */
|
|
15
|
+
export const BUILTIN_TARGETS_DIR = fileURLToPath(new URL('../../targets/', import.meta.url));
|
|
16
|
+
|
|
17
|
+
/** 路径值里表示“相对于工具链根目录”的前缀 */
|
|
18
|
+
const TOOLCHAIN_PREFIX = 'toolchain:';
|
|
19
|
+
|
|
20
|
+
/** 运行方案的模式:rom 直接加载产物;firmware-disk 加载固件并挂载磁盘镜像 */
|
|
21
|
+
const RUN_MODES = new Set(['rom', 'firmware-disk']);
|
|
22
|
+
|
|
23
|
+
/** 目标专用选项允许的类型 */
|
|
24
|
+
const OPTION_TYPES = new Set(['boolean', 'string', 'number']);
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @typedef {object} Target
|
|
28
|
+
* @property {string} name 标识
|
|
29
|
+
* @property {string} title 显示名
|
|
30
|
+
* @property {string} dir 目标目录的绝对路径
|
|
31
|
+
* @property {string} cpu CPU 型号
|
|
32
|
+
* @property {string} cc65Target 传给 cc65 工具的目标名
|
|
33
|
+
* @property {string} linkConfig 链接配置(路径值)
|
|
34
|
+
* @property {string[]} startup 启动代码(路径值)
|
|
35
|
+
* @property {string[]} forceImports 链接时强制引入的符号(让库里的启动代码一定被链接)
|
|
36
|
+
* @property {string[]} libraries 链接的库(路径值)
|
|
37
|
+
* @property {string[]} include 头文件目录(路径值)
|
|
38
|
+
* @property {string[]} asminclude 汇编引入目录(路径值)
|
|
39
|
+
* @property {Record<string, string|number>} defines 预定义宏
|
|
40
|
+
* @property {string} packager 打包器名
|
|
41
|
+
* @property {Record<string, unknown>} packagerOptions 打包器选项
|
|
42
|
+
* @property {string} extension 产物扩展名
|
|
43
|
+
* @property {string|null} nameRule 程序名规则
|
|
44
|
+
* @property {object|null} disk 磁盘镜像能力
|
|
45
|
+
* @property {object|null} run 运行方案
|
|
46
|
+
* @property {Record<string, {type: string, default: unknown, links: string[]}>} options 目标专用选项;布尔选项为 true 时额外链接 links 里的文件(路径值)
|
|
47
|
+
*/
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* 校验一个字段是字符串数组。
|
|
51
|
+
* @param {unknown} value 字段值
|
|
52
|
+
* @param {string} field 字段名,用于出错提示
|
|
53
|
+
* @param {string} name 目标名
|
|
54
|
+
* @returns {string[]} 字段值
|
|
55
|
+
*/
|
|
56
|
+
function requireStringArray(value, field, name) {
|
|
57
|
+
if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
|
|
58
|
+
throw new FcdevError(`目标 ${name} 的 ${field} 必须是字符串数组`, { code: 'TARGET_INVALID' });
|
|
59
|
+
}
|
|
60
|
+
return value;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* 校验并规范化目标定义。
|
|
65
|
+
* @param {unknown} raw target.json 的内容
|
|
66
|
+
* @param {string} dir 目标目录
|
|
67
|
+
* @returns {Target} 目标
|
|
68
|
+
* @throws {FcdevError} 缺字段或类型不对
|
|
69
|
+
*/
|
|
70
|
+
export function parseTarget(raw, dir) {
|
|
71
|
+
const fallbackName = path.basename(dir);
|
|
72
|
+
if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
|
|
73
|
+
throw new FcdevError(`目标 ${fallbackName} 的 target.json 必须是对象`, { code: 'TARGET_INVALID' });
|
|
74
|
+
}
|
|
75
|
+
for (const field of ['name', 'title', 'cpu', 'cc65Target', 'linkConfig', 'packager', 'extension']) {
|
|
76
|
+
if (typeof raw[field] !== 'string' || raw[field] === '') {
|
|
77
|
+
throw new FcdevError(`目标 ${fallbackName} 缺少字符串字段 ${field}`, { code: 'TARGET_INVALID' });
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
if (raw.name !== fallbackName) {
|
|
81
|
+
throw new FcdevError(`目标目录 ${fallbackName} 与 target.json 中的 name(${raw.name})不一致`, { code: 'TARGET_INVALID' });
|
|
82
|
+
}
|
|
83
|
+
const options = {};
|
|
84
|
+
if (raw.run !== undefined && raw.run !== null) {
|
|
85
|
+
if (typeof raw.run.emulator !== 'string' || !RUN_MODES.has(raw.run.mode)) {
|
|
86
|
+
throw new FcdevError(`目标 ${raw.name} 的 run 必须包含 emulator,且 mode 为 ${[...RUN_MODES].join(' 或 ')}`, { code: 'TARGET_INVALID' });
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
for (const [key, spec] of Object.entries(raw.options ?? {})) {
|
|
90
|
+
if (!spec || !OPTION_TYPES.has(spec.type) || typeof spec.default !== spec.type) {
|
|
91
|
+
throw new FcdevError(`目标 ${raw.name} 的选项 ${key} 定义不合法`, { code: 'TARGET_INVALID' });
|
|
92
|
+
}
|
|
93
|
+
if (spec.links !== undefined && (spec.type !== 'boolean' || !Array.isArray(spec.links) || !spec.links.every((item) => typeof item === 'string'))) {
|
|
94
|
+
throw new FcdevError(`目标 ${raw.name} 的选项 ${key} 的 links 只能用于布尔选项,且必须是字符串数组`, { code: 'TARGET_INVALID' });
|
|
95
|
+
}
|
|
96
|
+
options[key] = { type: spec.type, default: spec.default, links: spec.links ?? [] };
|
|
97
|
+
}
|
|
98
|
+
return {
|
|
99
|
+
name: raw.name,
|
|
100
|
+
title: raw.title,
|
|
101
|
+
dir,
|
|
102
|
+
cpu: raw.cpu,
|
|
103
|
+
cc65Target: raw.cc65Target,
|
|
104
|
+
linkConfig: raw.linkConfig,
|
|
105
|
+
startup: requireStringArray(raw.startup ?? [], 'startup', raw.name),
|
|
106
|
+
forceImports: requireStringArray(raw.forceImports ?? [], 'forceImports', raw.name),
|
|
107
|
+
libraries: requireStringArray(raw.libraries ?? [], 'libraries', raw.name),
|
|
108
|
+
include: requireStringArray(raw.include ?? [], 'include', raw.name),
|
|
109
|
+
asminclude: requireStringArray(raw.asminclude ?? [], 'asminclude', raw.name),
|
|
110
|
+
defines: raw.defines ?? {},
|
|
111
|
+
packager: raw.packager,
|
|
112
|
+
packagerOptions: raw.packagerOptions ?? {},
|
|
113
|
+
extension: raw.extension,
|
|
114
|
+
nameRule: raw.nameRule ?? null,
|
|
115
|
+
disk: raw.disk ?? null,
|
|
116
|
+
run: raw.run ?? null,
|
|
117
|
+
options,
|
|
118
|
+
};
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* 列出目标目录下全部目标的名称。
|
|
123
|
+
* @param {string} [targetsDir] 目标所在目录
|
|
124
|
+
* @returns {string[]} 目标名,按字母排序
|
|
125
|
+
*/
|
|
126
|
+
export function listTargetNames(targetsDir = BUILTIN_TARGETS_DIR) {
|
|
127
|
+
return readdirSync(targetsDir, { withFileTypes: true })
|
|
128
|
+
.filter((entry) => entry.isDirectory())
|
|
129
|
+
.map((entry) => entry.name)
|
|
130
|
+
.sort();
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* 读取一个目标。
|
|
135
|
+
* @param {string} name 目标名
|
|
136
|
+
* @param {string} [targetsDir] 目标所在目录
|
|
137
|
+
* @returns {Target} 目标
|
|
138
|
+
* @throws {FcdevError} 目标不存在或定义不合法
|
|
139
|
+
*/
|
|
140
|
+
export function loadTarget(name, targetsDir = BUILTIN_TARGETS_DIR) {
|
|
141
|
+
const dir = path.join(targetsDir, name);
|
|
142
|
+
if (!/^[a-z0-9-]+$/.test(name) || !isDirectory(dir)) {
|
|
143
|
+
throw new FcdevError(`不支持的目标:${name}`, {
|
|
144
|
+
code: 'TARGET_UNKNOWN',
|
|
145
|
+
hint: `可用的目标:${listTargetNames(targetsDir).join('、')}`,
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
return parseTarget(readJsonFile(path.join(dir, 'target.json')), dir);
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* 把目标定义里的路径值换成绝对路径。
|
|
153
|
+
* @param {Target} target 目标
|
|
154
|
+
* @param {string} value 路径值:相对目标目录,或以 toolchain: 开头表示相对工具链根目录
|
|
155
|
+
* @param {string} toolchainHome 工具链根目录
|
|
156
|
+
* @returns {string} 绝对路径
|
|
157
|
+
*/
|
|
158
|
+
export function resolveTargetPath(target, value, toolchainHome) {
|
|
159
|
+
if (value.startsWith(TOOLCHAIN_PREFIX)) return path.join(toolchainHome, value.slice(TOOLCHAIN_PREFIX.length));
|
|
160
|
+
return path.join(target.dir, value);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* 合并用户给的目标专用选项与默认值,并校验。
|
|
165
|
+
* @param {Target} target 目标
|
|
166
|
+
* @param {Record<string, unknown>} given 配置里的 targetOptions
|
|
167
|
+
* @returns {Record<string, unknown>} 完整的选项
|
|
168
|
+
* @throws {FcdevError} 出现目标没有定义的选项,或类型不对
|
|
169
|
+
*/
|
|
170
|
+
export function resolveTargetOptions(target, given) {
|
|
171
|
+
const result = {};
|
|
172
|
+
for (const [key, spec] of Object.entries(target.options)) result[key] = spec.default;
|
|
173
|
+
for (const [key, value] of Object.entries(given)) {
|
|
174
|
+
const spec = target.options[key];
|
|
175
|
+
if (!spec) {
|
|
176
|
+
throw new FcdevError(`目标 ${target.name} 没有选项 ${key}`, {
|
|
177
|
+
code: 'TARGET_OPTION_UNKNOWN',
|
|
178
|
+
hint: Object.keys(target.options).length > 0 ? `可用的选项:${Object.keys(target.options).join('、')}` : '该目标没有可配置的选项',
|
|
179
|
+
});
|
|
180
|
+
}
|
|
181
|
+
if (typeof value !== spec.type) {
|
|
182
|
+
throw new FcdevError(`目标 ${target.name} 的选项 ${key} 类型应为 ${spec.type}`, { code: 'TARGET_OPTION_INVALID' });
|
|
183
|
+
}
|
|
184
|
+
result[key] = value;
|
|
185
|
+
}
|
|
186
|
+
return result;
|
|
187
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:index.mjs
|
|
3
|
+
// 说明:toolchain 目录的对外入口。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:无
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
export {
|
|
10
|
+
TOOLCHAIN_ENV_NAME,
|
|
11
|
+
getToolPath,
|
|
12
|
+
getToolchainPackageName,
|
|
13
|
+
getToolchainVersion,
|
|
14
|
+
locateToolchain,
|
|
15
|
+
runTool,
|
|
16
|
+
} from './toolchain-locator.mjs';
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
// ------------------------------------------------------------------------
|
|
2
|
+
// 名称:toolchain-locator.mjs
|
|
3
|
+
// 说明:定位 cc65 工具链并启动其中的工具:配置项、环境变量、平台包,按顺序查找。
|
|
4
|
+
// 作者:sungbin
|
|
5
|
+
// 邮箱:sungbin@3578.cn
|
|
6
|
+
// 日期:2026-11-10
|
|
7
|
+
// 备注:不使用 PATH 里的 cc65,避免版本不一致;调用工具时设置 CC65_HOME。
|
|
8
|
+
// ------------------------------------------------------------------------
|
|
9
|
+
import { existsSync } from 'node:fs';
|
|
10
|
+
import { createRequire } from 'node:module';
|
|
11
|
+
import path from 'node:path';
|
|
12
|
+
import { FcdevError, runProcess } from '../shared/index.mjs';
|
|
13
|
+
|
|
14
|
+
/** 环境变量:自备 cc65 的根目录 */
|
|
15
|
+
export const TOOLCHAIN_ENV_NAME = 'FCDEV_CC65_HOME';
|
|
16
|
+
|
|
17
|
+
/** 工具链里必须存在的程序 */
|
|
18
|
+
const REQUIRED_TOOLS = ['cc65', 'ca65', 'ld65'];
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* @typedef {object} Toolchain
|
|
22
|
+
* @property {string} home 工具链根目录
|
|
23
|
+
* @property {string} source 来源:config、env 或 package
|
|
24
|
+
*/
|
|
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
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* 工具程序的完整路径。
|
|
38
|
+
* @param {Toolchain} toolchain 工具链
|
|
39
|
+
* @param {string} tool 工具名,如 cc65
|
|
40
|
+
* @returns {string} 可执行文件路径
|
|
41
|
+
*/
|
|
42
|
+
export function getToolPath(toolchain, tool) {
|
|
43
|
+
const fileName = process.platform === 'win32' ? `${tool}.exe` : tool;
|
|
44
|
+
return path.join(toolchain.home, 'bin', fileName);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* 检查目录是否是完整的工具链根目录。
|
|
49
|
+
* @param {string} home 候选目录
|
|
50
|
+
* @returns {boolean} 含全部必需程序时为 true
|
|
51
|
+
*/
|
|
52
|
+
function isToolchainHome(home) {
|
|
53
|
+
return REQUIRED_TOOLS.every((tool) => existsSync(getToolPath({ home, source: '' }, tool)));
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* 按顺序定位工具链:配置项 toolchain、环境变量、平台包。
|
|
58
|
+
* @param {{configured?: string, env?: NodeJS.ProcessEnv}} [options] configured 为配置里的 toolchain 绝对路径
|
|
59
|
+
* @returns {Toolchain} 工具链
|
|
60
|
+
* @throws {FcdevError} 都找不到,或指定的目录不完整
|
|
61
|
+
*/
|
|
62
|
+
export function locateToolchain({ configured, env = process.env } = {}) {
|
|
63
|
+
const explicit = configured ? { home: configured, source: 'config' } : env[TOOLCHAIN_ENV_NAME] ? { home: path.resolve(env[TOOLCHAIN_ENV_NAME]), source: 'env' } : null;
|
|
64
|
+
if (explicit) {
|
|
65
|
+
if (!isToolchainHome(explicit.home)) {
|
|
66
|
+
throw new FcdevError(`${explicit.home} 不是完整的 cc65 目录(缺少 bin 下的 ${REQUIRED_TOOLS.join('、')})`, { code: 'TOOLCHAIN_INCOMPLETE' });
|
|
67
|
+
}
|
|
68
|
+
return explicit;
|
|
69
|
+
}
|
|
70
|
+
const packageName = getToolchainPackageName();
|
|
71
|
+
try {
|
|
72
|
+
const packageJson = createRequire(import.meta.url).resolve(`${packageName}/package.json`);
|
|
73
|
+
const home = path.dirname(packageJson);
|
|
74
|
+
if (isToolchainHome(home)) return { home, source: 'package' };
|
|
75
|
+
} catch {
|
|
76
|
+
// 平台包没有安装,落到下面统一的报错
|
|
77
|
+
}
|
|
78
|
+
throw new FcdevError('找不到 cc65 工具链', {
|
|
79
|
+
code: 'TOOLCHAIN_NOT_FOUND',
|
|
80
|
+
hint: `任选一种:安装平台包 ${packageName};设置环境变量 ${TOOLCHAIN_ENV_NAME} 指向自备的 cc65 目录;在 fcdev.json 里用 toolchain 指定目录`,
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* 运行工具链里的一个工具。
|
|
86
|
+
* @param {Toolchain} toolchain 工具链
|
|
87
|
+
* @param {string} tool 工具名
|
|
88
|
+
* @param {string[]} args 参数
|
|
89
|
+
* @param {{cwd?: string, timeoutMs?: number}} [options] 工作目录与超时
|
|
90
|
+
* @returns {Promise<import('../shared/index.mjs').ProcessResult>} 运行结果
|
|
91
|
+
*/
|
|
92
|
+
export function runTool(toolchain, tool, args, options = {}) {
|
|
93
|
+
return runProcess(getToolPath(toolchain, tool), args, { ...options, env: { ...process.env, CC65_HOME: toolchain.home } });
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* 读取工具链版本,用于增量构建的指纹。
|
|
98
|
+
* @param {Toolchain} toolchain 工具链
|
|
99
|
+
* @returns {Promise<string>} cc65 的版本输出,如 “cc65 V2.19 - Git 357f64e”
|
|
100
|
+
*/
|
|
101
|
+
export async function getToolchainVersion(toolchain) {
|
|
102
|
+
const result = await runTool(toolchain, 'cc65', ['--version']);
|
|
103
|
+
return (result.stderr || result.stdout).trim();
|
|
104
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
; ------------------------------------------------------------------------
|
|
2
|
+
; 名称:fcnes.inc
|
|
3
|
+
; 说明:NES 的 PPU 寄存器地址,汇编程序与 fcnes 库共用。
|
|
4
|
+
; 作者:sungbin
|
|
5
|
+
; 邮箱:sungbin@3578.cn
|
|
6
|
+
; 日期:2026-11-10
|
|
7
|
+
; 备注:只含符号定义,不占空间。
|
|
8
|
+
; ------------------------------------------------------------------------
|
|
9
|
+
PPUCTRL = $2000 ; 控制寄存器:名称表、图案表、NMI
|
|
10
|
+
PPUMASK = $2001 ; 显示开关:背景、精灵
|
|
11
|
+
PPUSTATUS = $2002 ; 状态:位 7 为垂直消隐;读取会复位 PPUADDR 与 PPUSCROLL 的写入顺序
|
|
12
|
+
OAMADDR = $2003 ; 精灵内存地址
|
|
13
|
+
OAMDATA = $2004 ; 精灵内存数据
|
|
14
|
+
PPUSCROLL = $2005 ; 滚动,连续写两次:水平、垂直
|
|
15
|
+
PPUADDR = $2006 ; 显存地址,连续写两次:高字节、低字节
|
|
16
|
+
PPUDATA = $2007 ; 显存数据,写入后地址自动递增
|
|
Binary file
|