# xm-python

**Repository Path**: yuan_hp/xm-python

## Basic Information

- **Project Name**: xm-python
- **Description**: addon for python
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
  <a href="https://xmake.io">
    <img width="120" height="120" src="https://xmake.io/assets/img/logo.png">
  </a>

  <h1>xm-python</h1>

  <b>Python addon for xmake</b><br/>
  <i>Create, build, run and package Python projects with xmake</i>
</div>

## Features

- **Python 自动探测与安装**：优先使用缓存 → 系统 PATH → 包管理器（xmake-repo / vcpkg / conan / pkg-config）逐个尝试安装
- **版本约束**：`--pyversion=3.11` 或 `--pyversion=">=3.10 <3.12"` 精确匹配
- **虚拟环境**：`--venv=build/venv` 自动创建并复用 venv
- **依赖管理**：构建时自动执行 `pip install -r requirements.txt`
- **VSCode 集成**：自动生成 `.vscode/settings.json` 中的 debugpy 调试配置
- **一键打包**：通过 PyInstaller 将 Python 应用打包为可执行文件
- **跨平台**：Windows / Linux / macOS

## Installation

```console
$ xmake addon --install https://gitee.com/yuan_hp/xm-python.git
$ xmake addon --install https://gitcode.com/yuan_hp/xm-python.git
```

## Quick Start

使用模板创建一个 Python GUI 项目：

```console
$ xmake create -t xm-python.cpy myproject
$ cd myproject
$ xmake              # 查找/安装 Python + pip 依赖
$ xmake run          # 运行入口 main.py
$ xmake install      # 使用 PyInstaller 打包为可执行文件
```

## Usage

### 1. 在项目中引入 addon

```lua
-- xmake.lua


target("myapp")
    add_rules("@addon/xm-python/app")
    add_files("src/main.py")
    add_files("requirements.txt")
```

目录结构示例：

```
myproject/
├── xmake.lua
├── requirements.txt
└── src/
    ├── main.py          -- 唯一的入口文件
    ├── app.py
    ├── res.py
    └── images/
        └── logo.ico
```

### 2. xmake python 命令

`xm-python` 注册了一个 `python` 任务，可直接调用 Python 解释器：

```console
# 使用系统或自动安装的 Python
$ xmake python -- -m pip install numpy

# 强制刷新缓存，重装 Python
$ xmake python -f -- -m pip install -r requirements.txt

# 指定版本
$ xmake python --pyversion=3.11 -- -c "import sys; print(sys.version)"

# 创建/使用虚拟环境
$ xmake python --venv=build/venv -- -m pip install flask

# 仅用包管理器安装（不使用系统 Python）
$ xmake python --system=false -- -V
```

### 3. 打包为可执行文件

在 xmake.lua 中重写 `on_install`，调用 PyInstaller：

```lua
target("myapp")
    add_rules("@addon/xm-python/app")
    add_files("src/main.py")
    add_files("src/res.py")
    add_files("requirements.txt")

    on_install(function (target)
        import("core.base.task")
        local pymain = target:sourcefiles()[1]
        task.run("python", {
            ["pyargs"] = {
                "-m", "PyInstaller",
                "--distpath", "build/dist",
                "-F",                            -- 单文件模式
                "-w",                            -- 无控制台窗口
                "-i", "src/images/logo.ico",     -- 应用图标
                pymain,
                "--noconfirm",
                "--name", target:name(),
                "--add-data", "src/images/*;./src/images",
                "--add-data", "requirements.txt;.",
            }
        })
    end)
```

然后执行：

```console
$ xmake install
```

打包产物会输出到 `build/dist/myapp/`。

## 工作原理

### Python 查找顺序

1. **项目缓存**（默认：`<project>/.xmake/<host>/<arch>/python/cache.txt`）—— 命中则直接使用
2. **系统 PATH** —— 调用 `find_tool("python")`
3. **包管理器自动安装**（依次尝试，成功即停止）：

| 包名 | 来源 |
|------|------|
| `cpython` | xmake-repo |
| `python` | xmake-repo |
| `vcpkg::python3` | vcpkg |
| `conan::cpython` | conan |
| `pkgconfig::python3` | pkg-config |

4. 全部失败则报错退出

### 依赖自动安装

当目标中包含 `requirements.txt` 时，每次构建会自动执行：

```
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

依赖文件使用时间戳比对，未变更时跳过安装。

### VSCode 调试配置

首次 `xmake` 构建后，会自动在 `.vscode/settings.json` 写入：

```json
{
    "xmake.customDebugConfig": {
        "type": "debugpy",
        "request": "launch",
        "program": "G:/myproject/src/main.py",
        "cwd": "G:/myproject",
        "console": "integratedTerminal",
        "python": "G:/myproject/build/venv/Scripts/python.exe"
    }
}
```

配合 **xmake-vscode** 和 **Python Debugger (debugpy)** 扩展即可一键 F5 调试。

## 项目结构

```
xm-python/
├── addon.lua                       # addon 入口
├── version.txt                     # 版本号
├── src/
│   ├── plugins/
│   │   └── python/
│   │       ├── xmake.lua           # 任务注册
│   │       └── main.lua            # Python 自动探测/安装/缓存主逻辑
│   ├── rules/
│   │   └── app/
│   │       └── xmake.lua           # Python 应用构建规则
│   └── templates/
│       └── python/xm-python/
│           └── cpy/                # 模板工程（main.py + requirements.txt）
└── README.md
```

## xmake python 命令行参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-f`, `--force` | flag | false | 强制刷新 Python 缓存，重新搜索 |
| `--venv=<dir>` | kv | `build/venv` | 虚拟环境目录，设为空则不创建 venv |
| `--system=true/false` | kv | `true` | 是否允许使用系统 PATH 中的 Python |
| `--pyversion=<ver>` | kv | — | 要求的 Python 版本，如 `3.11` 或 `">=3.10 <3.12"` |
| `--outpypath=<file>` | kv | — | 将 Python 路径写入指定文件（内部调试用） |
| `-- <args>` | vs | — | 传递给 Python 的参数 |

## Homepage

https://gitee.com/yuan_hp/xm-python

## License

Licensed under the Apache License 2.0.