Metadata-Version: 2.1
Name: pyoneer_djinni_build
Version: 0.1.0
Summary: Utility to package and distribute Djinni libraries easily.
Home-page: https://github.com/goudantongxue/pyoneer-djinni-build
Author: goudantongxue
Author-email: woshigoudan0913@gmail.com
License: MIT
Keywords: djinni
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE

# pyoneer-djinni-build

一个用于跨平台构建和打包 [Djinni](https://djinni.xlcpp.dev/) 库的 Python 命令行工具。

## 简介

`pyoneer-djinni-build` 是一个构建编排工具，旨在简化 Djinni 跨平台库的编译、构建和打包流程。通过统一的命令行接口，开发者可以轻松地为 Android、iOS、macOS、Windows 和 Linux 等多个平台构建原生库，并自动生成对应平台的分发包。

## 功能特性

- **多平台支持** — 支持 Android、iOS、macOS、Windows、Linux 五大平台
- **多架构编译** — 支持 x86_64、x86、armv8、armv7 等多种 CPU 架构
- **自动打包** — 自动生成平台专属分发包：
  - **AAR**（Android Archive）— 用于 Android 项目集成
  - **XCFramework** — 用于 iOS / macOS 项目集成
  - **Swift Package** — 用于 Swift 包管理器集成
  - **NuGet** — 用于 Windows / .NET 项目集成
- **Conan 集成** — 基于 Conan 2.0+ 进行依赖管理和构建配置
- **灵活配置** — 支持 Debug / Release 构建模式，可自定义构建目录和 Conan Profile

## 系统要求

- **Python** >= 3.10
- **Conan** >= 2.0
- **Git**（用于自动版本号提取）
- 各平台工具链：
  - Android: [Android NDK](https://developer.android.com/ndk)（需设置 `ANDROID_NDK_HOME` 环境变量）
  - iOS / macOS: [Xcode](https://developer.apple.com/xcode/)
  - Windows: [Visual Studio 2022](https://visualstudio.microsoft.com/)
  - Linux: GCC 11+

## 安装

### 通过 pip 安装

```bash
pip install pyoneer-djinni-build
```

### 从源码安装

```bash
git clone https://github.com/goudantongxue/pyoneer-djinni-build.git
cd pyoneer-djinni-build
pip install .
```

## 快速开始

### 基本用法

在你的 Djinni 项目中创建构建脚本：

```python
from pyoneer_djinni_build import DjinniBuild

djinni_build = DjinniBuild(lib_name='my_library')
djinni_build.main()
```

然后通过命令行参数指定目标平台和架构：

```bash
# 构建 Android (armv8 + x86_64) 并打包为 AAR
python build.py --android armv8 x86_64 --package aar

# 构建 iOS + macOS 并打包为 XCFramework
python build.py --iphoneos armv8 --iphonesimulator armv8 x86_64 --macos armv8 x86_64 --package xcframework

# 构建 XCFramework 并生成 Swift Package
python build.py --iphoneos armv8 --iphonesimulator armv8 x86_64 --macos armv8 x86_64 --package xcframework swiftpackage

# 构建 Windows (x64) 并打包为 NuGet
python build.py --windows x86_64 --package nuget

# 构建 Linux (x86_64)
python build.py --linux x86_64

# 使用 Debug 模式构建
python build.py --android armv8 --configuration debug
```

## 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--configuration {release,debug}` | 构建配置（Release 或 Debug） | `release` |
| `--android [ARCH ...]` | 构建 Android 平台，可指定架构 | — |
| `--iphoneos [ARCH ...]` | 构建 iOS 真机平台，可指定架构 | — |
| `--iphonesimulator [ARCH ...]` | 构建 iOS 模拟器平台，可指定架构 | — |
| `--macos [ARCH ...]` | 构建 macOS 平台，可指定架构 | — |
| `--windows [ARCH ...]` | 构建 Windows 平台，可指定架构 | — |
| `--linux [ARCH ...]` | 构建 Linux 平台，可指定架构 | — |
| `--build-directory PATH` | 构建输出目录 | `build/` |
| `--build-profile PROFILE` | Conan 构建 Profile 名称 | `default` |
| `--package [TYPE ...]` | 打包类型：`xcframework`、`swiftpackage`、`aar`、`nuget` | — |

### 支持的架构

| 架构 | Conan 名称 | Android 名称 | Windows 名称 |
|------|-----------|-------------|-------------|
| `x86_64` | x86_64 | x86_64 | win10-x64 |
| `x86` | x86 | x86 | win10-x86 |
| `armv8` | armv8 | arm64-v8a | win10-arm64 |
| `armv7` | armv7 | armeabi-v7a | win10-arm |

## 项目结构

```
pyoneer-djinni-build/
├── profiles/                        # Conan 构建 Profile（各平台配置）
│   ├── android                      # Android NDK Profile
│   ├── ios                          # iOS SDK Profile
│   ├── macos                        # macOS Profile
│   ├── windows                      # Windows MSVC Profile
│   └── linux                        # Linux GCC Profile
├── pyoneer_djinni_build/            # Python 主包
│   ├── __init__.py                  # 包入口，导出 DjinniBuild
│   ├── djinni_build.py              # 主编排类，CLI 入口
│   ├── build_context.py             # 构建上下文基类
│   ├── android_build_context.py     # Android 构建逻辑
│   ├── darwin_build_context.py      # iOS / macOS 构建逻辑
│   ├── windows_build_context.py     # Windows 构建逻辑
│   ├── linux_build_context.py       # Linux 构建逻辑
│   ├── argparse_enums.py            # CLI 枚举定义
│   └── print_prefixed.py            # 日志输出工具
├── .github/workflows/publish.yml    # CI/CD：自动发布到 PyPI
├── setup.py                         # 包安装配置
├── requirements.txt                 # 开发依赖
├── LICENSE                          # MIT 许可证
└── README.md                        # 项目文档
```

## DjinniBuild 配置参数

`DjinniBuild` 类支持以下初始化参数，用于自定义构建行为：

| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `lib_name` | `str` | 库名称（必填） | — |
| `default_build_dir` | `Path` | 默认构建输出目录 | `build/` |
| `default_conan_build_profile` | `str \| Path` | 默认 Conan 构建 Profile | `default` |
| `working_directory` | `Path` | 项目根目录 | 当前工作目录 |
| `darwin_target_dir` | `Path` | Darwin 平台目标定义路径 | `lib/platform/darwin` |
| `android_target_dir` | `Path` | Android 平台目标定义路径 | `lib/platform/android` |
| `windows_target_dir` | `Path` | Windows 平台目标定义路径 | `lib/platform/windows` |
| `android_profile` | `str \| Path` | Android Conan Profile 路径 | 内置 Profile |
| `macos_profile` | `str \| Path` | macOS Conan Profile 路径 | 内置 Profile |
| `ios_profile` | `str \| Path` | iOS Conan Profile 路径 | 内置 Profile |
| `windows_profile` | `str \| Path` | Windows Conan Profile 路径 | 内置 Profile |
| `linux_profile` | `str \| Path` | Linux Conan Profile 路径 | 内置 Profile |
| `nupkg_dir` | `Path` | NuGet 包模板目录 | `lib/platform/windows/package` |
| `android_project_dir` | `Path` | Android 项目目录（用于 AAR 构建） | `lib/platform/android/package` |
| `swiftpackage_dir` | `Path` | Swift Package 目录 | `lib/platform/darwin/package` |

## 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。

Copyright (c) 2025 pyoneer


