bitcraze/toolbelt

Toolbelt

Toolbelt 是一个用于运行软件模块测试和构建工具的实用程序。这些工具在Docker化环境中运行，其中已安装工具链和框架，因此无需在本地系统上安装编译器等依赖。

前提条件

Toolbelt 需要 Docker 1.12 或更高版本。有关更多信息和安装说明，请参见 [***]

Toolbelt 可在 Linux、OSX 和 Windows 上运行。

Windows

由于 Toolbelt 在启动时使用 bash 别名，因此需要类 bash 环境。在 Windows 上最简单的方法是使用 Docker Toolbox（而非 Docker for Windows）。

Toolbelt 要求构建脚本的行尾为“Unix 风格”（仅 LF，而非 Windows 风格的 CRLF）。

• Windows 上的 Git 在克隆项目时会将文本文件的行尾转换为 CRLF。要永久关闭此功能，请运行 git config --global core.autocrlf input
• 应使用支持 Unix 行尾的编辑器，避免编辑器以 Windows 风格保存文件。例如 Notepad++、Atom 或 IntelliJ 都可以做到这一点。

安装

唯一需要的安装步骤是将别名添加到您的 .profile 或 .bashrc 文件中。有关详细说明，请运行

bash
docker run --rm -it bitcraze/toolbelt

Windows

如果使用 Docker Toolbox，可以将此别名添加到 /c/Users/MyUser/.bashrc。Docker Quickstart Terminal 启动时会加载此文件，tb 别名将在 Docker Quickstart Terminal 中可用。Toolbelt 在其他命令窗口或终端中不可用。

使用

假设已按照安装说明设置了别名“tb”。

bash
tb [command]

要获取命令列表，请使用

bash
tb help

要在模块中执行工具，Toolbelt 应始终从模块的根目录执行。

升级

需要不时升级以获取 Toolbelt 和构建器的最新版本。升级只需执行 docker pull，Toolbelt 可以帮您完成：

bash
tb update

工作原理

Toolbelt 旨在简化 Bitcraze 项目的修改、测试和构建。目标是消除在本地计算机上安装工具链、语言和框架的需求。

它几乎不需要安装，只需一个别名。

Toolbelt 是一个内置于 Docker 镜像中的 Python3 程序。调用 Toolbelt 时，会启动一个 Docker 容器（基于该镜像）并执行相应的命令（工具）。当前目录作为卷传递给 Toolbelt，以允许工具读取或修改文件。

模块

模块是在根目录中包含 module.json 文件的文件树，通常对应一个项目（例如本仓库）。module.json 文件描述模块的属性，Toolbelt 读取该文件以了解要执行的操作。

模块工具

Toolbelt 可以在任何位置执行，但如果在模块的根目录中运行，该模块特定的工具将在 Toolbelt 中可用。工具是位于 tools 目录中一个或多个子目录中的可执行文件。所有可用工具在输入以下命令时会显示：

bash
tb help

模块工具可以像其他工具一样调用：

bash
tb <工具名称>

工具目录

在 tools 目录中，一个或多个子目录可能包含工具。最常见的位置是 tools/build，按照惯例，应有一个名为 build 的工具用于构建源代码。module.json 文件包含配置，告诉 Toolbelt 哪些目录包含工具。

如果需要，tools 目录中可以有多个包含工具的目录，但并非 tools 文件夹中的所有目录都必须包含工具。

注意：由于工具通过名称（而非完整路径）标识，因此不同目录中不得有同名工具。

环境

当要执行模块工具时，它必须在具有适当环境（即工具使用的语言、编译器或框架）的 Docker 容器中运行。module.json 的 environmentReqs 成员描述 tools 目录中特定目录的工具所需的环境。

Toolbelt 检查 module.json 文件中的 "environmentReqs" 参数，并将其与 config.json 文件中可用的环境匹配，为工具选择合适的环境。执行工具时，Toolbelt 启动第二个 Docker 容器，并在该容器中运行工具。

例如，在此项目上调用

bash
tb flake8

时，tools/build/flake8 脚本会在具有 python3（和 flake8）的构建器容器中执行。

位于同一目录中的所有工具共享相同的环境要求，并且它们可以相互调用。如果其他目录中的工具具有不同环境，则工具不应调用这些目录中的工具，因为它们都将在同一容器中运行。

显示 Docker 命令

有时查看 Toolbelt 用于运行工具的确切 Docker 命令很有用（例如调试工具时）。只需使用 -d 标志运行 Toolbelt，例如：

bash
tb -d flake8

扩展 Toolbelt

如果需要，可以使用自己的工具扩展 Toolbelt。创建基于 bitcraze/toolbelt 的新 Docker 镜像，将您的工具复制到镜像中的 toolbelt/belt/ 目录，并替换 toolbelt/util/extensions.py 文件，在其中注册您的工具。