Hammerspoon项目开发与扩展编写指南

Hammerspoon项目开发与扩展编写指南

hammerspoon Staggeringly powerful macOS desktop automation with Lua 项目地址: https://gitcode.com/gh_mirrors/ha/hammerspoon

项目概述

Hammerspoon是一个强大的macOS自动化工具，它将系统级API通过Lua脚本语言暴露给用户。该项目主要由三部分组成：LuaSkin运行时框架、核心应用程序以及各种扩展模块。

项目构建机制

构建环境准备

构建Hammerspoon需要使用Xcode，但需要注意几个关键点：

1. 必须打开Hammerspoon.xcworkspace而非Hammerspoon.xcodeproj
2. 项目依赖多个Cocoapods，这些依赖关系在Podfile中定义
3. 在macOS Catalina之前的版本上需要安装Python 3

构建流程优化

为了提升本地开发效率，建议进行自签名构建：

1. 创建名为"Internal Code Signing"的自签名代码签名证书
2. 使用./scripts/rebuild.sh脚本进行快速重建

核心组件开发

核心应用与LuaSkin开发

虽然大多数开发集中在扩展模块，但核心组件的修改流程同样简单：

1. 获取项目代码
2. 使用最新版Xcode打开工作区
3. 进行修改并测试
4. 提交变更

扩展模块开发

扩展模块是Hammerspoon的核心功能所在，分为纯Lua扩展和混合Lua/Objective-C扩展两种类型。

开发规范

所有扩展API应遵循camelCase命名约定，这一要求仅针对暴露给Lua的接口，内部实现不受限制。

纯Lua扩展开发

纯Lua扩展通常用于提供辅助功能：

1. 在extensions目录下创建模块目录
2. 编写模块Lua文件，返回包含功能的table
3. 按照规范添加文档注释
4. 在Xcode中添加文件到构建阶段
5. 测试并提交

混合扩展开发

混合扩展用于暴露系统级API：

1. 创建模块目录和文件
   • Lua文件：加载Objective-C代码并提供Lua API
   • Objective-C文件：实现核心功能，尽可能使用LuaSkin
2. 配置Xcode构建
   • 复制现有扩展目标并重命名
   • 调整编译源和链接库
   • 添加目标依赖
3. 测试并提交

文档规范

完善的文档对项目维护至关重要，以下是文档注释规范：

常量文档

--- hs.foo.someConstant
--- Constant
--- 常量描述

变量文档

--- hs.foo.someVariable
--- Variable
--- 变量描述

函数文档

--- hs.foo.someFunction(bar[, baz]) -> string or nil
--- Function
--- 函数简要描述
---
--- Parameters:
---  * bar - 参数描述
---  * baz - 可选参数描述，默认值
---
--- Returns:
---  * 返回值描述
---
--- Notes:
---  * 注意事项1
---  * 注意事项2

方法文档

--- hs.foo:someMethod() -> bool
--- Method
--- 方法简要描述
---
--- Parameters:
---  * None
---
--- Returns:
---  * 返回值描述

测试规范

所有新扩展都应包含测试套件，修改现有扩展也应补充相应测试。

测试框架

使用XCTest框架，可以混合使用Lua和Objective-C编写测试：

1. 为每个扩展创建测试类(HSfoo.m)
2. 继承HSTestCase基类
3. 在setUp方法中加载测试Lua脚本
4. 编写testBar方法实现测试用例

测试辅助工具

测试初始化脚本提供了多种断言函数：

• assertIsEqual：验证值和类型
• assertTrue/assertFalse：验证布尔值
• assertIsString等：验证类型
• assertIsUserdataOfType：验证userdata类型

第三方扩展分发

虽然鼓励贡献到主项目，但也支持第三方扩展分发：

1. 采用init.lua/internal.so结构
2. 放置在用户目录的.hammerspoon下
3. 建议在社区wiki中登记扩展信息

通过遵循这些规范，开发者可以高效地为Hammerspoon贡献代码，无论是核心功能还是扩展模块，都能保持一致的代码质量和用户体验。

hammerspoon Staggeringly powerful macOS desktop automation with Lua 项目地址: https://gitcode.com/gh_mirrors/ha/hammerspoon