# Clash Meta 核心编译指南

## 环境准备

### 1. 安装必要工具

```bash
# macOS
brew install go
brew install android-ndk  # 或从 Android Studio 安装

# 验证
go version  # 需要 go 1.20+
```

### 2. 配置环境变量

```bash
# 添加到 ~/.zshrc 或 ~/.bash_profile
export ANDROID_HOME="$HOME/Library/Android/sdk"
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/29.0.14033849"  # 根据实际版本调整
export PATH="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin:$PATH"

# 应用配置
source ~/.zshrc
```

## 编译步骤

### 方法 1: 使用项目脚本 (推荐)

```bash
cd /Users/mac/Project/Dart/LighthouseApp/core

# 编译 ARM64 版本
make android-arm64

# 编译所有架构
make android-all  # arm64-v8a, armeabi-v7a, x86, x86_64
```

### 方法 2: 手动编译

#### 编译 ARM64 (arm64-v8a)

```bash
cd /Users/mac/Project/Dart/LighthouseApp/core

# 1. 初始化 Go 模块
go mod download
git submodule update --init --recursive

# 2. 设置交叉编译环境
export CGO_ENABLED=1
export GOOS=android
export GOARCH=arm64
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android29-clang"

# 3. 编译为共享库
go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o ../android/app/src/main/jniLibs/arm64-v8a/libclash.so \
  .

# 4. 验证编译结果
ls -lh ../android/app/src/main/jniLibs/arm64-v8a/libclash.so
nm -D ../android/app/src/main/jniLibs/arm64-v8a/libclash.so | grep quickStart
```

#### 编译 ARMv7 (armeabi-v7a)

```bash
export GOARCH=arm
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/armv7a-linux-androideabi29-clang"

go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o ../android/app/src/main/jniLibs/armeabi-v7a/libclash.so \
  .
```

#### 编译 x86_64

```bash
export GOARCH=amd64
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/x86_64-linux-android29-clang"

go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o ../android/app/src/main/jniLibs/x86_64/libclash.so \
  .
```

## 编译优化

### 减小文件体积

```bash
# 使用 -ldflags 优化
go build -buildmode=c-shared \
  -ldflags="-s -w -X 'github.com/metacubex/mihomo/constant.Version=1.0.0'" \
  -trimpath \
  -o libclash.so \
  .

# -s: 去除符号表
# -w: 去除 DWARF 调试信息
# -trimpath: 移除文件系统路径
```

### UPX 压缩 (可选)

```bash
# 安装 UPX
brew install upx

# 压缩 SO 文件 (可减少 30-50% 体积)
upx --best --lzma libclash.so

# ⚠️ 注意: UPX 压缩可能导致某些设备加载失败,仅在测试环境使用
```

## 常见问题

### 问题 1: `undefined reference to 'xxx'`

**原因:** NDK 版本不匹配或缺少依赖

**解决:**
```bash
# 检查 NDK 版本
ls $ANDROID_HOME/ndk/

# 使用推荐版本 (r25c / 25.2.9519653 或更高)
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/25.2.9519653"
```

### 问题 2: `clang: command not found`

**原因:** CC 环境变量路径错误

**解决:**
```bash
# macOS (Apple Silicon)
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-aarch64/bin/aarch64-linux-android29-clang"

# macOS (Intel)
export CC="$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/aarch64-linux-android29-clang"
```

### 问题 3: 编译后文件过大 (>50MB)

**原因:** 未启用优化参数

**解决:**
```bash
# 确保使用 -ldflags="-s -w"
go build -buildmode=c-shared \
  -ldflags="-s -w" \
  -trimpath \
  -o libclash.so \
  .

# 预期大小: 25-30MB (ARM64)
```

### 问题 4: `go: github.com/metacubex/mihomo: module not found`

**原因:** 子模块未初始化

**解决:**
```bash
cd core
git submodule update --init --recursive
go mod download
```

## 验证编译结果

### 1. 检查导出函数

```bash
nm -D libclash.so | grep -E "(quickStart|getAndroidVpnOptions|startTUN)"

# 预期输出:
# 0000000000e23960 T getAndroidVpnOptions
# 0000000000e237b0 T quickStart
# 0000000000e23820 T startTUN
```

### 2. 检查架构

```bash
file libclash.so

# ARM64 预期输出:
# libclash.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked
```

### 3. 测试加载

```bash
# 在 Android 设备上测试
adb push libclash.so /data/local/tmp/
adb shell "cd /data/local/tmp && LD_LIBRARY_PATH=. /system/bin/true"  # 测试加载
```

## 持续集成 (CI/CD)

### GitHub Actions 示例

```yaml
# .github/workflows/build-clash-core.yml
name: Build Clash Core

on:
  push:
    paths:
      - 'core/**'
  workflow_dispatch:

jobs:
  build-android:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        arch: [arm64, arm, amd64]

    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

      - uses: actions/setup-go@v4
        with:
          go-version: '1.20'

      - name: Setup Android NDK
        uses: nttld/setup-ndk@v1
        with:
          ndk-version: r25c

      - name: Build
        run: |
          cd core
          make android-${{ matrix.arch }}

      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: libclash-${{ matrix.arch }}
          path: android/app/src/main/jniLibs/**/libclash.so
```

## 更新核心版本

### 更新 Clash.Meta 子模块

```bash
cd core/Clash.Meta

# 更新到最新版本
git fetch origin
git checkout Alpha  # 或其他分支
git pull

cd ..
git add Clash.Meta
git commit -m "chore: update Clash.Meta to latest"

# 重新编译
make clean
make android-arm64
```

### 查看版本信息

```bash
# 查看当前 Clash.Meta 版本
cd core/Clash.Meta
git log -1 --oneline

# 查看依赖版本
cd ..
go list -m github.com/metacubex/mihomo
```

## 调试编译问题

### 启用详细日志

```bash
# 查看详细编译过程
go build -v -x -buildmode=c-shared -o libclash.so .

# -v: 显示正在编译的包
# -x: 显示执行的命令
```

### 检查依赖

```bash
# 列出所有依赖
go list -m all

# 检查特定依赖
go mod why github.com/metacubex/mihomo
```

## 性能优化

### 编译时优化

```bash
# 启用所有优化
go build -buildmode=c-shared \
  -ldflags="-s -w -extldflags=-Wl,-z,now" \
  -trimpath \
  -tags="with_gvisor,with_quic" \
  -o libclash.so \
  .
```

### Profile 引导优化 (PGO)

```bash
# 1. 生成性能剖析文件
go test -cpuprofile=cpu.prof ./...

# 2. 使用剖析文件编译
go build -buildmode=c-shared \
  -pgo=cpu.prof \
  -o libclash.so \
  .
```

## 相关资源

- [Android NDK 官方文档](https://developer.android.com/ndk)
- [Go 交叉编译指南](https://go.dev/doc/install/source#environment)
- [Clash Meta 编译指南](https://wiki.metacubex.one/dev/)