# puppy

**Repository Path**: puppy-group/puppy

## Basic Information

- **Project Name**: puppy
- **Description**: 项目介绍
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-16
- **Last Updated**: 2025-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Puppy Group 项目总览

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

## 目录结构

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

## 子项目摘要

### 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。