# xtool-demo-build

**Repository Path**: jinpeng0804/xtool-demo-build

## Basic Information

- **Project Name**: xtool-demo-build
- **Description**: arkui-x-demo-build
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ArkUI-X 开发环境

本项目用于 ArkUI-X 跨平台应用开发的构建和管理，提供了一套完整的工具链来简化开发流程。

## 目录结构

```
demo-arkui-x/
├── arkui-x-sdk/          # ArkUI-X SDK 目录
│   ├── 20/              # API Level 20 SDK
│   └── 22/              # API Level 22 SDK
├── jdk/                 # JDK 目录（JDK 17.0.17+10）
├── command-line-tools/   # ArkUI-X 命令行工具
│   ├── bin/             # 工具可执行文件
│   ├── hvigor/          # Hvigor 构建工具
│   ├── ohpm/            # OpenHarmony 包管理器
│   ├── hstack/          # HStack 工具
│   ├── sdk/             # SDK 工具
│   ├── codelinter/      # 代码检查工具
│   └── tool/            # 内部工具
├── projects/            # ArkUI-X 项目目录（开发者自行放置）
│   ├── fangdouyin/      # 示例项目 1
│   └── EnjoyArkUIX/     # 示例项目 2
├── output/              # 构建产物输出目录（APK 等）
├── tool/                # 构建和管理工具脚本
│   ├── build_app.py     # 应用构建脚本
│   ├── clean_app.py     # 项目清理脚本
│   ├── replace.py       # SDK 替换工具
│   ├── env.py           # 环境设置脚本
│   └── unzip.exe        # 解压工具（Windows）
└── start.py             # 工具统一入口脚本
```

## 目录说明

### `arkui-x-sdk/`
ArkUI-X SDK 存放目录，包含不同 API Level 的 SDK 版本。

**注意事项**：
- 由 `tool/replace.py` 工具自动管理
- 请勿手动修改此目录内容
- SDK 版本通过 zip 包更新

### `jdk/`
JDK 17.0.17+10 存放目录，用于 ArkUI-X 开发。
JDK下载：https://repo.huaweicloud.com/java/jdk/

**注意事项**：
- 已包含必要的 JDK 环境
- `bin` 和 `jdk_home` 符号链接指向对应目录

### `command-line-tools/`
ArkUI-X 官方命令行工具集合。
下载地址：https://developer.huawei.com/consumer/cn/download/

**注意事项**：
- 包含 Hvigor 构建工具
- 包含 OHPM 包管理器
- 包含代码检查和格式化工具
- 修改后可能影响构建功能

### `projects/`
**开发者项目存放目录**，所有 ArkUI-X 项目应放置于此目录下。

**使用方法**：
1. 将您的 ArkUI-X 项目复制或克隆到 `projects/` 目录
2. 项目应直接作为 `projects/` 的一级子目录
3. 例如：`projects/MyProject/`

**示例**：
```
projects/
├── MyProject/           # 您的项目 1
│   ├── entry/
│   ├── oh-package.json5
│   └── build-profile.json5
└── AnotherProject/      # 您的项目 2
    ├── entry/
    └── ...
```

### `output/`
构建产物输出目录，编译生成的 APK 文件会自动复制到此目录。

**注意事项**：
- 由构建工具自动管理
- 可手动删除清理空间

### `tool/`
构建和管理工具脚本目录，详见下文 [工具说明](#工具说明)。

### `start.py`
工具统一入口脚本，提供便捷的交互式和命令行两种使用方式。

## start.py 使用方法

### 交互式模式（推荐）

直接运行脚本，通过菜单选择功能：

```bash
python start.py
```

菜单选项：
1. **构建应用 (build_app)** - 构建项目、复制 APK、自动安装
2. **清理项目 (clean_app)** - 清理构建产物
3. **替换 SDK (replace)** - 更新 ArkUI-X SDK 版本
0. 退出

### 命令行模式

直接指定操作和参数：

```bash
# 构建项目
python start.py build projects/MyProject

# Release 模式构建
python start.py build projects/MyProject --mode=release

# 清理项目
python start.py clean projects/MyProject

# 清理 Release 产物
python start.py clean projects/MyProject --mode=release

# 替换 SDK
python start.py replace arkui-x-darwin-arm64-6.1.0.32-Canary1.zip
```

### 参数说明

| 参数 | 说明 |
|-----|------|
| `action` | 操作类型：`build`、`clean`、`replace` |
| `target` | 目标：项目名称（build/clean）或 zip 文件名（replace） |
| `--mode` | 模式：`debug` 或 `release`（仅用于 build/clean） |
| `--product` | 产品配置（可选） |

## 工具说明

### tool/build_app.py
应用构建脚本，自动完成构建、APK 复制和设备安装。

**功能**：
- 自动设置开发环境变量
- 交互式项目选择或命令行指定
- 自动修复 gradlew 文件行尾符问题
- 自动处理 local.properties 配置
- 智能搜索并复制最新 APK 到 output 目录
- 自动安装到已连接的 Android 设备（排除模拟器）
- 实时显示构建输出

**独立使用**：
```bash
python tool/build_app.py projects/MyProject --mode=debug
```

### tool/clean_app.py
项目清理脚本，清理构建产物释放磁盘空间。

**功能**：
- 自动设置开发环境变量
- 支持指定项目目录
- 支持不同清理模式（debug/release）
- 实时显示清理输出

**独立使用**：
```bash
python tool/clean_app.py projects/MyProject --mode=debug
```

### tool/replace.py
SDK 替换工具，从 zip 包更新 SDK 版本。

**功能**：
- 自动扫描并选择 zip 文件
- 解压 zip 到 arkui-x 目录
- 修改 apiVersion 为 "22"
- 清空并更新 arkui-x-sdk/22 目录
- 自动创建必要的目录结构

**独立使用**：
```bash
python tool/replace.py arkui-x-darwin-arm64-6.1.0.32-Canary1.zip
```

### tool/env.py
开发环境启动脚本，设置必要的环境变量。

**功能**：
- 设置 PATH 环境变量（包含 command-line-tools/bin 和 tool）
- 设置 ARKUIX_SDK_HOME 环境变量
- 自动检测 Android SDK 路径
- 跨平台支持（Windows/macOS/Linux）

## 使用前准备

### 环境要求

1. **Python 环境**：Python 3.x
2. **Android SDK**：已配置 Android SDK
3. **ADB 工具**：Android SDK 平台工具已安装
4. **设备连接**：Android 设备已通过 USB 连接并开启 USB 调试模式

### 设备准备

1. 在手机上开启"开发者选项"
2. 开启"USB 调试"模式
3. 使用 USB 连接手机到电脑
4. 首次连接时在手机上授权电脑调试

### 验证设备连接

```bash
adb devices
```

应显示已连接的设备列表。

## 常见问题

### Q: 构建时提示 "adb 命令不可用"

**A**: 请确保 Android SDK 平台工具已安装并添加到 PATH 环境变量中。

### Q: APK 安装失败

**A**: 请检查：
- 设备是否通过 USB 连接
- 是否已开启 USB 调试模式
- 运行 `adb devices` 检查设备连接状态

### Q: 如何添加新项目？

**A**: 将项目复制到 `projects/` 目录下，例如 `projects/MyProject`。

### Q: SDK 如何更新？

**A**: 将新的 ArkUI-X SDK zip 包放置在项目根目录，然后运行：
```bash
python start.py replace
```

### Q: 如何指定构建模式？

**A**: 使用 `--mode` 参数：
```bash
python start.py build projects/MyProject --mode=release
```

## 注意事项

1. **项目路径**：所有项目必须放在 `projects/` 目录下
2. **设备选择**：构建工具只会安装到真实设备，自动排除模拟器
3. **SDK 管理**：请使用 `replace.py` 工具更新 SDK，不要手动修改 `arkui-x-sdk/` 目录
4. **强制安装**：使用 `adb install -r` 强制覆盖安装现有应用
5. **跨平台**：脚本会自动检测操作系统并使用相应的可执行文件

## 许可证

请参考各工具和 SDK 的相应许可证。