# 开发环境搭建 ## 系统要求 ### 硬件要求 - **处理器**：Apple Silicon (M1/M2/M3) 或 Intel Mac - **内存**：至少 8GB RAM（推荐 16GB） - **存储**：至少 20GB 可用空间 ### 软件要求 - **操作系统**：macOS 26.0+ - **Xcode**：16.0+ - **Swift**：6.0+ - **Go**：1.25.5+ - **Git**：2.40+ ## 安装步骤 ### 1. 安装 Xcode 从 App Store 安装 Xcode： ```bash # 安装 Xcode Command Line Tools xcode-select --install # 验证安装 xcodebuild -version ``` ### 2. 安装 Homebrew ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 验证安装 brew --version ``` ### 3. 安装 Go ```bash # 使用 Homebrew 安装 Go brew install go # 验证安装 go version ``` ### 4. 安装系统依赖 ```bash # 无需额外安装 # libusb-1.0 已在构建过程中自动处理 ``` ### 5. 克隆项目 ```bash # 克隆仓库 git clone https://github.com/wang93wei/SwiftMTP.git cd SwiftMTP # 初始化子模块（如果有） git submodule update --init --recursive ``` ### 6. 安装 Go 依赖 ```bash cd Native # 下载依赖 go mod download # 验证依赖 go mod verify ``` ### 7. 构建 Go 桥接层 ```bash # 使用构建脚本 cd .. ./Scripts/build_kalam.sh # 或手动构建 cd Native go build -o ../SwiftMTP/libkalam.dylib -buildmode=c-shared . ``` ### 8. 打开 Xcode 项目 ```bash # 打开 Xcode 项目 open SwiftMTP.xcodeproj ``` ## 项目配置 ### Xcode 配置 1. **选择 Scheme**： - 在 Xcode 顶部选择 `SwiftMTP` scheme - 选择 `My Mac` 作为运行目标 2. **配置签名**： - 选择项目 → Signing & Capabilities - 确保 "Automatically manage signing" 已勾选 - 选择正确的 Team 3. **禁用沙盒**： - 选择 Target → Info - 添加 `App Sandbox` capability 并设置为 `NO` - 或在 `Info.plist` 中移除 `App Sandbox` 键 ### Go 模块配置 **go.mod**： ```go module github.com/wang93wei/SwiftMTP go 1.25.5 require ( github.com/ganeshrvel/go-mtpfs v1.0.4 github.com/ganeshrvel/go-mtpx v0.0.0 github.com/ganeshrvel/usb v0.0.0 ) ``` ### Swift 配置 **Swift Language Version**： - 在 Xcode 项目设置中设置为 `Swift 6` **Swift Concurrency**： - 在 Build Settings 中设置： - `Swift Concurrency` = `Strict` - `Swift Concurrency Target` = `6.0` ## 开发工具 ### 推荐工具 - **Xcode**：IDE 和调试器 - **Visual Studio Code**：轻量级编辑器 - **SwiftLint**：代码规范检查 - **SwiftFormat**：代码格式化 ### 安装 SwiftLint ```bash # 使用 Homebrew 安装 brew install swiftlint # 验证安装 swiftlint version ``` ### 安装 SwiftFormat ```bash # 使用 Homebrew 安装 brew install swiftformat # 验证安装 swiftformat --version ``` ## 构建项目 ### Debug 构建 ```bash # 使用 Xcode 构建 xcodebuild -project SwiftMTP.xcodeproj \ -scheme SwiftMTP \ -configuration Debug \ build # 或使用脚本 ./Scripts/build_kalam.sh ``` ### Release 构建 ```bash # 使用 Xcode 构建 xcodebuild -project SwiftMTP.xcodeproj \ -scheme SwiftMTP \ -configuration Release \ build ``` ### 清理构建 ```bash # 清理 Xcode 构建 xcodebuild clean -project SwiftMTP.xcodeproj -scheme SwiftMTP # 清理 Go 构建 cd Native go clean -cache ``` ## 运行项目 ### 在 Xcode 中运行 1. 选择 `SwiftMTP` scheme 2. 选择 `My Mac` 作为运行目标 3. 点击 Run 按钮（⌘R） ### 使用命令行运行 ```bash # 构建 xcodebuild -project SwiftMTP.xcodeproj \ -scheme SwiftMTP \ -configuration Debug \ build # 运行 open build/Debug/SwiftMTP.app ``` ## 调试项目 ### Xcode 调试 1. **设置断点**：在代码行号处点击 2. **启动调试**：点击 Debug 按钮（⌘⌘D） 3. **查看变量**：使用 Variables View 4. **控制台输出**：使用 Console View ### 日志调试 ```swift // 使用 print print("Debug message") // 使用 os.log import os let logger = Logger(subsystem: "com.swiftmtp", category: "DeviceManager") logger.debug("Device found: \(device.name)") // 使用 NSLog NSLog("Debug message") ``` ### LLDB 命令 ```bash # 查看变量 po variableName # 查看所有变量 frame variable # 继续执行 continue # 单步执行 step next # 查看调用栈 bt ``` ## 测试项目 ### 运行所有测试 ```bash # 使用 Xcode xcodebuild test -project SwiftMTP.xcodeproj \ -scheme SwiftMTP \ -destination 'platform=macOS' # 使用脚本 ./Scripts/run_tests.sh ``` ### 运行特定测试 ```bash # 运行单个测试文件 xcodebuild test -project SwiftMTP.xcodeproj \ -scheme SwiftMTP \ -only-testing:SwiftMTPTests/DeviceManagerTests # 运行特定测试方法 xcodebuild test -project SwiftMTP.xcodeproj \ -scheme SwiftMTP \ -only-testing:SwiftMTPTests/DeviceManagerTests/testScanDevices ``` ### 生成代码覆盖率报告 ```bash # 生成覆盖率报告 xcodebuild test -project SwiftMTP.xcodeproj \ -scheme SwiftMTP \ -enableCodeCoverage YES \ -resultBundlePath TestResults.xcresult # 查看覆盖率 xcrun xccov view --report TestResults.xcresult ``` ## 代码规范 ### Swift 代码规范 遵循 [Swift API Design Guidelines](https://swift.org/documentation/api-design-guidelines/)： - 使用驼峰命名法 - 类型名使用大驼峰（PascalCase） - 变量和方法名使用小驼峰（camelCase） - 常量使用小驼峰或全大写 ```swift // ✅ 正确 class DeviceManager { let maxFileSize: UInt64 = 10 * 1024 * 1024 * 1024 func scanDevices() { } } // ❌ 错误 class device_manager { let MAX_FILE_SIZE: UInt64 = 10 * 1024 * 1024 * 1024 func Scan_Devices() { } } ``` ### Go 代码规范 遵循 [Effective Go](https://go.dev/doc/effective_go)： - 使用驼峰命名法 - 导出的名称使用大驼峰 - 私有的名称使用小驼峰 - 避免缩写 ```go // ✅ 正确 type DevicePoolEntry struct { Device *mtp.Device LastUsed time.Time } func GetDevice(id uint32) *Device { // ... } // ❌ 错误 type devicePoolEntry struct { device *mtp.Device lastUsed time.Time } func getDevice(id uint32) *Device { // ... } ``` ## Git 工作流 ### 分支策略 - `main`：主分支，稳定版本 - `develop`：开发分支 - `feature/*`：功能分支 - `bugfix/*`：修复分支 - `hotfix/*`：紧急修复分支 ### 提交规范 使用 [Conventional Commits](https://www.conventionalcommits.org/)： ``` ():