# 包艺工坊

**Repository Path**: deepin20/packcraft

## Basic Information

- **Project Name**: 包艺工坊
- **Description**: 通用图形化打包工具— 让你轻松构建 DEB 软件包，无需手写控制文件或记忆繁琐的 `dpkg` 命令。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 包艺工坊 (PackCraft)

**通用图形化打包工具** — 让你轻松构建 DEB 软件包，无需手写控制文件或记忆繁琐的 `dpkg` 命令。

![PackCraft 界面预览](packcraft/resources/icons/packcraft_256.png)

---

## 简介

PackCraft 是一款面向开发者和打包维护者的图形化工具，旨在简化 Debian 软件包的构建流程。你只需准备一个简单的 JSON 配置文件，指定待安装的文件、依赖关系、版本等信息，点击“开始打包”即可生成标准的 `.deb` 包。工具内置了可视化的配置校验、日志输出、进度反馈和偏好设置，让打包工作变得直观高效。

---

## 功能特性

- 🖥️ **图形化界面**：基于 Tkinter 开发，开箱即用，在 Linux 桌面环境下流畅运行。
- 📦 **JSON 配置驱动**：通过 `package.json`（或 `build_config.json` / `packcraft.json`）定义包名、版本、架构、文件映射、依赖、可执行权限等。
- 🎛️ **交互式字段编辑**：在 UI 中直接修改版本、架构、描述、依赖，无需重复编辑配置文件。
- 📋 **实时构建日志**：彩色日志区域清晰展示打包过程，错误信息一目了然。
- 📊 **进度条反馈**：复制文件时动态显示进度，让你掌握打包节奏。
- 🔧 **自定义 control 文件**：支持使用外部 `control` 文件，灵活定制 DEB 控制信息。
- ⚙️ **偏好设置**：保存默认输出目录、默认架构、自动清理构建目录等个性化配置。
- 🧹 **一键清理**：快速删除 `build/` 临时目录，保持项目整洁。
- 🌐 **跨平台支持**：虽为 Linux 打包工具设计，但可在任何支持 Tkinter 和 dpkg 的 Linux 发行版上运行。

---

## 系统要求

- **Python 3.6+**（推荐 3.8 以上）
- **Tkinter**（通常随 Python 一起安装，部分发行版需单独安装 `python3-tk`）
- **dpkg**（Debian/Ubuntu 及其衍生版：`sudo apt install dpkg`）
- 可选：**Pillow**（用于更佳图标显示，可通过 `pip install Pillow` 安装）

---

## 安装

### 从源码运行（开发模式）

1. 克隆或下载本项目源码到本地。
2. 进入项目根目录：
   ```bash
   cd packcraft
   ```
3. （可选）创建虚拟环境并激活：
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```
4. 安装依赖：
   ```bash
   pip install -r requirements.txt
   ```
   若未安装 Pillow，图标可能无法加载，但不影响核心功能。
5. 启动应用：
   ```bash
   ./run.sh
   ```
   或直接运行：
   ```bash
   python3 -m packcraft.main
   ```

### 作为 Python 包安装

（计划支持 `pip install`，当前可从源码运行。）

---

## 使用说明

### 第一步：准备项目目录

在你的项目目录中，放置好需要打包的文件（如 `usr/bin/myapp`、`etc/myapp/config` 等），并创建一个配置文件（推荐命名为 `package.json`）。

### 第二步：编写配置文件

配置文件为 JSON 格式，基本结构如下：

```json
{
    "package_name": "myapp",
    "version": "1.0.0",
    "architecture": "amd64",
    "description": "My application",
    "depends": ["bash", "coreutils"],
    "files": [
        {"src": "usr/bin/myapp", "dest": "/usr/bin/myapp"}
    ],
    "executables": ["/usr/bin/myapp"],
    "control_fields": {
        "Maintainer": "Your Name <you@example.com>"
    }
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `package_name` | string | ✔ | 包名（应符合 Debian 包名规范） |
| `version` | string | ✔ | 版本号，格式 `x.y.z` |
| `architecture` | string | 否 | 架构，可选 `all`、`amd64`、`arm64`、`i386`，默认 `all` |
| `description` | string | 否 | 简短描述（会被写入 control 文件的 `Description`） |
| `depends` | array | 否 | 依赖列表，如 `["bash", "libc"]` |
| `files` | array | ✔ | 文件映射，每项包含 `src`（相对于项目根目录）和 `dest`（目标安装路径，可包含前导 `/`） |
| `executables` | array | 否 | 需要设置 0755 权限的文件（相对于 `dest` 的路径） |
| `control_fields` | object | 否 | 自定义 control 文件中的字段，会覆盖默认值 |
| `custom_control` | string | 否 | 使用外部 `control` 文件的绝对路径（若指定，则忽略自动生成的 control） |

### 第三步：启动 PackCraft

运行 `./run.sh` 启动图形界面。

### 第四步：加载配置

- 点击“项目目录”的浏览按钮，选择你的项目根目录。
- 程序会自动寻找 `package.json`、`build_config.json` 或 `packcraft.json`。
- 配置加载成功后，界面会显示包名、版本、架构等信息。

### 第五步：调整参数（可选）

你可以直接在界面中修改版本、架构、描述、依赖，这些修改会覆盖配置文件中的值。

### 第六步：开始打包

- 确认输出目录（默认为项目根目录，可在偏好设置中更改默认值）。
- 点击“开始打包”，工具会：
  1. 校验配置文件格式。
  2. 检查所有源文件是否存在。
  3. 创建临时构建目录。
  4. 复制文件并设置权限。
  5. 生成 `DEBIAN/control`（或复制自定义 control）。
  6. 执行 `dpkg -b` 生成 `.deb` 包。
- 打包完成后，`.deb` 文件会出现在输出目录中。

### 第七步：查看日志

日志区域会实时显示详细步骤，成功或失败均有明确提示。

---

## 偏好设置

通过“工具”→“偏好设置”可以配置以下选项：

- **默认输出目录**：每次启动时自动填充的输出路径。
- **打包成功后自动清理构建目录**：避免残留临时文件。
- **日志级别**：控制日志输出的详细程度（目前仅用于未来扩展）。
- **默认架构**：新建或加载配置时默认使用的架构。

偏好设置保存在 `~/.config/packcraft/settings.json`，你可以手动编辑该文件。

---

## 目录结构

```
packcraft/
├── packcraft/                # 源码包
│   ├── app.py                # 应用入口
│   ├── main.py               # 程序主入口
│   ├── core/                 # 核心逻辑
│   │   ├── base_packager.py  # 打包器基类
│   │   ├── deb_packager.py   # DEB 打包引擎
│   │   ├── config_loader.py  # 配置加载器
│   │   └── validator.py      # 配置与项目验证
│   ├── gui/                  # 图形界面
│   │   ├── main_window.py    # 主窗口
│   │   └── ...               # 其他 UI 组件
│   ├── resources/            # 资源文件
│   │   ├── icons/            # 应用图标
│   │   └── locale/           # 国际化翻译文件
│   ├── templates/            # 预设配置模板
│   └── utils/                # 工具函数
├── tests/                    # 单元测试
├── scripts/                  # 辅助脚本
├── docs/                     # 文档
├── requirements.txt          # Python 依赖
├── run.sh                    # 启动脚本
├── Makefile                  # 构建辅助
└── README.md                 # 本文件
```

---

## 开发指南

### 扩展打包格式

若要添加对 RPM、PKG 等其他格式的支持，可继承 `core.base_packager.BasePackager`，实现 `build()` 方法，并在 `main_window.py` 的打包类型下拉菜单中注册。

### 国际化

项目已预留国际化支持（`resources/locale/` 中的 `.po` 文件）。若需翻译，可使用 gettext 工具生成 `.mo` 文件，并在 `app.py` 中启用。

### 运行测试

```bash
pytest tests/
```

---

## 常见问题

### 1. 启动时提示 `ModuleNotFoundError: No module named 'PIL'`
- 这是 Pillow 未安装，图标可能无法显示，但应用仍可正常使用。若希望显示图标，执行 `pip install Pillow`。

### 2. 打包时报错 `dpkg: command not found`
- 说明系统中未安装 `dpkg`，请在 Debian/Ubuntu 上执行 `sudo apt install dpkg`。

### 3. 配置文件中的 `dest` 路径以 `/` 开头，是否会被视为绝对路径？
- PackCraft 会自动将开头的 `/` 去除，作为相对路径处理（相对于构建根目录 `build/包名/`），因此你只需按目标安装路径书写即可（如 `/usr/bin/myapp` 会被正确安装到 `build/包名/usr/bin/myapp`）。

### 4. 如何自定义 `control` 文件的字段？
- 方法一：在配置中使用 `control_fields` 对象覆盖默认字段。
- 方法二：在界面中勾选“使用自定义 control 文件”，并选择一个外部 `control` 文件。

---

## 贡献

欢迎提交 Issue 和 Pull Request。请确保代码符合 PEP 8 规范，并尽可能添加测试用例。

---

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---

## 作者

温暖断章 &lt;1802272181@qq.com&gt;

---

**Happy Packaging! 🎉**