# Sikuwa

基于 Nuitka 的跨平台 Python 项目打包工具

--- ## 概述 Sikuwa 是一款专业的 Python 项目打包工具，基于 Nuitka 编译器构建，支持将 Python 项目编译为独立的可执行文件。提供两种编译模式，满足不同场景的需求。 ### 核心特性 | 特性 | 描述 | |------|------| | 双模式编译 | 支持 Nuitka 模式和 Native 原生编译模式 | | 跨平台支持 | Windows、Linux、macOS 全平台构建 | | 增量编译 | 智能检测变更，仅编译修改的部分 | | 配置驱动 | 基于 TOML 的声明式配置 | | 国际化 | 内置多语言支持 (i18n) | | 高性能缓存 | C++ 实现的智能缓存系统 | --- ## Features ### 编译模式 #### Nuitka 模式 (默认) 使用 Nuitka 编译器将 Python 代码编译为优化的机器码。 - 完整的 Python 兼容性 - 自动依赖分析与打包 - 支持 Standalone 和 OneFile 模式 - 内置插件系统 #### Native 模式将 Python 代码转换为 C/C++ 源码，通过 GCC/G++ 编译为原生二进制文件。 - 生成通用动态链接库 (.dll/.so) - 不依赖 Python 专用格式 (.pyd) - 支持静态链接 - 可保留生成的 C/C++ 源码用于审计 ### 增量编译系统基于依赖图的智能增量编译，实现"指哪编哪"的精确编译策略。 ``` 源码改变 -> 依赖分析 -> 影响范围计算 -> 最小化重编译 ``` - 函数级粒度的变更检测 - 依赖关系追踪 - 编译缓存持久化 - 并行编译支持 --- ## Installation ### 系统要求 | 组件 | 版本要求 | |------|----------| | Python | >= 3.7 | | Nuitka | >= 2.0 | | GCC/G++ | >= 8.0 (Native 模式) | | CMake | >= 3.16 (可选，用于 C++ 扩展) | ### 获取工具链 ```bash git clone https://github.com/FORGE24/Sikuwa.git cd Sikuwa ``` ### 安装依赖 ```bash pip install click tomli tomli-w nuitka ``` ### 运行方式 ```bash # 直接运行 python -m sikuwa --version python -m sikuwa doctor # 或添加别名 (PowerShell) Set-Alias sikuwa "python -m sikuwa" # 或添加别名 (Bash) alias sikuwa='python -m sikuwa' ``` --- ## Quick Start ### 1. 初始化项目 ```bash sikuwa init ``` 该命令将在当前目录创建 `sikuwa.toml` 配置文件。 ### 2. 配置项目编辑 `sikuwa.toml`： ```toml [sikuwa] project_name = "myproject" version = "1.0.0" main_script = "src/main.py" src_dir = "src" output_dir = "dist" platforms = ["windows", "linux"] [sikuwa.nuitka] standalone = true onefile = false include_packages = [ "requests", "numpy", ] ``` ### 3. 构建项目 ```bash # 使用 Nuitka 模式构建 sikuwa build # 使用 Native 模式构建 sikuwa build -m native # 构建指定平台 sikuwa build -p windows # 详细输出模式 sikuwa build -v ``` ### 4. 清理构建文件 ```bash sikuwa clean ``` --- ## 命令行参考 ### 命令列表 | 命令 | 描述 | |------|------| | `build` | 构建项目 | | `clean` | 清理构建文件 | | `init` | 初始化项目配置 | | `info` | 显示项目信息 | | `validate` | 验证配置文件 | | `doctor` | 检查构建环境 | | `version` | 显示版本信息 | ### build 命令选项 | 选项 | 简写 | 描述 | |------|------|------| | `--config` | `-c` | 指定配置文件路径 | | `--platform` | `-p` | 目标平台 (windows/linux/macos) | | `--mode` | `-m` | 编译模式 (nuitka/native) | | `--verbose` | `-v` | 详细输出模式 | | `--force` | `-f` | 强制重新构建 | | `--keep-c-source` | - | 保留生成的 C/C++ 源码 | --- ## 配置文件详解 ### 基础配置 ```toml [sikuwa] # 项目基本信息 project_name = "myproject" # 项目名称 version = "1.0.0" # 版本号 description = "项目描述" # 可选 author = "作者名" # 可选 # 构建路径配置 main_script = "main.py" # 入口脚本 src_dir = "." # 源码目录 output_dir = "dist" # 输出目录 build_dir = "build" # 构建临时目录 # 目标平台 platforms = ["windows", "linux", "macos"] ``` ### Nuitka 选项 ```toml [sikuwa.nuitka] # 基础选项 standalone = true # 独立模式 onefile = false # 单文件模式 follow_imports = true # 跟踪导入 show_progress = true # 显示进度 enable_console = true # 启用控制台 # 优化选项 optimize = true # 启用优化 lto = false # 链接时优化 # Windows 特定选项 windows_icon = "icon.ico" windows_company_name = "Company" windows_product_name = "Product" # macOS 特定选项 macos_app_bundle = false macos_icon = "icon.icns" # 包含/排除 include_packages = ["package1", "package2"] include_modules = ["module1"] nofollow_imports = ["test_*"] # 插件 enable_plugins = ["pyside6", "numpy"] # 数据文件 include_data_dirs = [ { src = "assets", dest = "assets" } ] # 额外参数 extra_args = [ "--assume-yes-for-downloads" ] ``` ### Native 编译选项 ```toml [sikuwa.native] # 编译器选择 cc = "gcc" # C 编译器 cxx = "g++" # C++ 编译器 # 编译标志 c_flags = ["-O2", "-fPIC"] cxx_flags = ["-O2", "-fPIC", "-std=c++17"] link_flags = [] # 输出选项 output_dll = true # 生成动态库 output_exe = true # 生成可执行文件 output_static = false # 生成静态库 # Python 嵌入 embed_python = true # 嵌入 Python python_static = false # 静态链接 Python # 优化选项 lto = false # 链接时优化 strip = true # 剥离符号 # 调试选项 debug = false # 调试模式 keep_c_source = false # 保留 C/C++ 源码 ``` --- ## 项目结构 ``` sikuwa/ ├── __init__.py # 包初始化 ├── __main__.py # 入口点 ├── cli.py # 命令行接口 ├── config.py # 配置管理 ├── builder.py # 构建器核心 ├── compiler.py # Native 编译器 ├── parser.py # 代码解析器 ├── log.py # 日志系统 ├── i18n.py # 国际化支持 ├── nuitka_loader.py # Nuitka 加载器 ├── cpp_cache/ # C++ 缓存扩展 │ ├── smart_cache.cpp │ ├── smart_cache.h │ └── pysmartcache.cpp ├── incremental/ # 增量编译模块 │ ├── core.py # 核心实现 │ ├── analyzer.py # 代码分析器 │ ├── smart_cache.py # 智能缓存 │ └── compiler_integration.py └── i18n/ # 国际化资源 └── locales/ └── en_US/ ``` --- ## Documentation ### 在线文档 - [官方文档](https://www.sanrol-cloud.top) - [API 参考](https://www.sanrol-cloud.top/api) - [示例项目](https://github.com/FORGE24/Sikuwa/tree/main/examples) ### 本地文档 ```bash # 生成文档 cd docs make html ``` --- ## Contributing 欢迎贡献代码、报告问题或提出改进建议。 ### 贡献流程 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 创建 Pull Request ### 开发环境设置 ```bash # 克隆仓库 git clone https://github.com/FORGE24/Sikuwa.git cd Sikuwa # 创建虚拟环境 python -m venv .venv .venv\Scripts\activate # Windows source .venv/bin/activate # Linux/macOS # 安装依赖 pip install click tomli tomli-w nuitka pytest # 运行测试 pytest tests/ ``` ### 代码规范 - 遵循 PEP 8 代码风格 - 使用类型注解 - 编写单元测试 - 更新相关文档 ### 提交规范提交信息格式： ``` ():