# mpy编译器-MicroPython优化工具

**Repository Path**: tmrnic/mpy_compiler

## Basic Information

- **Project Name**: mpy编译器-MicroPython优化工具
- **Description**: mpy编译器-MicroPython优化工具，专为MicroPython设计，提升代码性能与运行效率，适用于嵌入式开发和物联网项目。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-03-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<text_never_used_51bce0c785ca2f68081bfa7d91973934>
# MicroPython MPY 编译器 GUI 版

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
[![Version](https://img.shields.io/badge/version-1.0.0-green.svg)]()

一个功能完整、界面友好的 MicroPython MPY 文件编译工具，支持批量编译 Python 文件为 MicroPython 字节码格式，极大提高 MicroPython 项目的部署效率和代码安全性。

## ✨ 功能特性

### 🎯 核心功能
- **一键批量编译**：支持批量编译整个项目目录下的 Python 文件
- **智能文件扫描**：自动识别项目中的 Python 文件，支持忽略特定目录和文件
- **灵活的编译选项**：可配置优化级别、qstr缓存、GC收集等多种编译参数
- **目录结构保持**：编译后保持原项目的目录结构，方便直接部署
- **多平台支持**：完美兼容 Windows、Linux 和 macOS 系统
- **自动查找编译器**：自动检测系统中已安装的 mpy-cross 编译器

### 🖥️ 界面特性
- **直观的图形界面**：基于 Tkinter 的原生 GUI，无需额外依赖
- **实时进度显示**：编译进度条和实时状态显示，掌握编译过程
- **彩色日志输出**：不同级别日志使用不同颜色显示，便于排查问题
- **最近项目记录**：自动保存最近打开的项目，快速切换
- **文件选择交互**：支持全选、反选、单独选择需要编译的文件
- **一键打开输出目录**：编译完成后直接打开输出目录查看结果

### 🔧 高级功能
- **配置持久化**：自动保存用户配置，下次启动自动恢复
- **多线程编译**：后台线程执行编译任务，界面不会卡顿
- **编译结果统计**：详细显示成功/失败文件数量和编译详情
- **错误信息展示**：编译失败时显示详细的错误信息，方便调试
- **跨版本兼容**：支持不同版本的 mpy-cross 编译器

## 📋 系统要求

### 运行环境
- **Python 版本**: 3.6 或更高版本
- **操作系统**: Windows 7/8/10/11, Linux, macOS
- **依赖工具**: mpy-cross 编译器（MicroPython 官方提供）

### 硬件要求
- 内存: 最低 256MB，推荐 512MB 以上
- 硬盘: 至少 100MB 可用空间
- 显示器: 分辨率 1024x768 或更高

## 🚀 快速开始

### 方式一：直接运行（推荐普通用户）
1. **下载程序**
   - 从 Releases 页面下载最新的 exe 可执行文件（Windows 用户）
   - 或克隆本仓库到本地
   ```bash
   git clone https://github.com/yourusername/mpy-compiler-tkinter.git
   cd mpy-compiler-tkinter
   ```

2. **安装 mpy-cross 编译器**
   - 访问 [MicroPython 官方下载页面](https://micropython.org/download/)
   - 下载对应平台的 mpy-cross 编译器
   - 将 mpy-cross 可执行文件放置在系统 PATH 中，或放在本程序目录下
   - 验证安装：
     ```bash
     mpy-cross --version
     ```
     应该显示类似 `mpy-cross 1.20.0` 的版本信息

3. **运行程序**
   - Windows 用户直接双击 `mpy_compiler.exe`
   - 或运行 Python 脚本：
     ```bash
     python mpy_compiler.py
     ```

### 方式二：从源代码运行
1. **克隆仓库**
   ```bash
   git clone https://github.com/yourusername/mpy-compiler-tkinter.git
   cd mpy-compiler-tkinter
   ```

2. **安装 Python 依赖**
   ```bash
   # 基础运行无需额外依赖，直接运行即可
   # 如果需要完整功能，安装可选依赖：
   pip install -r requirements.txt
   ```

3. **安装 mpy-cross**
   参考上述步骤安装 mpy-cross 编译器

4. **运行程序**
   ```bash
   python mpy_compiler.py
   ```

## 📖 使用教程

### 基础使用流程

#### 1. 选择项目目录
- 点击"选择项目文件夹"按钮
- 选择包含 Python 文件的项目根目录
- 程序会自动扫描目录下所有的 Python 文件

#### 2. 选择要编译的文件
- 在文件列表中勾选需要编译的文件
- 可使用"全选"或"取消全选"按钮快速操作
- 点击"刷新文件列表"按钮重新扫描项目文件

#### 3. 配置编译选项
- **优化级别**: 选择 0-3 级优化（推荐使用 3 级获得最小的文件体积）
  - 0: 不优化，保留调试信息
  - 1: 基础优化
  - 2: 高级优化
  - 3: 最高优化，移除断言和调试信息
- **递归扫描子目录**: 勾选后会扫描所有子目录中的 Python 文件
- **保持目录结构**: 勾选后编译输出保持原有的目录结构
- **输出目录**: 设置编译后的 mpy 文件输出位置
- **启用 qstr 缓存**: 勾选后启用 qstr 缓存，提高编译速度（推荐开启）

#### 4. 开始编译
- 点击"开始编译"按钮
- 观察进度条和日志输出，了解编译进度
- 编译过程中可随时点击"中止编译"按钮取消编译

#### 5. 查看结果
- 编译完成后会弹出提示框显示编译结果
- 点击"打开输出目录"按钮查看生成的 mpy 文件
- 在日志区域可以查看每个文件的编译详情和错误信息

### 高级使用技巧

#### 自定义忽略文件
编辑 `config.json` 文件中的 `ignore_patterns` 数组，添加需要忽略的文件或目录模式：
```json
{
  "ignore_patterns": [
    "__pycache__/*",
    ".git/*",
    "tests/*",
    "examples/*",
    "my_custom_ignore/*"
  ]
}
```

支持的模式语法：
- `*` 匹配任意字符
- `?` 匹配单个字符
- `[seq]` 匹配 seq 中的任意字符
- `[!seq]` 匹配不在 seq 中的任意字符

#### 命令行使用（无GUI模式）
你也可以直接使用核心编译模块进行命令行编译：

```python
from compiler_core import MpyCompiler

# 初始化编译器
compiler = MpyCompiler()

# 编译单个文件
result = compiler.compile_file("input.py", "output.mpy", options={'optimize': 3})
if result['success']:
    print("编译成功！")
else:
    print(f"编译失败：{result['message']}")

# 编译整个目录
result = compiler.compile_directory("src_dir", "output_dir", recursive=True)
print(f"编译结果：{result['success_count']} 成功，{result['fail_count']} 失败")
```

#### 最近项目功能
程序会自动记录最近打开的10个项目，点击"最近项目"下拉框即可快速切换到之前的项目，无需每次都浏览文件夹。

## 📁 项目结构

```
mpy_compiler_tkinter/
├── mpy_compiler.py          # 主程序入口，GUI 界面实现
├── compiler_core.py         # 编译核心模块，独立于 GUI
├── project_scanner.py       # 项目文件扫描器
├── config.json              # 配置文件，自动生成和保存
├── requirements.txt         # Python 依赖声明
├── README.md                # 项目说明文档
└── icon.ico                 # 程序图标（可选）
```

### 模块说明

#### mpy_compiler.py
- 实现 Tkinter 图形用户界面
- 处理用户交互和界面更新
- 管理编译任务和线程
- 处理配置的加载和保存

#### compiler_core.py
- 独立的编译核心实现
- 提供 mpy-cross 编译器查找和验证功能
- 实现单个文件和批量编译功能
- 提供命令行编程接口

#### project_scanner.py
- 项目文件扫描和过滤功能
- 支持忽略模式配置
- 提供文件信息收集和管理
- 支持 MD5 哈希计算（可选）

## ⚙️ 配置说明

配置文件 `config.json` 会在程序第一次运行时自动生成，包含以下配置项：

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| last_project | string | "" | 最后打开的项目路径 |
| output_dir | string | "./mpy_output" | 默认输出目录 |
| optimize_level | int | 3 | 默认优化级别（0-3） |
| recursive_scan | bool | true | 是否默认递归扫描子目录 |
| keep_structure | bool | true | 是否保持目录结构 |
| auto_select_all | bool | true | 是否默认全选所有文件 |
| recent_projects | array | [] | 最近项目列表（最多10个） |
| window_geometry | object | {"width": 1200, "height": 800} | 窗口大小和位置 |
| compiler_options | object | {} | 编译器默认选项 |
| ignore_patterns | array | [] | 忽略的文件/目录模式 |
| ui_settings | object | {} | 界面相关设置 |

## 🛠️ 开发指南

### 环境搭建
1. 安装 Python 3.6+
2. 克隆仓库到本地
3. 安装开发依赖：
   ```bash
   pip install -r requirements.txt
   ```

### 代码结构说明
- 界面代码和核心业务逻辑完全分离
- compiler_core.py 可以独立使用，不依赖 GUI
- 所有模块都有详细的注释和类型提示
- 遵循 Python PEP8 编码规范

### 扩展功能开发
1. 添加新的编译选项：
   - 在 compiler_core.py 的 default_options 中添加新选项
   - 在 GUI 中添加对应的控件
   - 在 build_command 方法中添加对应的命令行参数

2. 添加新的界面功能：
   - 在 MpyCompilerGUI 类中添加新的方法
   - 在 init_ui 方法中创建对应的 UI 控件
   - 绑定事件处理函数

### 打包为可执行文件
使用 PyInstaller 打包为单个 exe 文件：

```bash
pyinstaller --onefile --windowed --icon=icon.ico --name=mpy_compiler mpy_compiler.py
```

打包参数说明：
- `--onefile`: 打包为单个 exe 文件
- `--windowed`: 不显示控制台窗口（GUI 程序使用）
- `--icon=icon.ico`: 设置程序图标
- `--name=mpy_compiler`: 设置输出文件名

打包完成后，可执行文件会生成在 `dist` 目录下。

## ❓ 常见问题

### Q: 程序提示"未找到mpy-cross编译器"怎么办？
A: 请按照以下步骤检查：
1. 确认已经下载了对应平台的 mpy-cross 编译器
2. 将 mpy-cross 可执行文件放在程序目录下，或者添加到系统 PATH 中
3. 重启程序，程序会自动重新查找

### Q: 编译时提示"语法错误"是什么原因？
A: 可能的原因：
1. Python 代码中使用了 MicroPython 不支持的语法特性
2. 代码中包含语法错误
3. mpy-cross 版本过旧，不支持新的 Python 语法
4. 检查错误信息中的具体行号，修改对应代码

### Q: 编译后的 mpy 文件比原 py 文件还大？
A: 这是正常现象，因为：
1. mpy 文件包含了字节码和附加信息
2. 可以尝试提高优化级别（使用 -O3）
3. 对于非常小的 Python 文件，编译后可能会更大
4. 对于较大的项目，整体体积会有明显减小

### Q: 编译后的 mpy 文件无法运行？
A: 可能的原因：
1. mpy-cross 的版本和目标设备上的 MicroPython 版本不匹配
2. 编译时使用了不兼容的编译选项
3. 目标设备的架构与 mpy-cross 编译目标不匹配
4. 尝试降低优化级别重新编译

### Q: Linux 下运行程序提示没有 tkinter 模块？
A: 请安装 tkinter 包：
- Ubuntu/Debian: `sudo apt-get install python3-tk`
- CentOS/RHEL: `sudo yum install python3-tkinter`
- Fedora: `sudo dnf install python3-tkinter`

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目！

### 贡献步骤
1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

### 代码规范
- 遵循 PEP8 编码规范
- 为新功能添加注释和文档
- 确保代码兼容 Python 3.6+
- 添加必要的错误处理

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

- [MicroPython](https://micropython.org/) - 优秀的 Python 嵌入式实现
- [mpy-cross](https://github.com/micropython/micropython/tree/master/mpy-cross) - 官方字节码编译器
- Tkinter - Python 标准 GUI 库

## 📞 联系方式

如有问题或建议，欢迎通过以下方式联系：
- 提交 GitHub Issue
- 发送邮件：yangxk@mail.nwpu.edu.cn

---

**享受高效的 MicroPython 开发体验！** 🎉
</text_never_used_51bce0c785ca2f68081bfa7d91973934>