Puppy Group 项目总览

Puppy Group 是一组面向系统与工程实践的开源项目集合，覆盖操作系统、编译/语言、虚拟化、区块链与智能合约、数据库与缓存、三维引擎与多媒体、大模型训练与工具链等多个方向。本文件统一汇总各子项目的简介、核心特性与使用说明，并提供交叉链接与统一风格建议，便于快速了解与上手。

目录结构

• ../puppy-chain/ — Rust 区块链与智能合约开发、运行与工具链（README）
• ../puppy-llvm/ — LLVM 学习与生产级工具链实践（README）
• ../puppy-script-lang/ — 轻量脚本语言，强调快速原型与可嵌入（README）
• ../puppy-vm/ — 轻量高性能虚拟化解决方案与管理（README）
• ../puppy-player/ — 基于 FFmpeg + Qt 的跨平台多媒体播放器（README）
• ../puppy-db/ — 轻量高速的数据库管理与存取（README）
• ../puppy-3d-engine/ — 轻量跨平台 3D 引擎（README）
• ../puppy-cache/ — 高性能轻量缓存管理，支持多策略（README）
• ../puppy-os/ — PuppyOS 微内核操作系统（Rust）（README）
• ../puppy-bigmodel/ — 兼容 Metal/CUDA 的大模型训练与工具链（README）
• ../puppy-lang/ — 实验性编程语言与编译管线（README）

子项目摘要

puppy-chain

• 简介：Rust 实现的区块链与智能合约平台，提供完整的合约开发、测试、部署与高效运行时。
• 核心特性：简洁合约接口、完善测试工具、效率与安全并重、模块化架构、跨平台支持。
• 基本使用：安装 Rust 工具链（rustup/cargo），在项目目录执行 cargo build --release。更多示例与 CLI 用法见子仓库文档。
• 文档：../puppy-chain/README.md

puppy-llvm

• 简介：以 LLVM 为核心的学习与生产工具链实践，包含 IR 构造、Pass、JIT 等示例与工程模板。
• 核心特性：模块化架构、清晰编码规范、教程驱动示例、面向生产的工具链。
• 基本使用：安装 LLVM 12+、CMake/Ninja 与编译器；执行 cmake -S . -B build && cmake --build build。
• 文档：../puppy-llvm/README.md

puppy-script-lang

• 简介：轻量脚本语言，面向快速开发与原型验证，强调可嵌入与跨平台。
• 核心特性：简单语法、快速上手、可嵌入运行、友好生态（规划中）。
• 基本使用：按子仓库说明安装对应构建工具（C++/Go/Rust），示例语法与 REPL 逐步完善中。
• 文档：../puppy-script-lang/README.md

puppy-vm

• 简介：轻量、高性能的虚拟化引擎，支持多平台部署与简易管理。
• 核心特性：轻量设计、多平台支持、高性能运行、友好 CLI/配置。
• 基本使用：准备 C++/Rust/Go 构建环境，按子仓库说明构建与使用（示例 YAML/CLI 已提供）。
• 文档：../puppy-vm/README.md

puppy-player

• 简介：跨平台多媒体播放器，基于 FFmpeg 解码与 Qt 界面。
• 核心特性：多格式支持、本地与流媒体播放、简洁 UI、低资源占用。
• 基本使用：安装 Qt 与 FFmpeg，使用 CMake 构建；运行可执行并加载媒体文件播放。
• 文档：../puppy-player/README.md

puppy-db

• 简介：面向小型应用与快速原型的轻量高速数据库管理组件。
• 核心特性：直观 API、最小配置、快速查询；规划索引、TTL 与事务等能力。
• 基本使用：按子仓库说明构建为库或可执行，依示例进行 CRUD/索引/事务操作。
• 文档：../puppy-db/README.md

puppy-3d-engine

• 简介：轻量、易用、可插拔模块的跨平台 3D 引擎。
• 核心特性：场景/实体/组件、渲染管线、模型与资源管理、摄像机与光照、输入系统；规划物理/音频/脚本等模块。
• 基本使用：安装图形 API 与 CMake/编译器，cmake -S . -B build && cmake --build build，按示例创建场景与渲染。
• 文档：../puppy-3d-engine/README.md

puppy-cache

• 简介：多策略（LRU/LFU/FIFO/TTL）高性能轻量缓存管理，线程安全与低内存占用。
• 核心特性：策略可选、易集成、灵活数据结构（规划）、持久化/分布式（规划）。
• 基本使用：以库方式集成，参考示例进行创建、设置/获取与过期管理。
• 文档：../puppy-cache/README.md

puppy-os

• 简介：Rust 编写的微内核操作系统 PuppyOS，强调安全、稳定与效率。
• 核心特性：进程/内存管理、基础设备驱动、文件系统（VFS/devfs）、系统调用（POSIX 风格）、基础 Shell。
• 基本使用：安装 Rust nightly 与 QEMU，按子仓库说明构建并通过 QEMU 运行实验环境。
• 文档：../puppy-os/README.md

puppy-bigmodel

• 简介：兼容 Apple GPU（Metal）与 NVIDIA GPU（CUDA）的跨平台大模型训练与工具链。
• 核心特性：高性能分布式训练、智能硬件检测、全流程监控、灵活配置与模型管理。
• 基本使用：准备 Python 环境与对应 GPU 驱动；pip install -e . 后使用 CLI/SDK 进行训练与评测。
• 文档：../puppy-bigmodel/README.md

puppy-lang

• 简介：实验性编程语言与编译管线，含完整前端（词法/语法/AST/语义）与 LLVM IR 后端。
• 核心特性：语言基础（变量/函数/控制流/集合）、实验性结构体/模式匹配/并发/接口、CLI 编译器与 IR 生成。
• 基本使用：安装 Go 与 LLVM 工具链（可选），go build ./... 后使用 CLI 将示例编译为 LLVM IR 或原生可执行。
• 文档：../puppy-lang/README.md

通用先决条件

• 操作系统：macOS、Linux、Windows（不同项目支持范围略有差异）
• 基础工具：git、终端/Shell、包管理器（brew/apt/choco 等）
• 语言/工具链：
  • Rust：rustup/cargo（puppy-chain、puppy-os 等）
  • C/C++：CMake、Ninja、Clang/GCC、必要的图形/系统库（puppy-llvm、puppy-player、puppy-3d-engine、puppy-vm 等）
  • Go：Go 1.20+（puppy-lang、部分脚本/工具）
  • Python：Python 3.8+（puppy-bigmodel 等，具体版本以子项目为准）
  • 依赖组件：LLVM、Qt、FFmpeg、CUDA/Metal、Graphviz/Doxygen 等按子仓库文档要求安装。

统一使用说明（速览）

• 克隆某子项目：git clone https://github.com/.../puppy-<name>.git 或在本组仓库中进入对应目录。
• 常见构建方式：
  • Rust：cargo build --release
  • CMake：cmake -S . -B build && cmake --build build
  • Go：go build ./...
  • Python/ML：pip install -e . 后按 CLI/SDK 文档执行。
• 运行与示例：各子仓库 README.md 均提供最小示例与使用指引；如需跨项目协同，请参考“快速链接”与对应文档。

统一风格与贡献建议

• 代码风格：
  • Rust 使用 cargo fmt 与 clippy；
  • C/C++ 建议 clang-format 与 CMake 统一构建；
  • Go 使用 gofmt/golangci-lint；
  • Python 遵循 PEP8，并建议使用 ruff/black。
• 分支与提交：
  • 分支命名：feat/*、fix/*、docs/*、perf/*、refactor/*；
  • 提交信息：动词开头，简明描述变更范围与影响；
  • PR：关联 Issue，提供背景、设计与测试说明，保持小步提交。
• 版本兼容：尽量遵循语义化版本（SemVer），在 README 标注最低工具链版本与平台支持矩阵。

许可与合规

• 多数项目采用 Apache License 2.0；puppy-os 采用 MIT License；其余项目以各自仓库的 LICENSE 文件为准。
• 贡献代码需遵循对应项目的许可与贡献指南，提交前请确认依赖的第三方库许可兼容性。

快速链接与文档索引

• puppy-chain：../puppy-chain/README.md
• puppy-llvm：../puppy-llvm/README.md
• puppy-script-lang：../puppy-script-lang/README.md
• puppy-vm：../puppy-vm/README.md
• puppy-player：../puppy-player/README.md
• puppy-db：../puppy-db/README.md
• puppy-3d-engine：../puppy-3d-engine/README.md
• puppy-cache：../puppy-cache/README.md
• puppy-os：../puppy-os/README.md
• puppy-bigmodel：../puppy-bigmodel/README.md
• puppy-lang：../puppy-lang/README.md

—— 本总览文档将随各子项目迭代持续更新，欢迎提交改进建议或 PR。