Viper_TemplateProject/README.md

Viper Template Project

English | 中文

A minimal, ready-to-use template for bootstrapping a new Viper language project on Windows (x86_64-pc-windows-gnu).

Windows 平台（x86_64-pc-windows-gnu）下 Viper 语言新项目的最小可用模板。

---

中文

这是什么

ViperTemplateProject 是基于 Viper 语言的 Windows 桌面应用模板。克隆本仓库后，你可以立即得到一个能够：

• 设置 Windows 控制台为 UTF-8 编码（避免中文乱码）
• 打印一行 你好，世界
• 通过 llc + clang++（mingw 工具链）编译为原生 app.exe

的最小 Viper 项目。

模板对应的语言编译器是 TransPyC；关于 Viper 语言本身的概览，参见 TransPyC 仓库 wiki。

目录结构

ViperTemplateProject/
├── .gitignore           # 忽略 build/、*.o、*.exe、缓存等
├── README.md            # 本文件
├── project.vpj          # 项目配置（编译器、链接器、目标三元组等）
└── App/
    └── main.py          # 入口文件

前提条件

工具	说明
python ≥ 3.10	用于运行 TransPyC 编译器
llc	LLVM 静态编译器，编译 .ll → .o
clang++	mingw 工具链下的链接驱动（x86_64-w64-mingw32）
TransPyC 仓库	本编译器，克隆在 ViperTemplateProject/.. 同一目录下

环境变量建议（PowerShell）：

$env:PATH = "D:\msys64\mingw64\bin;D:\LLVM\bin;$env:PATH"

快速开始

# 1. 确保目录布局正确
#    D:\Users\TermiNexus\Desktop\TransPyC\
#    ├── TransPyC\        # 编译器仓库
#    └── ViperTemplateProject\   # 本仓库

cd D:\Users\TermiNexus\Desktop\TransPyC\ViperTemplateProject

# 2. 编译并运行
python ..\TransPyC\Projectrans.py `
    --project .\project.vpj `
    --clean-cache=false

# 3. 产物位于 output\app.exe
.\output\app.exe

预期输出：

你好，世界

编写你的第一个程序

打开 App/main.py，替换 print("你好，世界") 为任意合法 Viper 表达式。例如：

import w32.win32console as w32cmd
import t, c

pagecode: t.CDefine = 65001

@t.CExport
def main() -> int:
    w32cmd.SetConsoleOutputCP(pagecode)
    w32cmd.SetConsoleCP(pagecode)

    # 你的代码从这里开始
    a: t.CInt = 1
    b: t.CInt = 2
    print("a + b =", a + b)

    return 0

修改项目配置

打开 project.vpj，按需调整：

字段	含义	模板默认值
name	项目名（仅显示用）	Standard Template Project
source_dir	源文件根目录	./App
temp_dir	中间产物目录（.pyi / .stub.ll）	./temp
output_dir	最终产物目录	./output
compiler.cmd	汇编器	llc
compiler.flags	传给 llc 的参数	["-filetype=obj", "-relocation-model=pic"]
linker.cmd	链接器	clang++
linker.flags	链接器参数	mingw 标准库 + kernel32
linker.output	产物名	app.exe
includes	标准库搜索路径	["../includes"]
target.triple	LLVM 目标三元组	x86_64-pc-windows-gnu
target.datalayout	LLVM 数据布局	mingw 默认
options.target	后端目标	llvm
options.strict_mode	严格类型检查	true
options.slice_level	切片级别	3

跨平台使用

本模板默认针对 Windows + mingw。若需在其他平台使用，修改 project.vpj 的 compiler.cmd / linker.cmd / target.triple：

• Linux (x86_64)：triple = "x86_64-unknown-linux-gnu"，linker.cmd = "clang++"
• macOS (x86_64)：triple = "x86_64-apple-darwin*"，linker.cmd = "clang++"
• 裸机 x86_64 (ViperOS)：triple = "x86_64-none-elf"，linker.cmd = "ld.lld"，需要 isr.s 启动文件

常见问题

Q: 报错 cannot find includes/os / cannot find includes/atom 之类？ A: 检查 project.vpj 中的 includes 字段是否指向 TransPyC/includes。../includes 假设本仓库与 TransPyC 仓库同级。

Q: 输出 app.exe 双击闪退？ A: 在终端中运行 .\output\app.exe 而非双击，并确认 mingw 与 LLVM 在 PATH 中。

Q: 想完全清理构建产物？ A: 使用 python ..\TransPyC\Projectrans.py --project .\project.vpj --clean-cache 清理缓存；删除 output/ 和 temp/ 即可彻底重置。

Q: StandardTemplateProject 和本仓库是什么关系？ A: 本仓库 ViperTemplateProject 是 StandardTemplateProject 的独立仓库版本。如果你仍想保留 StandardTemplateProject 放在 TransPyC 仓库内，只需把它加入 TransPyC/.gitignore 的 # 排除独立仓库的目录 小节。

进一步阅读

• Viper 语言概览
• 类型系统
• OOP 与对象模型
• 自举路线图

---

English

What is this

ViperTemplateProject is a Windows desktop application template based on the Viper language. After cloning, you immediately have a minimal Viper project that:

• Sets the Windows console to UTF-8 (avoids mojibake for non-ASCII output)
• Prints 你好，世界
• Compiles to a native app.exe via llc + clang++ (mingw toolchain)

The corresponding compiler is TransPyC. For a Viper language overview, see the TransPyC wiki.

Directory layout

ViperTemplateProject/
├── .gitignore           # ignores build/, *.o, *.exe, caches, etc.
├── README.md            # this file
├── project.vpj          # project config (compiler, linker, target triple, ...)
└── App/
    └── main.py          # entry point

Prerequisites

Tool	Notes
python ≥ 3.10	runs the TransPyC compiler
llc	LLVM static compiler, .ll → .o
clang++	mingw toolchain driver (x86_64-w64-mingw32)
TransPyC repo	the compiler, cloned as a sibling of ViperTemplateProject

Suggested PATH (PowerShell):

$env:PATH = "D:\msys64\mingw64\bin;D:\LLVM\bin;$env:PATH"

Quick start

# 1. Make sure the layout is right
#    D:\Users\TermiNexus\Desktop\TransPyC\
#    ├── TransPyC\             # compiler repo
#    └── ViperTemplateProject\ # this repo

cd D:\Users\TermiNexus\Desktop\TransPyC\ViperTemplateProject

# 2. Build and run
python ..\TransPyC\Projectrans.py `
    --project .\project.vpj `
    --clean-cache=false

# 3. Output is at output\app.exe
.\output\app.exe

Expected output:

你好，世界

Writing your first program

Open App/main.py and replace print("你好，世界") with any valid Viper expression. Example:

import w32.win32console as w32cmd
import t, c

pagecode: t.CDefine = 65001

@t.CExport
def main() -> int:
    w32cmd.SetConsoleOutputCP(pagecode)
    w32cmd.SetConsoleCP(pagecode)

    # your code goes here
    a: t.CInt = 1
    b: t.CInt = 2
    print("a + b =", a + b)

    return 0

Editing project.vpj

Field	Meaning	Template default
name	display name	Standard Template Project
source_dir	source root	./App
temp_dir	intermediate artifacts (.pyi / .stub.ll)	./temp
output_dir	final artifacts	./output
compiler.cmd	assembler	llc
compiler.flags	flags passed to llc	["-filetype=obj", "-relocation-model=pic"]
linker.cmd	linker	clang++
linker.flags	linker flags	mingw stdlib + kernel32
linker.output	output name	app.exe
includes	standard library search paths	["../includes"]
target.triple	LLVM target triple	x86_64-pc-windows-gnu
target.datalayout	LLVM data layout	mingw default
options.target	backend target	llvm
options.strict_mode	strict type checking	true
options.slice_level	slice level	3

Cross-platform use

This template targets Windows + mingw by default. To use on another platform, adjust compiler.cmd / linker.cmd / target.triple in project.vpj:

• Linux (x86_64): triple = "x86_64-unknown-linux-gnu", linker.cmd = "clang++"
• macOS (x86_64): triple = "x86_64-apple-darwin*", linker.cmd = "clang++"
• Bare-metal x86_64 (ViperOS): triple = "x86_64-none-elf", linker.cmd = "ld.lld", requires isr.s startup

FAQ

Q: Error like cannot find includes/os or cannot find includes/atom? A: Check that the includes field in project.vpj points to the TransPyC/includes directory. ../includes assumes this repo lives next to TransPyC.

Q: app.exe flashes and closes on double-click? A: Run .\output\app.exe from a terminal, not by double-clicking. Make sure mingw and LLVM are on PATH.

Q: How to fully clean build artifacts? A: python ..\TransPyC\Projectrans.py --project .\project.vpj --clean-cache clears the cache. To reset everything, also delete output/ and temp/.

Q: What is the relationship with StandardTemplateProject? A: This repo ViperTemplateProject is the standalone-repo version of StandardTemplateProject. If you still want StandardTemplateProject to live inside the TransPyC repo, add it to the # 排除独立仓库的目录 section in TransPyC/.gitignore.

Further reading

• Viper language overview
• Type system
• OOP and object model
• Bootstrapping roadmap