# compiler

**Repository Path**: jimonik/compiler

## Basic Information

- **Project Name**: compiler
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 编译流水线

本地 Web 工具：管理多个 Git 仓库、配置编译环境、执行自定义编译命令、浏览并下载产物。

默认在浏览器打开 `http://127.0.0.1:8765` 使用。

## 环境要求

| 依赖 | 说明 |
|------|------|
| Python | 3.10+ |
| Git | 用于克隆、拉取、切换分支 |
| 编译工具链 | 按项目需要自行安装（Flutter、JDK、Android SDK、Gradle 等） |

服务进程会继承当前 shell 的系统环境变量；页面里「已启用的环境」会额外注入到编译命令执行环境中。

## 安装

```bash
cd /path/to/compiler
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## 启动

```bash
python3 main.py
```

启动后会自动释放占用端口（默认 `8765`），并打印本机与局域网访问地址。

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `COMPILER_HOST` | `0.0.0.0` | 监听地址；仅本机访问可设为 `127.0.0.1` |
| `COMPILER_PORT` | `8765` | 监听端口 |

示例：

```bash
COMPILER_HOST=127.0.0.1 COMPILER_PORT=9000 python3 main.py
```

## 快速上手

1. 点击左侧 **+ 新建**，填写仓库名称和 Git 地址。
2. 在「仓库配置」中点击 **获取分支**，选择目标分支后 **保存**。
3. 点击 **克隆**，将代码拉到本地（`data/repos/<仓库ID>/`）。
4. 在「环境配置」中从 **已知环境** 启用编译所需变量（如 `FLUTTER_BIN`、`JAVA_HOME`、`ANDROID_HOME`）。
5. 在「编译配置」填写 **工作目录** 和 **编译命令**（每行一条），点击 **保存** 后 **编译**。
6. 在「编译产物」中浏览输出目录，点击文件 **下载**。

## 功能说明

### 仓库管理

- **保存**：写入 Git 地址、分支、账号等配置到 `data/repos.json`。
- **克隆**：首次将远程仓库克隆到本地；若未克隆，点编译时会自动尝试克隆。
- **更新代码**：执行 `git reset --hard && git pull`，**本地未提交修改会丢失**，操作前请确认。
- **删除**：删除仓库配置与本地目录；若正在编译，会先终止编译任务。
- **切换仓库**：切换前会自动保存当前仓库的编译配置、仓库配置和产物浏览路径；各仓库配置相互独立。

左侧列表悬停可点 **×** 快速删除；正在编译的仓库会显示「编译中」状态。

### 环境配置

编译命令通过 `${变量名}` 引用环境，例如：

```text
${FLUTTER_BIN} pub get
${FLUTTER_BIN} build apk --release
```

**已知环境** 会自动扫描本机：

- 系统环境变量（`JAVA_HOME`、`ANDROID_HOME`、`FLUTTER_ROOT` 等）
- `which` 找到的可执行文件（`FLUTTER_BIN`、`GRADLE_BIN` 等）
- 常见 JDK / Android SDK / FVM / Flutter 安装路径

同一目标变量（如 `JAVA_HOME`）若有多个候选，会以分组形式展示，**选一个启用**即可。

**手动添加环境**：可加入自定义路径，并可用测试命令验证（如 `${DART_BIN} --version`）。

**已启用的环境** 按仓库单独保存；切换仓库后各自保留，不会互相覆盖。

> 编译前会校验：命令里出现的 `${变量}` 必须已在「已启用的环境」中配置，否则会提示缺失变量。

### 编译

- **工作目录**：相对于克隆后的仓库根目录，`.` 表示根目录。
- **编译命令**：按顺序逐条在 shell 中执行；stdout/stderr 实时输出到「编译日志」。
- **后台编译**：切换到其他仓库不会中断当前编译；后台任务会继续运行，列表仍显示「编译中」，切回该仓库可继续看日志。
- **清空**：仅清空页面上的日志显示，不影响服务端记录。

### 编译产物

- 浏览克隆目录（自动排除 `.git`），每 3 秒刷新。
- 点击文件夹进入，点击 **下载** 获取单个文件。
- 当前浏览路径会随仓库一起保存，下次进入自动恢复。

## 配置示例

### Flutter 项目

工作目录：`.`

```text
${FLUTTER_BIN} pub get
${FLUTTER_BIN} build apk --release
```

启用环境：`FLUTTER_BIN`（或从 FVM 候选中选择对应 SDK）

产物常见路径：`build/app/outputs/flutter-apk/`

### Android / Gradle 项目

工作目录：`.` 或子模块目录

```text
chmod +x gradlew
./gradlew assembleRelease
```

启用环境：`JAVA_HOME`、`ANDROID_HOME`

产物常见路径：`app/build/outputs/apk/release/`

## 数据目录

| 路径 | 内容 |
|------|------|
| `data/repos.json` | 各仓库配置（Git 信息、编译命令、已启用环境、产物路径等） |
| `data/env_library.json` | 全局「手动添加」的已知环境 |
| `data/repos/<ID>/` | 克隆下来的 Git 工作区 |

删除仓库会同时移除对应配置项与 `data/repos/<ID>/` 目录。

## 常见问题

**获取分支失败**

- 检查 Git 地址是否正确。
- 私有仓库需填写用户名和密码/Token。
- 确认本机可访问该 Git 远程（网络、VPN、SSH/HTTPS 权限）。

**编译提示「未启用的环境变量」**

- 在「已知环境」中找到对应项并 **启用**，或手动添加后启用。
- 变量名须为大写字母、数字、下划线，且以字母开头。

**编译命令找不到工具**

- 确认已在「已启用的环境」中配置了正确路径。
- 服务启动时的 shell 环境也会影响 `which` 检测结果；必要时用手动添加补全路径。

**局域网其他设备无法访问**

- 确认 `COMPILER_HOST=0.0.0.0`（默认）。
- 检查防火墙是否放行 `COMPILER_PORT`。
- 编译在本机执行，远程浏览器仅操作界面，实际仍使用**运行服务的那台机器**上的工具链。

## 项目结构

```text
compiler/
├── main.py              # 入口，启动 uvicorn
├── requirements.txt
├── app/
│   ├── main.py          # FastAPI 路由与 WebSocket
│   ├── build_runner.py  # 编译任务执行
│   ├── git_manager.py   # Git 克隆/拉取/分支
│   ├── env_detector.py  # 本机环境自动检测
│   ├── env_service.py   # 环境面板数据
│   ├── storage.py       # 仓库配置持久化
│   └── ...
├── static/              # Web 前端
└── data/                # 运行时数据（配置与克隆目录）
```