代码速览指南（第一版）

本指南将于其发布时起指导作用，直到下一版发布时将会过时。本指南旨在让开发者在5分钟内快速了解项目架构以及阅读顺序。

——2024年10月15日

很多人反映源码的后缀名很奇怪。

本项目中，依赖库的源码后缀统一为.h或.hpp格式；主体实现部分中，每一个源码子目录由一个.hpp文件来统领其他的.cpp文件（要求开发者只需包含此.hpp文件即可调用该子目录下的所有代码）。

.hpp和.cpp都可以用于代码的定义和实现，两个后缀名在本项目当中仅用来区分哪个文件统领了源码目录。

以上仅适用一般情况，并非强制要求。

由于本项目并未采用“定义与实现分离开来，后期统一链接”的形式，因此源码包含的结构有点奇怪。

我们不建议开发者将此项目中的#include看作C/C++中的包含，而是看作import（类似java，py的设计）。

因为本项目的编译指令只有一条，不存在链接，因此我们不建议两个文件之间相互包含（请尽量编写不循环引用的代码）。

我们承认我们并没有在编写“纯正的现代C++代码”。

尽管这个项目是用C++编写的，但是其掺杂了很多java的元素。

例如把所有的成员都写在类里、一个大类编写在一个文件里、代码格式化风格以及上述所说的代码引用方法。请阅读源码时不要见怪。

我们来介绍与源码有关的目录：

该目录用于存放依赖库文件，此目录又有多个子目录。其中template子目录用于存放依赖库模板，其余子目录是依赖库的不同平台实现。

该目录存储主体实现部分的代码，与依赖库实现分割开来，以此实现更强的可移植性。该目录下存放有若干子目录和项目主要文件（例如程序的入口源码）。

该目录存储抽象语法树（AST）的数据结构，主要用于语法分析。

该目录存储stamon数据类型的数据结构。

该目录存储Stamon的标准库源码。

该目录存储编译器的实现。

该目录存储Stamon的中间代码数据结构，中间代码生成器以及解析器。

该目录存储Stamon调用虚拟机外部库的实现。

该目录存储虚拟机的实现。

我们建议开发者先从基础出发，一步步看到主函数的实现。

因此一个合理的源码阅读流程是（以目录为单位）：