Automachina

洛班抽象计算机

内容

• 安装
  • Cargo
  • Git
• 用法
  • 添加crate
  • 更新crate
  • 使用crate
• 文档
  • 使用文档
  • 编辑文档
• 示例
• 支持
• 贡献
  • 拉取请求
  • 拉取请求指南
  • API指南
  • 代码风格指南
  • 贡献方式
    • 请求
      • 评论
      • 功能
    • 报告错误
    • 编辑代码
      • 修复错误
      • 添加功能
      • 移除功能
      • 重构
    • 编辑文档
    • 社区支持
    • 捐赠
  • 行为准则
• 致谢
• 许可证

安装

• Cargo
• Git

Cargo

安装库的推荐方法是使用Cargo，Rust的包管理器。要使用Cargo安装库，请按照以下步骤操作

1. 在您的系统上打开终端或命令行界面。

2. 导航到您的项目目录。

       cd <project-directory>
   

3. 使用Cargo安装。

       cargo install automachina
   

4. 等待Cargo下载和构建库。这可能需要一些时间，具体取决于服务器负载和您的网络连接速度。

5. 一旦Cargo完成库的构建，您就应该能在您的项目中使用它了。

Git

如果您更喜欢从源代码安装库，您可以通过克隆库的Git仓库并手动构建来做到这一点。要从源代码安装库，请按照以下步骤操作

1. 在您的系统上打开终端或命令行界面。

2. 导航到您想克隆仓库的目录。

       cd <directory>
   

3. 克隆库的Git仓库。

       git clone https://github.com/karansinghlobana/automachina.git
   

4. 等待GitHub下载库。这可能需要一些时间，具体取决于服务器负载和您的网络连接速度。

5. 导航到包含库源代码的目录。

           cd automachina
   

6. 使用Cargo构建库。

           cargo build
   

7. 等待Cargo下载依赖项并构建库。这可能需要一些时间，具体取决于服务器负载、您的网络连接速度以及您的系统计算能力。

8. 一旦Cargo完成库的构建，您就应该能在您的项目中使用它了。

用法

• 添加crate
• 更新crate
• 使用crate

添加crate

在您可以在项目中使用库之前，您需要导入它。为此，请将以下行添加到项目中的Cargo.toml文件。

    [dependencies]
    automachina = "0.1.0"

您可以在库的仓库页面上找到库的最新版本。

更新crate

在您的Cargo.toml文件中添加库之后，运行以下命令以下载和安装库。

    cargo update

使用crate

一旦将库导入到您的项目中，您就可以在代码中使用它。以下是如何使用库功能的示例。

use automachina::Computer;
use automachina::architectures::Architecture;
use automachina::machines::Machine;
use automachina::programs::Program;

fn main() {

    let architecture = Architecture::new();
    let machine = Machine::new(architecture);
    let computer = Computer::new(machine);

    let program = Program::new();
    computer.execute(program);

}

文档

此项目的文档以多种格式提供。这些格式包括

• README.md：这是本项目的首要文档来源。它提供了项目的概述、安装说明、使用说明、贡献指南以及其他相关信息。建议您从这里开始。
• 代码文档：代码使用了大量的内联注释进行详细文档。此文档提供了对项目实现细节的深入解释。要生成此文档，您可以使用Rustdoc等工具。
• Wiki：项目还有一个Wiki，提供了有关项目的详细信息，包括架构、设计决策和实现细节。您可以通过访问项目的GitHub页面来访问Wiki。

使用文档

为了有效地使用文档，建议您从README.md文件开始。此文件提供了项目的简要概述、安装说明和使用说明。

如果您需要更多详细的信息，可以参考代码文档。代码文档提供了对项目实现细节的深入解释。

如果您需要有关架构、设计决策或实现细节的信息，可以参考Wiki。

编辑文档

如果您发现文档有任何问题或想为文档做出贡献，可以通过以下方式操作

• 提出问题：如果您发现文档有任何问题，可以在项目的GitHub页面上提出问题。这将提醒项目维护者，他们可以随后解决问题。
• 提交拉取请求：如果您想为文档做出贡献，可以提交包含您想进行的更改的拉取请求。项目维护者将审查您的更改，并在它们符合项目标准的情况下合并它们。

需要注意的是，文档与代码本身一样重要，对文档的任何贡献都将受到高度赞赏。

示例

架构

use automachina::architectures::Architecture;
use automachina::architectures::registers::Register;
use automachina::architectures::stacks::Stack;
use automachina::architectures::instructions::Instruction;
use automachina::architectures::labels::Label;
use automachina::architectures::directives::Directive;

机器

use automachina::machines::Machine;

程序

use automachina::programs::Program;

计算机

use automachina::Computer;

支持

如果您在此项目中遇到任何问题或有任何疑问，有几种方法可以寻求支持

1. 查看README.md文件：README.md文件包含有关安装和使用库的信息，以及如何报告错误和为项目做出贡献。
2. 查看文档：文档提供了对库功能和使用的详细概述。它还可能包含故障排除技巧和示例。
3. 在GitHub上提出问题：如果您遇到错误或对库有任何疑问，您可以在项目的GitHub存储库上打开一个问题。请确保提供尽可能多的详细信息，包括重现问题的步骤和相关错误消息。
4. 加入社区：考虑加入在线论坛、邮件列表或聊天室，这些论坛、邮件列表或聊天室专门针对库或其编写的编程语言。这些社区可以成为支持和知识的宝贵来源。
5. 联系贡献者：如果您通过上述方法无法找到解决问题的方案，您可以尝试直接联系项目贡献者。您可以通过[email protected]联系我。

贡献

• 拉取请求
  • 拉取请求指南
  • API指南
  • 代码风格指南
• 贡献方式
  • 请求
    • 评论
    • 功能
  • 报告错误
  • 编辑代码
    • 修复错误
    • 添加功能
    • 移除功能
    • 重构
  • 编辑文档
  • 社区支持
  • 捐赠
• 行为准则

拉取请求

我们欢迎对这个库做出贡献！如果您想做出贡献，请按照以下步骤操作

1. 在GitHub上复制存储库。
2. 将复制的存储库克隆到您的本地机器。
3. 为您的更改创建一个新分支。
4. 进行更改，并在进行过程中提交。
5. 将您的更改推送到您分叉的仓库。
6. 向原始仓库提交拉取请求。

我们将尽快审查您的拉取请求，并在需要时提供反馈。我们感谢您对库的贡献！

拉取请求指南

提交拉取请求时，请确保：

1. 您的代码符合我们的代码风格指南。我们使用Rustfmt来确保代码库中的格式一致性。请在提交拉取请求之前运行cargo fmt来格式化您的更改。
2. 您的更改不会破坏现有功能。在提交更改之前，请确保所有现有测试通过，并考虑为任何新功能编写额外的测试。
3. 您的更改有良好的文档记录，包括对公共API的任何更改。请确保更新任何相关文档，包括README.md、示例和API文档，以反映您的更改。
4. 您为任何新功能添加了测试。我们要求所有新功能都有测试，以确保其按预期工作且不会破坏现有功能。

除了这些指南外，我们要求所有拉取请求都遵守API指南。

API指南

我们努力保持库的API稳定，以便用户可以放心依赖它而不用担心破坏性更改。为此，我们遵循以下公共API指南：

1. 稳定性：当我们有信心API不太可能以破坏性的方式进行更改时，我们会将其标记为稳定。一旦API被标记为稳定，我们将保持未来可预见的向后兼容性。当添加新功能时，我们通常首先将其作为不稳定功能添加到库中，然后只有在有信心其准备好上线时才将其标记为稳定。
2. 向后兼容性：我们尽量避免对稳定API进行破坏性更改。如果需要做出破坏性更改，我们将遵循Rust的语义化版本控制指南，这意味着我们将提升库的主版本号以指示API已以不向后兼容的方式更改。我们还将提供迁移指南，以帮助用户升级到新版本。
3. 文档：我们为所有公共API提供清晰和全面的文档。这包括API参考文档、示例、指南和教程，以帮助用户开始使用库。我们还努力编写易于理解的文档，即使是对于新手Rust或编程用户。
4. 一致性：我们旨在使我们的API保持一致且易于使用。这意味着遵循已建立的Rust约定和惯例，以及避免不必要的复杂性和模板代码。我们还将避免通过公共API暴露实现细节或内部状态。

除了这些指南外，我们要求所有拉取请求都遵守代码风格指南。

代码风格指南

我们认为，干净、可读和一致的代码对于库的长期维护至关重要。为此，我们遵循以下代码风格指南：

1. 格式化：我们使用由rustfmt提供的默认Rust格式化指南。这有助于确保我们的代码格式一致且易于阅读。
2. 命名约定：我们遵循官方Rust文档中概述的Rust命名约定。这包括使用snake_case为变量和函数命名，使用PascalCase为类型和结构命名，以及使用SCREAMING_SNAKE_CASE为常量命名。
3. 注释：我们使用注释来帮助解释代码并使其更易于阅读。我们努力编写清晰、简洁且为代码增加价值的注释。我们还避免对自解释或明显的代码进行注释。
4. 函数大小：我们旨在保持我们的函数小而专注。这有助于提高代码的可读性和可维护性。通常，我们试图将函数大小限制在不超过50行代码。如果一个函数变得过于复杂，我们会考虑将其重构为更小、更专注的函数。
5. 错误处理：我们使用Rust内置的错误处理机制，如Result和Option，来处理错误和意外情况。我们避免抛出异常或使用错误代码，而是使用Rust强大的类型系统来提供清晰简洁的错误消息。我们还旨在提供有帮助的错误消息，以便用户能快速诊断和修复问题。
6. 代码模块化：我们努力保持代码模块化和易于理解。这意味着将我们的代码分解为小型、可重用的组件，并避免大型、单体函数或模块。我们还旨在编写易于测试和维护的代码，以便我们可以在开发早期阶段捕捉到错误和问题。
7. 测试：我们相信编写测试对于确保代码的质量和正确性至关重要。我们使用Rust内置的测试框架为我们的代码编写单元测试。我们旨在编写涵盖所有关键功能、边缘情况和错误场景的测试。我们还努力编写易于理解和维护的测试。

贡献方式

请求

如果您对项目有新的功能或改进建议，或者遇到错误或问题，您可以通过几种不同的方式提出请求。

评论

如果您对项目有任何问题或反馈，您可以请求评论。这可以通过多种方式完成

• 您可以在存储库中打开一个问题并留下描述您的问题或反馈的评论。
• 如果您认为您有一些相关的信息可以添加，您也可以在现有的问题上评论。

在请求评论时，请尽可能详细地提供您的问题或反馈。这将帮助项目维护者理解您的请求并做出适当的回应。

功能

如果您觉得项目中缺少某些内容或可以进行改进，您可以建议新的功能。这可以通过多种方式完成

• 您可以在存储库中打开一个问题并描述您希望看到的特性。
• 如果该特性已经被提出，您可以对该问题进行投票或添加更多信息。
• 如果您对特性的工作方式有清晰的想法，并且愿意参与其中，您可以创建一个实现该特性的pull request。

在请求功能时，请尽可能详细地说明您希望看到的内容。这可以包括用例、示例以及任何其他相关信息。这将帮助项目维护者理解您的建议并评估其可行性。

报告错误

如果您在使用项目时遇到任何错误或问题，我们鼓励您向我们报告。报告错误有助于我们提高项目的质量和对所有用户的可靠性。

要报告错误，您可以在GitHub上项目的存储库中打开一个问题。在打开问题时，请尽可能详细地提供您遇到的错误信息。这应包括

• 发生的事情和您期望发生的事情的描述
• 任何生成的错误消息或日志
• 如果有，重现错误的步骤

如果您有其他可能有助于诊断或修复错误的信息，请一并包括在内。

一旦您报告了一个错误，项目团队的一名成员将审查该问题，并尽快回复。请耐心等待，并理解调查和解决问题可能需要一些时间。

如果您能够提供错误修复，也可以提交带有修复的拉取请求。有关如何向项目贡献代码更改的更多信息，请参阅编辑代码部分。

编辑代码

向项目贡献代码更改是帮助改进其功能并添加新特性的好方法。当向项目贡献代码更改时，请确保您的代码遵循项目的编码标准和任何已建立的API。有关更多信息，请参阅代码风格指南和API指南部分。

在提交拉取请求之前，请确保您已彻底测试您的更改，并且它们不会引入任何新的问题或错误。如果可能，请将自动化测试与您的更改一起包含，以帮助确保它们在未来继续按预期工作。

一旦您提交了拉取请求，项目团队的一名成员将审查更改并提供反馈。请耐心等待，并理解审查和合并您的更改可能需要一些时间。

修复错误

如果您遇到了项目中的错误或问题，并已确定修复方法，您可以通过提交带有修复的拉取请求来解决问题。在提交拉取请求时，请包括您正在修复的错误以及您的修复如何解决该问题的详细描述。

添加功能

如果您有一个想法，认为该功能对项目来说是一个宝贵的补充，您可以通过提交带有新功能的拉取请求来添加它。在提交拉取请求时，请包括功能的详细描述以及它将如何增强项目。

删除功能

如果您认为项目中的某个功能是不必要的或存在问题的，并且您已确定一种在不影响其他功能的情况下删除它的方法，您可以通过提交删除请求来提交它。在提交拉取请求时，请包括您要删除的功能的详细描述以及您为什么认为应该删除它的原因。

重构

如果您认为可以通过重构来改进代码库的一部分，并且您已确定一种不会影响其他功能的方法，您可以通过提交重构请求来提交它。在提交拉取请求时，请包括您正在重构的代码库部分的详细描述以及您的更改如何改进代码。

编辑文档

对提高项目文档的贡献总是受欢迎的。文档是项目的重要方面，有助于用户了解如何使用项目、其功能和限制。

以下是一些贡献文档的方法

• 修复错别字和语法错误：如果您在文档中遇到任何错别字或语法错误，请随时提交带有必要修正的拉取请求。
• 添加新内容：如果您认为文档中缺少某些内容，您可以通过提交拉取请求将其添加到文档中。
• 改进现有内容：如果您觉得现有文档可以改进，您可以通过提交带有必要更改的拉取请求来改进它。
• 翻译文档：如果您精通除英语以外的语言，您可以翻译文档到那种语言，以帮助非英语使用者使用项目。

在进行任何贡献之前，请务必仔细阅读现有文档，以确保您的贡献与现有结构和风格相一致。

社区支持

社区支持是任何开源项目的重要组成部分。您可以通过以下方式支持项目：

• 在论坛上回答问题：如果您对该项目或使用了一段时间，您可以帮助回答其他用户对该项目的问题。这可以在项目的论坛、GitHub问题或其他社区论坛上完成。
• 分享您对该项目的经验：如果您使用该项目有一段时间，您可以在社交媒体、博客文章或其他在线平台上分享您的经验。这有助于传播项目信息并吸引新用户。
• 指导新贡献者：如果您有贡献开源项目的经验，您可以帮助指导新贡献者加入项目。这可能包括帮助他们开始项目，回答他们的问题，并审查他们的贡献。

捐赠

捐款始终受到欢迎，并有助于支持项目的发展和维护。如果您发现该项目很有用，请考虑捐款以支持其发展。您可以通过以下方式捐款：

• 一次性捐款：您可以通过PayPal、Stripe或其他支付处理器一次性向项目捐款。
• 定期捐款：您可以设置定期捐款以支持项目的持续发展和维护。
• 赞助：如果您是公司或组织，您可以通过提供财务支持、资源或其他贡献来赞助项目的发展。

所有捐款都将用于支持项目的发展和维护，例如支付托管费、域名注册和发展工具。

行为准则

贡献者应致力于使项目的分析、规范、设计、开发、测试和维护成为一种有益且受尊重的责任。根据他们对公众健康、安全和福利的承诺，贡献者应遵守以下八项原则

1. 公众：贡献者应始终与公众利益保持一致。
2. 项目：贡献者应以符合公众利益的方式行事，以维护项目的最大利益。
3. 产品：贡献者应确保他们的工作成果和相关修改达到最高的专业标准。
4. 判断：贡献者应在专业判断中保持诚信和独立性。
5. 管理：贡献管理者和管理者应订阅并推广软件开发和维护的道德方法。
6. 职业：贡献者应维护与公众利益一致的职业道德和声誉。
7. 同事：贡献者应公平对待并支持其他贡献者。
8. 自我：贡献者应参与终身学习，以了解他们职业的实践，并推广职业道德。

致谢

我要感谢社区对该项目支持和贡献。

许可证

Automachina：Lobana 抽象计算机版权（C）2023 Karan Singh Lobana

本程序是自由软件：您可以按照自由软件基金会发布的GNU Affero通用公共许可证的条款重新分发和/或修改它，许可证版本为3，或（根据您的选择）许可证的任何后续版本。

本程序是根据希望它将是有用的目的进行分发的，但没有任何保证；甚至没有关于适销性或适用于特定目的的隐含保证。有关详细信息，请参阅GNU Affero通用公共许可证。

您应该已经收到与该程序一起的GNU Affero通用公共许可证副本。如果没有，请参阅https://gnu.ac.cn/licenses/。