# puppy-llvm

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

## Basic Information

- **Project Name**: puppy-llvm
- **Description**: puppy-llvm：一个专注于LLVM编译器技术的开源项目，旨在为初学者和开发者提供友好、高效的编译工具链支持与学习资源。
- **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-llvm

一个专注于 LLVM 编译器技术的开源项目，旨在为初学者和开发者提供友好、高效的编译工具链支持与学习资源。项目采用模块化设计与清晰的编码规范，帮助你快速上手、深入学习并参与贡献。

## 核心内容
- 精心设计的 LLVM 工具链实现
- 完善的编译优化教程与示例代码
- 针对不同技能水平开发者的学习路径
- 详细的 API 文档与开发指南
- 持续维护的代码库与社区支持

## 特性亮点
- 模块化架构：工具链、Pass、IR 处理、JIT 子系统彼此解耦，便于扩展和复用
- 清晰规范：统一的代码风格与目录结构，降低阅读与维护成本
- 教程驱动：从基础到进阶的示例与讲解，覆盖常用 LLVM API 与优化技巧
- 生产导向：面向实战的工具与脚手架，支持快速搭建编译相关项目

## 系统要求
- 操作系统：macOS 12+/Ubuntu 20.04+/Windows 10+
- 架构：x86_64 或 arm64（Apple Silicon 已验证）
- 必备依赖：
  - LLVM 12+（推荐 14 或更高版本）
  - CMake 3.20+
  - Ninja（或使用你偏好的生成器）
  - Clang/GCC（用于编译 C/C++ 代码）
  - Python 3.8+（用于脚本与工具链胶水代码）
  - Doxygen 1.9+（可选，用于生成 API 文档）
  - Graphviz（可选，用于生成调用图/依赖图）

## 安装与构建

### macOS（Homebrew）
```bash
brew install llvm cmake ninja python doxygen graphviz
export LLVM_DIR="$(brew --prefix llvm)/lib/cmake/llvm"
export PATH="$(brew --prefix llvm)/bin:$PATH"  # 使用 brew 的 clang/llvm 工具

git clone https://your.repo.url/puppy-llvm.git
cd puppy-llvm && mkdir -p build && cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR="$LLVM_DIR"
ninja
```

### Ubuntu/Debian（APT）
```bash
sudo apt update
sudo apt install -y llvm-14-dev clang-14 cmake ninja-build python3 doxygen graphviz
export LLVM_DIR=/usr/lib/llvm-14/cmake

git clone https://your.repo.url/puppy-llvm.git
cd puppy-llvm && mkdir -p build && cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR="$LLVM_DIR"
ninja
```

### Windows（PowerShell + Chocolatey）
```powershell
choco install llvm cmake ninja -y
$env:LLVM_DIR = "C:\Program Files\LLVM\lib\cmake\llvm"

git clone https://your.repo.url/puppy-llvm.git
cd puppy-llvm
mkdir build; cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_DIR="$env:LLVM_DIR"
ninja
```

### CMake 使用 `find_package(LLVM)` 示例
在你的子项目或示例的 `CMakeLists.txt` 中加入：
```cmake
cmake_minimum_required(VERSION 3.20)
project(puppy_llvm_demo CXX)

set(CMAKE_CXX_STANDARD 17)
find_package(LLVM REQUIRED CONFIG)
message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
message(STATUS "Using LLVMConfig.cmake in: ${LLVM_DIR}")

include_directories(${LLVM_INCLUDE_DIRS})
add_definitions(${LLVM_DEFINITIONS})

add_executable(demo demo.cpp)
llvm_map_components_to_libnames(LLVM_LIBS core irreader passes support)
target_link_libraries(demo PRIVATE ${LLVM_LIBS})
```

## 代码示例

### 1) 使用 IRBuilder 构建简单函数
```cpp
#include <llvm/IR/IRBuilder.h>
#include <llvm/IR/LLVMContext.h>
#include <llvm/IR/Module.h>
#include <llvm/IR/Verifier.h>

int main() {
  llvm::LLVMContext ctx;
  auto module = std::make_unique<llvm::Module>("puppy", ctx);
  llvm::IRBuilder<> builder(ctx);

  auto intTy = llvm::Type::getInt32Ty(ctx);
  auto funcTy = llvm::FunctionType::get(intTy, {intTy, intTy}, false);
  auto func = llvm::Function::Create(funcTy, llvm::Function::ExternalLinkage, "add", module.get());

  auto entry = llvm::BasicBlock::Create(ctx, "entry", func);
  builder.SetInsertPoint(entry);

  auto args = func->args();
  auto a = args.begin();
  auto b = std::next(a);
  auto sum = builder.CreateAdd(&*a, &*b, "sum");
  builder.CreateRet(sum);

  if (llvm::verifyModule(*module, &llvm::errs())) {
    llvm::errs() << "Module verification failed\n";
    return 1;
  }
  module->print(llvm::outs(), nullptr);
  return 0;
}
```

### 2) 自定义 FunctionPass 示例（统计指令数量）
```cpp
#include <llvm/IR/Function.h>
#include <llvm/Pass.h>
#include <llvm/Support/raw_ostream.h>

using namespace llvm;

struct CountInstPass : public FunctionPass {
  static char ID;
  CountInstPass() : FunctionPass(ID) {}

  bool runOnFunction(Function &F) override {
    size_t count = 0;
    for (auto &BB : F) for (auto &I : BB) ++count;
    errs() << "Function " << F.getName() << " has " << count << " instructions\n";
    return false; // 不修改 IR
  }
};

char CountInstPass::ID = 0;
static RegisterPass<CountInstPass> X("count-inst", "Count Instructions", false, false);
```

### 3) ORC JIT（LLJIT）示例（简化版）
```cpp
#include <llvm/ExecutionEngine/Orc/LLJIT.h>
#include <llvm/ExecutionEngine/Orc/ThreadSafeModule.h>
#include <llvm/IR/IRBuilder.h>
#include <llvm/IR/Module.h>

using namespace llvm;
using namespace llvm::orc;

int main() {
  auto J = LLJITBuilder().create();
  if (!J) { errs() << "Create LLJIT failed\n"; return 1; }

  LLVMContext Ctx; auto M = std::make_unique<Module>("jit", Ctx);
  IRBuilder<> B(Ctx);
  auto FT = FunctionType::get(Type::getInt32Ty(Ctx), {Type::getInt32Ty(Ctx)}, false);
  auto F = Function::Create(FT, Function::ExternalLinkage, "square", M.get());
  auto BB = BasicBlock::Create(Ctx, "entry", F);
  B.SetInsertPoint(BB);
  auto X = &*F->arg_begin();
  B.CreateRet(B.CreateMul(X, X));

  ThreadSafeModule TSM(std::move(M), std::make_unique<LLVMContext>());
  if (auto Err = (*J)->addIRModule(std::move(TSM))) { errs() << "addIRModule failed\n"; return 1; }

  auto Sym = (*J)->lookup("square");
  if (!Sym) { errs() << "lookup failed\n"; return 1; }
  using Fn = int(*)(int);
  auto *Square = (Fn)Sym->getAddress();
  outs() << "square(7) = " << Square(7) << "\n";
  return 0;
}
```

## 学习路径建议
- 初级：LLVM 基本概念（IR、Pass、Module）、IRBuilder 实践、CMake 集成
- 中级：编写与注册优化 Pass、使用分析与转换 API、IRReader/PassManager
- 高级：ORC JIT、目标后端与代码生成、跨平台构建与调试、性能分析

## 文档与示例
- API 文档：使用 Doxygen 生成，示例命令：
  ```bash
  doxygen docs/Doxyfile
  # 或通过 CMake 启用：cmake -S . -B build -DBUILD_DOCS=ON
  ```
- 示例代码：位于 `examples/`（如果未创建，该目录将随后续版本补充）；你可以将上面的示例保存为 `demo.cpp` 并按“安装与构建”一节的 CMake 配置进行编译运行。

## 平台兼容性与版本策略
- 已验证：macOS（Intel/Apple Silicon）、Ubuntu 20.04+/22.04+、Windows 10/11
- 优先支持：最新两个 LLVM 大版本（例如 14/15 或更高），其余版本视需求兼容
- 构建生成器：默认使用 Ninja，也支持其他生成器（如 Unix Makefiles、VS）

## 许可协议
- 本项目采用 Apache License 2.0 许可协议，详见仓库根目录的 `LICENSE` 文件。

## 贡献指南
- 工作流：
  - Fork 仓库 → 创建功能分支（如 `feat/xxx`）→ 提交代码 → 发起 Pull Request
- 代码规范：
  - 建议启用 `clang-format` 与 `clang-tidy`，保持统一风格与基本静态检查
  - 目录与命名遵循模块化约定（工具链/Pass/JIT/示例/文档）
- 提交信息：
  - 使用清晰的动词与范围前缀（如 `feat:`, `fix:`, `docs:`）
- PR 检查清单：
  - 包含必要的文档与示例更新
  - 通过本地构建与基本测试（若有）

## 社区与支持
- 问题反馈：在 Issue 中描述环境、复现步骤与期望结果
- 讨论与建议：欢迎提出教程方向、API 覆盖与示例场景建议
- 长期维护：我们会定期跟进 LLVM 的新版本与生态变化，持续改进文档与代码

—— 感谢你对 puppy-llvm 的关注与贡献！