Build Tool 是一个用 Bash 编写的模块化构建工具。它提供配置加载、目标注册、依赖解析、插件加载、缓存、日志、平台检测和终端输出等基础能力；当前仓库内置的主要插件是 android，用于在不依赖 Gradle 的情况下完成 Android APK 构建流程。
这个项目适合两类场景：
- 作为一个轻量级 Bash 构建框架，为项目定义自己的构建目标和插件。
- 作为 Android 构建实验工具，直接调用 Android SDK 工具链完成资源编译、Java/Kotlin 编译、DEX、打包、对齐、签名、安装和运行。
仓库当前实际可用的内置插件是：
| 插件 | 说明 | 入口 |
|---|---|---|
android |
不使用 Gradle 的 Android 构建插件 | plugins/android.sh |
部分文档仍保留通用构建框架和 Java 示例的说明，可以作为插件开发参考；但本仓库当前没有内置 java 插件。
- 模块化 Bash 架构：核心能力拆分在
lib/下。 - 插件系统：插件通过
register_target注册构建目标。 - 目标依赖解析：支持目标依赖、循环依赖检测和按顺序执行。
- YAML 配置：通过
build.yaml描述项目、目录、插件、目标和钩子。 - Android 构建链：依赖解析、资源处理、源码编译、DEX、APK 打包、zipalign、签名、安装和运行。
- Maven POM 解析：只解析顶层项目依赖，支持 dependencyManagement 版本补全、scope/optional/type 过滤和 exclusions 传递。
- 缓存模块：基于文件哈希的缓存读写、清理和统计。
- 跨平台辅助：检测系统、架构、包管理器和基础工具。
- 终端输出：彩色输出、分节输出、键值展示和步骤状态。
- 国际化：核心文案和 Android 插件文案支持中英文。
| 要求 | 说明 |
|---|---|
| Bash | 4.0 或更高版本，需要关联数组支持 |
| 基础命令 | cat, mkdir, rm, cp, mv, find, sed, grep |
| YAML 工具 | 支持 Mike Farah yq v4+，也兼容 Python yq 的 yq -r 语法 |
| Java | Android 插件需要 JDK 11+ 和 javac |
| Android SDK | Android 插件需要 Android SDK、Build Tools、Platform Tools 和对应 API platform |
Android SDK 路径通常通过 ANDROID_HOME 或 ANDROID_SDK_ROOT 提供。
./build help
./build version
./build plugin list
./build list./build android:check
./build android:sdk-info
./build android:tools仓库包含一个 Android 示例项目，配置位于 test/build.yaml，源码和资源位于 test/src/main。进入示例项目目录后使用仓库根目录的入口脚本：
cd test
../build android:info
../build android:build当 Android SDK、JDK 和构建工具齐全后，android:build 会依次执行：
依赖解析 -> 资源处理 -> Java/Kotlin 编译 -> DEX -> APK 打包 -> zipalign -> 签名
./build <target> # 执行指定目标
./build list # 列出可用目标
./build clean # 执行 clean 目标或提示可用插件目标
./build check # 检查基础环境
./build config # 显示当前配置
./build help # 显示帮助
./build version # 显示版本./build plugin list # 列出已加载插件
./build plugin create <name> # 创建插件模板
./build plugin validate [name] # 验证插件
./build plugin deps [name] # 查看插件命令依赖
./build plugin install-deps [name] # 安装缺失命令依赖
./build plugin packages [name] # 查看插件系统包
./build plugin install-pkgs [name] # 安装插件系统包./build cache stats
./build cache clear
./build cache enable
./build cache disable
./build cache cleanup./build android:check # 检查 Android 构建环境
./build android:setup # 设置 Android SDK
./build android:deps # 下载并解析 Maven 依赖
./build android:resources # 编译和链接 Android 资源
./build android:compile # 编译 Java/Kotlin 源码
./build android:dex # 转换 class/jar 为 DEX
./build android:package # 打包未签名 APK
./build android:sign # 对齐并签名 APK
./build android:build # 完整构建 APK
./build android:install # 安装 APK 到设备
./build android:run # 启动设备上的应用
./build android:info # 显示 Android 项目信息
./build android:sdk-info # 显示 SDK 信息
./build android:lint # 执行 lint
./build android:lint-fix # 自动修复 lint 问题
./build android:lint-baseline # 创建 lint baseline
./build android:clean # 清理 Android 构建产物-v, --verbose 详细输出
-q, --quiet 静默输出
--no-color 禁用彩色输出
--no-unicode 禁用 Unicode 符号
-c, --config <file> 指定配置文件
-j, --jobs <n> 指定并行任务数
--no-cache 禁用缓存
--log-file <file> 写入日志文件build-tool/
├── build # 主入口脚本
├── build.yaml # 仓库根目录示例配置
├── config/
│ └── default.conf # 默认配置
├── lib/
│ ├── cache.sh # 缓存模块
│ ├── config.sh # 配置管理
│ ├── core.sh # 目标注册、依赖解析和执行引擎
│ ├── i18n.sh # 国际化
│ ├── log.sh # 日志
│ ├── output.sh # 终端输出
│ ├── platform.sh # 平台检测和包管理器封装
│ ├── plugin.sh # 插件发现、加载、钩子和依赖
│ ├── utils.sh # 通用工具函数
│ └── yaml.sh # YAML 读写
├── plugins/
│ ├── android.sh # Android 插件入口
│ └── android/ # Android 插件子模块
│ ├── compile.sh
│ ├── dependencies.sh
│ ├── dex.sh
│ ├── lint.sh
│ ├── package.sh
│ ├── resources.sh
│ ├── sdk.sh
│ ├── signing.sh
│ ├── tools.sh
│ └── xml.sh
├── scripts/ # 项目辅助脚本
├── test/ # Android 示例项目
└── docs/ # 文档
build.yaml 支持项目元信息、源码目录、输出目录、插件、目标和钩子：
project:
name: my-project
version: 1.0.0
description: My project
directories:
source: src
build: build
plugins:
- android
targets:
prepare:
script: scripts/prepare.sh
package:
script: scripts/package.sh
deps:
- prepare
hooks:
pre_build: scripts/hooks/pre_build.sh
post_build: scripts/hooks/post_build.sh自定义目标脚本会在目标执行时被 source，因此脚本中可以直接使用 lib/ 暴露的函数，例如 output_info、ensure_dir、step_start 和 step_end。
Android 项目的配置示例：
project:
name: android-test
version: 1.0.0
description: Android test project
directories:
source: src/main
build: output
plugins:
- android
android:
application:
id: com.example.test
version_name: 1.0.0
version_code: 1
sdk:
compile_sdk: 34
build_tools: 34.0.0
min_sdk: 21
target_sdk: 34
build:
type: debug
minify: false
shrink: false
java:
source: "11"
target: "11"
repositories:
- https://maven.aliyun.com/repository/public
- https://maven.aliyun.com/repository/google
- https://repo1.maven.org/maven2
- https://dl.google.com/dl/android/maven2
dependencies:
implementation:
- androidx.appcompat:appcompat:1.6.1
compile_only: []Android 依赖解析会读取 Maven POM 的 <project><dependencies> 作为传递依赖来源；dependencyManagement 只用于补全缺省版本，不会被当成真实依赖下载。解析时会跳过 test、provided、system、import、optional=true 和 type=pom 的依赖，并向下传递 POM 中声明的 exclusions。
配置项可以通过 BUILD_ 前缀的环境变量覆盖：
export BUILD_VERBOSE=true
export BUILD_JOBS=8
export BUILD_CACHE_DIR=/tmp/build-cache创建插件模板：
./build plugin create my-plugin插件本质是 Bash 脚本。插件加载后可以设置元信息、声明依赖并注册目标：
#!/usr/bin/env bash
PLUGIN_NAME="my-plugin"
PLUGIN_VERSION="1.0.0"
PLUGIN_DESCRIPTION="Custom build plugin"
PLUGIN_DEPENDENCIES=""
PLUGIN_PACKAGES_STR=""
register_target "my-plugin:build" "Build project" "my_plugin_build"
register_target "my-plugin:clean" "Clean build artifacts" "my_plugin_clean"
my_plugin_build() {
step_start "Building"
output_info "Building project"
step_end
return 0
}
my_plugin_clean() {
rm -rf "${BUILD_DIR:-build}"
return 0
}插件可以放在以下位置：
- 仓库内置插件目录：
plugins/ - 项目插件目录：
./plugins - 项目隐藏插件目录：
./.build/plugins - 用户插件目录：
~/.build-tool/plugins
确认 yq 可用，并且至少支持以下任一语法：
yq --version
yq eval '.project.name' build.yaml
yq -r '.project.name' build.yaml如果两种读取方式都不可用，请安装 Mike Farah yq v4+ 或 Python yq。
先确认插件是否已加载：
./build plugin list
./build list如果看不到 android:* 目标，检查运行目录和插件目录。开发本仓库时建议从仓库根目录运行 ./build。
先运行环境检查：
./build android:check常见原因包括：
- 未安装 JDK 11+。
- 未设置
ANDROID_HOME或ANDROID_SDK_ROOT。 - 缺少
platforms;android-<compile_sdk>。 - 缺少
build-tools;<build_tools>。 - 缺少
platform-tools或cmdline-tools。
仓库当前没有包含许可证文件。发布或分发前请补充 LICENSE。