# 从源码构建 TechKit

本指南说明如何为不同平台和用例从源码构建 TechKit。

## 前提条件

### 必需工具

- **CMake**: 版本 3.14 或更高
- **C++ 编译器**: 兼容 C++11 的编译器
  - **GCC**: 5.0 或更高
  - **Clang**: 3.4 或更高
  - **MSVC**: Visual Studio 2015 或更高（Windows）
- **Git**: 用于克隆仓库

### 可选依赖项

- **Python 3.10+**: 用于构建 Python 绑定
- **Emscripten**: 用于构建 WebAssembly 绑定
- **Catch2**: 由 CMake 自动下载用于测试

## 快速开始

### 克隆仓库

```bash
git clone https://github.com/yiivon/techkit.git
cd techkit
```

### 构建原生库

```bash
# 创建构建目录
mkdir build && cd build

# 配置 CMake
cmake .. -DCMAKE_BUILD_TYPE=Release

# 构建（推荐并行构建）
cmake --build . --parallel

# 运行测试（可选）
ctest --output-on-failure
```

### 安装（可选）

```bash
cmake --install . --prefix /usr/local
```

## 构建选项

TechKit 提供多个 CMake 选项来自定义构建：

| Option | Default | Description |
|--------|---------|-------------|
| `TECHKIT_BUILD_SHARED` | `ON` (standalone) / `OFF` (submodule) | Build shared library (.so/.dll/.dylib) |
| `TECHKIT_BUILD_STATIC` | `ON` | Build static library (.a/.lib) |
| `TECHKIT_BUILD_TESTS` | `ON` (standalone) / `OFF` (submodule) | Build unit tests |
| `TECHKIT_BUILD_EXAMPLES` | `ON` (standalone) / `OFF` (submodule) | Build example programs |
| `TECHKIT_BUILD_VALIDATION` | `OFF` | Build TA-Lib validation tests |
| `TECHKIT_BUILD_PYTHON` | `OFF` | Build Python bindings |
| `TECHKIT_BUILD_WASM` | `OFF` | Build WebAssembly bindings |
| `TECHKIT_CXX_STANDARD` | `11` | C++ standard (11, 14, 17, 20) |

### 示例：自定义构建配置

```bash
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DTECHKIT_BUILD_SHARED=ON \
    -DTECHKIT_BUILD_STATIC=OFF \
    -DTECHKIT_BUILD_TESTS=OFF \
    -DTECHKIT_BUILD_EXAMPLES=OFF \
    -DTECHKIT_CXX_STANDARD=17
```

## 平台特定说明

### Linux

```bash
# Install dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install build-essential cmake git

# Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --parallel

# Install system-wide (optional)
sudo cmake --install . --prefix /usr/local
```

### macOS

```bash
# Install dependencies via Homebrew
brew install cmake

# Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --parallel
```

### Windows

#### 使用 Visual Studio

```batch
# Open Developer Command Prompt
mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release
```

#### 使用 MinGW

```bash
# Install MinGW-w64 and CMake
mkdir build && cd build
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release
cmake --build .
```

## 构建 Python 绑定

### 前提条件

- Python 3.10 或更高
- NumPy 1.21 或更高
- pip 和构建工具

### 开发安装

```bash
cd bindings/python
pip install -e .
```

### 构建分发包

```bash
cd bindings/python

# Install build tools
pip install build wheel

# Build wheel
python -m build --wheel

# Build source distribution (optional)
python -m build --sdist
```

### 为多平台构建

使用 `cibuildwheel` 进行跨平台 wheel 构建：

```bash
pip install cibuildwheel
cibuildwheel --platform linux
```

## 构建 WebAssembly 绑定

### 前提条件

1. 安装 Emscripten SDK：
```bash
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
```

### 构建 WASM

```bash
cd bindings/wasm

# Core edition (158 indicators)
mkdir build-core && cd build-core
emcmake cmake ../src/core
emmake make -j4

# Full edition (189 indicators)
cd ..
mkdir build-full && cd build-full
emcmake cmake ../src/full
emmake make -j4
```

### 输出文件

- `techkit-core.wasm` - Core edition (~200KB)
- `techkit-full.wasm` - Full edition (~800KB)
- `techkit-core.js` - JavaScript bindings
- `techkit-full.js` - JavaScript bindings

## 运行测试

### 单元测试

```bash
cd build
ctest --output-on-failure
```

### 运行特定测试

```bash
cd build
./tests/test_rsi
```

### 验证测试（TA-Lib 对比）

```bash
# Build with validation enabled
cmake .. -DTECHKIT_BUILD_VALIDATION=ON
cmake --build .

# Run validation
cd validation
./techkit_validation
```

## 作为 Git 子模块构建

如果 TechKit 作为子模块包含在你的项目中：

```bash
# Add submodule
git submodule add https://github.com/yiivon/techkit.git libs/techkit

# Initialize and update
git submodule update --init --recursive
```

在你的 `CMakeLists.txt` 中：

```cmake
# Add TechKit subdirectory
add_subdirectory(libs/techkit)

# Link to your target
target_link_libraries(your_app PRIVATE techkit::static)
```

**注意**：作为子模块构建时，`TECHKIT_BUILD_SHARED` 默认为 `OFF`，`TECHKIT_BUILD_TESTS` 默认为 `OFF`，以避免冲突。

## 使用已安装的包

如果 TechKit 已系统级安装：

```cmake
find_package(TechKit REQUIRED)
target_link_libraries(your_app PRIVATE TechKit::techkit)
```

## 故障排除

### CMake 未找到

**错误**：`CMake Error: Could not find CMAKE_ROOT`

**解决方案**：安装 CMake 3.14 或更高版本：
- Linux: `sudo apt-get install cmake`
- macOS: `brew install cmake`
- Windows: 从 [cmake.org](https://cmake.org/download/) 下载

### 编译器未找到

**错误**：`No CMAKE_CXX_COMPILER could be found`

**解决方案**： 
- Linux: 安装 build-essential: `sudo apt-get install build-essential`
- macOS: 安装 Xcode Command Line Tools: `xcode-select --install`
- Windows: 安装带 C++ 支持的 Visual Studio

### Python 绑定构建失败

**错误**：`Could not find Python3`

**解决方案**： 
- 确保已安装 Python 3.10+ 并在 PATH 中
- 安装 Python 开发头文件：
  - Linux: `sudo apt-get install python3-dev`
  - macOS: 随 Python 包含
  - Windows: 随 Python 安装程序包含

### WASM 构建失败

**错误**：`emcmake: command not found`

**解决方案**： 
- 确保 Emscripten SDK 已安装并激活
- 加载环境：`source /path/to/emsdk/emsdk_env.sh`
- 验证：`emcc --version`

## CI/CD 集成

### GitHub Actions 示例

```yaml
name: Build TechKit

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y build-essential cmake
      - name: Build
        run: |
          mkdir build && cd build
          cmake .. -DCMAKE_BUILD_TYPE=Release
          cmake --build . --parallel
      - name: Test
        run: |
          cd build
          ctest --output-on-failure
```

## 下一步

- [贡献指南](contributing.md) - 如何为 TechKit 做贡献
- [更新日志](changelog.md) - 版本历史和变更
- [API 参考](../api/index.md) - 完整 API 文档