指令
Targo 通过 JSDoc 语法支持 Go 指令。
语法
typescript
/** @go:<directive> [arguments] */已支持的指令
| 指令 | 用途 |
|---|---|
@go:build | 文件构建约束 |
@go:generate | go generate 钩子 |
@go:embed | 嵌入文件或目录 |
@go:noinline | 禁止内联 |
@go:nosplit | 禁止栈分裂 |
@go:noescape | 标记函数参数不逃逸 |
@go:passthrough | 透传原始 Go 注释或指令 |
@go:build — 构建约束
放在文件顶部，控制何时将该文件纳入构建：
typescript
/** @go:build "linux && amd64" */
export function platformSpecific(): void {
// 仅在 linux/amd64 上编译
}@go:generate — 代码生成
触发 go generate 命令：
typescript
/** @go:generate "stringer -type=Status" */@go:embed — 文件嵌入
将文件或目录嵌入到二进制文件中。指令必须放在变量声明上方：
typescript
/** @go:embed "static/*" */
const staticFiles: embed.FS = zero<embed.FS>();嵌入单个文件为字符串：
typescript
/** @go:embed "version.txt" */
const version: string = "";嵌入单个文件为字节：
typescript
/** @go:embed "data.bin" */
const data: slice<byte> = zero<slice<byte>>();关键规则：
- 变量类型决定嵌入模式：
embed.FS用于目录树，string用于文本，slice<byte>用于二进制。 - 嵌入路径相对于源文件所在目录。
- 使用
embed.FS时需要从 Go 标准库导入embed。
@go:noinline / @go:nosplit / @go:noescape
编译器提示，直接放在函数声明上方：
typescript
/** @go:noinline */
function hotPath(x: int): int {
return x * 2;
}@go:passthrough
透传 Targo 原生不理解的原始 Go 注释或指令：
typescript
/** @go:passthrough "//go:linkname localFunc runtime.someFunc" */规则
- 使用 JSDoc 注释直接放在其影响的声明上方。
- 保持指令字符串为合法的 Go 格式；Targo 会将它们透传到生成的 Go 代码中。
- 不要使用
@directive(...)这类占位语法。