# XIRASM 语言指南

XIRASM 是一种多ISA的汇编器，可直接编写x86/risc-v/spv汇编,并构造二进制文件。

支持裸二进制/自定义二进制格式，支持windows/linux可执行格式。

XIRASM前端语言是类似编译期小语言来代替传统的汇编器那些伪指令,xirasm比宏指令更安全。

支持标准ISA处理器指令与结构化的编译期语言结合在一起：

指令仍然保持汇编代码的可读形式的写法，而值、函数、循环、数据布局和输出格式则使用清晰的高级现代化语言结构来表达,非常Nice.

本指南有点啰嗦,带有部分机翻，但关键点人工审核,不影响阅读和理解。

前端语法部分都是和正常高级语言一样的,但输出/区域/可执行格式需要自己去理解,这些内容在高级语言里是不会面向用户的，

汇编er要理解,这些都是手戳范畴，没有隐藏任何技术细节和黑魔法。

大部分文档是ai编写，噪声过大，人工修复非常耗时，不影响阅读。

本指南按照新用户通常的学习顺序介绍 XIRASM。内容从简单的裸二进制文件开始，逐步讲解编译期语言、标号、二进制布局、输出区域、收尾处理以及可执行文件格式。完整的函数签名和速查表由接口参考提供；PE、COFF 和 ELF 的专题教程见可执行文件格式指南。

另外出现一些Meta术语不要谎，meta是我之前汇编器的语言模块名字,XIRASM借用了它然后重构了，

总之就当成是XIRASM前端语法就是了。

## 指南结构

### 第一部分：语言基础

1. **[认识 XIRASM](language/01-introducing-xirasm.md)**
   - 汇编第一个 x86-64 程序。
   - 理解处理器指令与编译期代码如何配合。
   - 掌握基本源代码规则。
2. **[值与绑定](language/02-values-and-bindings.md)**
   - 声明常量和可变的局部绑定。
   - 使用整数、布尔值、字符串和字节。
   - 理解作用域和赋值。
3. **[表达式](language/03-expressions.md)**
   - 使用算术、比较、逻辑、位运算和字段表达式。
   - 调用函数并组合编译期计算。
4. **[流程控制](language/04-control-flow.md)**
   - 使用 `if` 选择需要生成的内容。
   - 使用 `while` 和 `for` 重复执行操作。
   - 根据编译期条件生成数据和指令。
5. **[函数与作用域](language/05-functions-and-scope.md)**
   - 编写不返回值的过程和返回值的函数。
   - 使用参数、返回类型、局部绑定和嵌套作用域。
6. **[集合与文本](language/06-collections-and-text.md)**
   - 创建和处理列表、映射、字符串及字节序列。
   - 使用集合描述表格和需要生成的输出内容。
7. **[词法单元与模式匹配](language/07-tokens-and-pattern-matching.md)**
   - 检查词法单元序列。
   - 匹配源代码模式，并据此构建更高层的源代码处理工具。

### 第二部分：汇编器模型

8. **[目标平台、处理器指令与标号](language/08-targets-isa-text-and-labels.md)**
   - 选择指令集和指令模式。
   - 定义标号，并在指令中使用编译期值。
   - 理解地址引用与回填。
9. **[数据与二进制布局](language/09-data-and-binary-layout.md)**
   - 写出整数、字符串和字节。
   - 预留空间并控制对齐方式。
   - 定义具有精确二进制布局的结构体和联合体。
10. **[模块与文件](language/10-modules-and-files.md)**
    - 通过包含和导入复用源代码。
    - 从普通文件以及 JSON、TOML 格式中读取源数据。
11. **[输出区域与虚拟数据](language/11-output-regions-and-virtual-data.md)**
    - 区分逻辑地址和文件中的实际位置。
    - 构建输出区域、预留一段空间，并使用虚拟数据作为临时工作区。
    - 读取并修改已经生成的字节。
12. **[收尾处理](language/12-finalizers.md)**
    - 等布局稳定后再执行检查和回填。
    - 计算校验和与最终字段值。
    - 理解哪些操作不得改变最终布局。

### 第三部分：构建程序

13. **[裸二进制文件与自定义格式](language/13-flat-and-custom-binaries.md)**
    - 构建紧凑的裸二进制文件和应用专用文件格式。
14. **[可执行文件与目标文件格式](language/14-executable-and-object-formats.md)**
    - 理解格式接口负责完成哪些工作。
    - 无需手工计算文件头，即可构建一个最小可执行文件。
    - 通过可执行文件格式指南继续学习 PE、COFF、ELF、导入、导出、BSS（未初始化数据区）和重定位。
15. **[诊断信息与实用约定](language/15-diagnostics-and-practical-conventions.md)**
    - 报告无效输入，并检查布局是否符合预期。
    - 组织可以复用的汇编项目。
    - 在掌握本指南后继续查阅接口参考和可执行文件格式指南。
