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 的 # 排除独立仓库的目录 小节。

进一步阅读

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.

README.md Unescape Escape

Viper Template Project

中文

这是什么

目录结构