快速开始
本节假设你已经完成 安装 (pip install codecin)。 下面所有命令既可以用安装后的 codecin, 也可以用源码树里的 codecin, 两者完全等价。
1. 第一个程序
新建 hello.cin:
function main() -> int {
println("Hello, Code CIN!")
println("2 + 3 = " + (2 + 3))
return 0
}运行:
codecin hello.cin实际输出 (日志行会与程序输出混在同一终端, 见下方提示):
08:37:15 INFO CIN compiled: 30 instructions
INFO Starting program execution
Hello, Code CIN!
2 + 3 = 5
INFO HALT instruction executed
INFO Program execution finished想要“干净”的输出
日志默认是 INFO 级别。脚本或对比输出时可加 --log-level ERROR:
codecin hello.cin --log-level ERRORHello, Code CIN!
2 + 3 = 5这段程序的要点:
main是入口函数 (不是必须叫main, 程序按源码顺序先执行全局初始化, 再到第一条语句);- 语句以换行结尾, 分号可选;
- 字符串用
+与任意类型拼接,println自动追加换行; -> int是返回类型, 省略时默认void。
2. 同一件事, 三种写法
Code CIN 的编译器/汇编器接受三种输入, 默认都产出 .sdgcc (其 CODE 段为 UCBC BIN v3):
function main() -> int {
println("Hello, Code CIN!")
return 0
}codecin hello.cin # 高级语言
codecin hello.pl # PL 关键字风格汇编
codecin hello.asm # 汇编- PL 风格使用关键字助记符 (
set/output/stop/compare/jump_zero/branch_link…), ASM 风格使用标准助记符 (MOV/OUT/HALT/CMP/JZ/BL…); 两种风格都由同一个codecin/assembler.py汇编, 语法细节见 汇编语法参考。 sys #24是宿主系统调用PRINT_STR(打印x0指向的 NUL 结尾字符串),out输出数值, 值为10时输出换行 —— 详见 指令语义参考。
3. 两条执行主线: Go 引擎与 cincc
默认路径由 Go 原生引擎执行 (详见 执行路径):
codecin hello.cin # 编译为 .sdgcc, 由 Go 引擎执行Python 侧负责编译与装载, 然后通过 ABI v2 的 codecin_run_v2 把整程序一次调用 交给 Go 原生引擎执行, 结束后回传寄存器/向量/标志/脏内存段与输出。 v5.9.0 起没有解释器/JIT 回退: 原生库缺失时会直接抛 CPUSimulatorError 并附 重建指引 (源码树 codecin/native/ 下的 build.ps1 / build.sh, 需 Go 1.26+), 所以安装后构建原生库是必要步骤。
v7.22.10 起也可以走 cincc 原生机器码路径 (不经 C、不经字节码):
codecin hello.cin --native # 编译为 x86-64 ELF 并运行 (Windows 经 WSL)
codecin hello.cin --native-out hello # 只构建, 不运行--native 需先构建 cincc (cd codecin/native && go build -o cincc ./cmd/cincc), 或设置 CODECIN_CINCC。它覆盖语言子集: 没有 GUI/画布/音频、HTTP/DNS、FFI。 完整宿主能力请用默认 .sdgcc 路径。
内存默认 1 GiB (4 KiB 稀疏分页、按需提交), 大数组/大缓冲不再需要 --mem-size。
4. 编译产物与内存镜像
# 编译为默认 .sdgcc 容器 (不执行)
codecin hello.cin --compile-only
# INFO CIN compiled: 30 instructions
# INFO Compiled to hello.sdgcc
# 显式要兼容 BIN v3 时:
codecin hello.cin --compile-only -o hello.bin
# 直接运行产物
codecin hello.sdgcc
# 反汇编查看字节码清单
codecin hello.sdgcc --disasm; CPUSA binary: 30 instructions, mem=1073741824 bytes, entry=0x0, sp=0x3ffffff8
;
0000: CALL #2
0001: HALT
0002: PUSH X29
0003: MOV X29 X32
0004: MOV X0 #0
0005: SYS #24运行后保存内存镜像 (段式 CROM v4, 默认 zlib 压缩, 只保存实际使用的内存页):
codecin hello.cin --save # 生成 hello.crom (固定为 <程序名>.crom, 不受 -o 影响)
codecin prog.asm --crom prog.crom # 汇编路径: 先恢复内存镜像再汇编并运行--crom 只对 .pl / .asm 生效
CPU.load_program 在 .cin、.sdgcc 与 .bin 分支会直接返回, 因此这些入口不会读取 --crom; .pl / .asm 还会自动探测同目录同名的 <程序名>.crom。CROM 是内存镜像而不是可执行文件 (直接 codecin x.crom 会被当作汇编源码而报错), 详见 二进制格式。
5. 生成独立可执行文件 (AOT) 与原生机器码
# AOT: 本机平台生成 hello.exe (Windows) / hello (Linux/macOS)
codecin hello.cin --build-exe hello
# 交叉编译 Linux 静态单文件
codecin hello.cin --build-exe app-linux --build-target linux/amd64 --build-static
# macOS 目标需显式使用 Go 后端 (C 后端不支持)
codecin hello.cin --build-exe app-mac --build-target darwin/arm64 --build-backend native默认 auto 后端优先使用 C 后端 (需系统 GCC/Clang 或 zig); C 不支持时回退 Go native/VM。产物运行时不需要 Python、Go 工具链或 Code CIN 动态库; C 后端默认动态 链接系统 C 库, --build-static 时静态链接。CIN/ASM/PL 也可 --emit-object + --link 独立编译链接, 详见 AOT 独立可执行文件。
如果只想要 cincc 直出的机器码 (不经 C/字节码), 用上一节的 --native-out。
6. 看看内置示例
仓库 examples/ 目录下的程序都可以直接跑, 输出如下 (用 --log-level ERROR 过滤日志):
codecin examples/control_flow.cin --log-level ERRORlevel: top
sum=20 d=4 pass覆盖 break / continue / do-while / switch / 三目 / 复合赋值。
运行示例前确认原生库就绪
所有示例 (尤其是 gui_demo.cin / local_audio.cin 这类宿主能力示例) 都依赖 Go 原生 引擎库。缺失时会直接抛 CPUSimulatorError, 用 codecin --build-info 可核对原生库 版本与包版本是否匹配, 重建方法见 安装 Code CIN。
7. 编辑器支持
仓库 misc/vim/ 提供 Vim 语法文件:
| 文件 | 作用 |
|---|---|
misc/vim/ftdetect/codecin.vim | 识别 .cin / .pl / .asm 文件类型 |
misc/vim/syntax/cin.vim | CIN 语言语法高亮 |
misc/vim/syntax/codecinasm.vim | 汇编语法高亮 |
把 misc/vim/* 拷进 ~/.vim/ (或 %USERPROFILE%\vimfiles\) 即可生效。