Home(主页)
用于为 iOS 和其他平台构建和部署软件的跨平台工具套件
这个 wiki 是官方文档。使用右侧的页面列表进行导航
Theos 最初是一个 iPhone-Framework,该项目旨在简化命令行中的代码构建,主要用于越狱的 iOS 设备。后来它经历了重大变化并成为了现在的 Theos:一个灵活的基于 Make 的构建系统,主要针对 iOS 越狱软件的开发,同时也支持对其他各种平台的构建。Theos 可以在 macOS、iOS、Linux、Windows(通过 Cygwin 或者 Windows Subsystem for Linux) 上运行和构建项目
2015 年,由于 Dustin Howett(达斯汀-豪威特)无法投入时间,该项目停滞不前。从那时起,该项目被 Theos Community(Theos 社区) 接手,社区为 Theos 添加了许多亟需的功能并修复了许多问题。曾经位于 DHowett/theos
的旧版 Theos 现在被永久保留在 legacy 分支上
原始 Theos 的文档可以在 iPhone Dev Wiki 和 theos-ref 上找到。但是请注意,并非所有上述文档都是最新的,并且可能无法反映 Theos 最近的更改
Installation(安装)
-
Officially supported platforms(官方支持的平台)
Theos 旨在运行在以下平台,并进行代码的构建工作:
以下说明中展示的所有命令均应以
user
用户身份运行,而不是以root
用户身份运行。同样地,Theos 也应该以普通用户的身份运行,而不是以根用户的身份运行- iOS:iOS 5 及更高的版本
- macOS:macOS Mavericks 10.9 及更高的版本
- Linux/WSL:Linux 内核 3.16 或者 Windows 10 build 14393 及更高的版本(WSL:Windows Subsystem for Linux)
- Cygwin:Windows 7 及更高的版本
其他平台(或者比上面列出的更旧的系统版本)可能可以工作,但请注意它们是不受技术支持的。Theos 现在可能可以在这些旧的系统版本上运行,但未来可能无法在这些旧的系统版本上运行。如果您认为我们应该正式支持此处未列出的平台,请联系我们
-
Updating(更新)
Theos 使用 滚动发布(rolling release) 模式,这意味着对 Git 存储库的最新提交是可用的最新版本的 Theos。有时,开发者应该更新 Theos。更新 Theos 可以通过以下方式完成:
$THEOS/bin/update-theos
如果开发者收到
no such file or directory
的错误消息,则开发者可能使用的是缺少此脚本的非常旧的 Theos 版本。作为另一种选择,切换到一个包含 Theos Makefile 的目录,然后运行:make update-theos
(以上的两条命令都做同样的事情)
如果您遇到了问题,则更新 Theos 是您应该做的第一件事情。如果您向别人寻求帮助,则可以更容易地找到这个问题
如果您在运行命令时看到以下内容:
make: *** No rule to make target 'update-theos'. Stop.
……那么您使用的是 legacy 版的 Theos。请阅读下一节
-
Switching from DHowett’s or rpetrich’s Theos(从 DHowett 或者 rpetrich 的旧版 Theos 转换)
请参阅:从旧版 Theos 升级
Installation iOS(iOS 平台上的安装)
本指南将帮助您在越狱的 iOS 设备上安装 Theos
平台:iOS
最低操作系统版本:5.0
支持的目标平台:iOS
以下说明中展示的所有命令均应以 user
用户身份运行,而不是以 root
用户身份运行。同样地,Theos 也应该以普通用户的身份运行,而不是以根用户的身份运行
-
安装以下前置条件:
Sam Bingner’s repository(一个 Cydia 源)
Theos Dependencies(BigBoss 源上的软件包,依赖于先前安装的
Sam Bingner’s repository
) -
设置
THEOS
环境变量:echo "export THEOS=~/theos" >> ~/.profile
要使此更改生效,您必须重新启动 shell。在任务切换器 taskswitcher 中杀死终端,然后重新打开终端并在您的 shell 上执行
echo $THEOS
以检查更改是否生效 -
将 Theos 克隆到您的设备:
git clone --recursive https://github.com/theos/theos.git $THEOS
-
获取 Toolchain:
Theos Dependencies 将安装 iOS Toolchain
-
获取 iOS SDK:
您可以从 我们的 SDK 存储库 中获取修补过的 SDK
curl -LO https://github.com/theos/sdks/archive/master.zip TMP=$(mktemp -d) unzip master.zip -d $TMP mv $TMP/sdks-master/*.sdk $THEOS/sdks rm -r master.zip $TMP
-
安装 Swift Toolchain(可选)
swift-toolchain
在 BigBoss 源中
请注意,编译 Swift 代码需要相当新的 SDK。建议您使用可以获取到的最新 SDK
Installation macOS(macOS 平台上的安装)
本指南将帮助您在 macOS 设备上安装 Theos
平台:macOS
最低操作系统版本:Mavericks 10.9
支持的目标平台:macOS、iOS、watchOS、tvOS、simulators
以下说明中展示的所有命令均应以 user
用户身份运行,而不是以 root
用户身份运行。同样地,Theos 也应该以普通用户的身份运行,而不是以根用户的身份运行
-
安装以下前置条件:
Homebrew(macOS 软件包管理工具)
Xcode (必须安装),命令行工具包不足以让 Theos 工作。Xcode 包含针对所有苹果平台的 Toolchain。需要 Xcode 5.0 或者更新的版本。虽然支持 Xcode 4.4,但是仅在为 ARMv6 构建时(第一和第二代 iPhone 与 iPod touch)
brew install ldid xz
-
设置
THEOS
环境变量:echo "export THEOS=~/theos" >> ~/.zprofile
如果您使用的是 macOS 10.14 或者更早的版本,请将
~/.zprofile
更改为~/.profile
。因为在 macOS 10.15 中,默认的 shell 已经从 bash 更改为 zsh。您可以通过运行echo $SHELL
来检查您使用的是哪一种 shell要使此更改生效,您必须重新启动 shell。打开一个新的 shell 界面并执行
echo $THEOS
以检查更改是否生效 -
将 Theos 克隆到您的设备:
git clone --recursive https://github.com/theos/theos.git $THEOS
-
获取 Toolchain:
Xcode 包含 Toolchain
-
获取 iOS SDK:
虽然 Xcode 始终提供最新的 iOS SDK,但是从 Xcode 7.3 开始,它不再包含您可以链接的私有 Framework。这在开发 Tweak 时,可能是一个问题。您可以从 我们的 SDK 存储库 中获取修补过的 SDK
curl -LO https://github.com/theos/sdks/archive/master.zip TMP=$(mktemp -d) unzip master.zip -d $TMP mv $TMP/sdks-master/*.sdk $THEOS/sdks rm -r master.zip $TMP
Installation Linux(Linux 平台上的安装)
本指南将帮助您在 Linux 机器上安装 Theos,可以通过 Windows Subsystem for Linux 或者 Google Cloud Shell 在 Windows 中安装 Linux
平台:Linux 或者 Windows 10
最低操作系统版本:Linux 内核 3.16 或者 Windows 10 build 14393
支持的目标平台:Linux,iOS
以下说明中展示的所有命令均应以 user
用户身份运行,而不是以 root
用户身份运行。同样地,Theos 也应该以普通用户的身份运行,而不是以根用户的身份运行
-
安装以下前置条件:
sudo apt-get install fakeroot git perl unzip build-essential libtinfo5
此外,在 WSL(Windows Subsystem for Linux)上:
sudo update-alternatives --set fakeroot /usr/bin/fakeroot-tcp
此外,在 Google Cloud Shell 上:
sudo apt install rsync
-
设置
THEOS
环境变量:echo "export THEOS=~/theos" >> ~/.profile
要使此更改生效,您必须重新启动 shell。打开一个新的 shell 界面并执行
echo $THEOS
以检查更改是否生效 -
将 Theos 克隆到您的设备:
git clone --recursive https://github.com/theos/theos.git $THEOS
-
获取 Toolchain:
没有对 Swift 的支持(较小的 Toolchain 体积):
curl -LO https://github.com/sbingner/llvm-project/releases/latest/download/linux-ios-arm64e-clang-toolchain.tar.lzma TMP=$(mktemp -d) tar -xvf linux-ios-arm64e-clang-toolchain.tar.lzma -C $TMP mkdir -p $THEOS/toolchain/linux/iphone mv $TMP/ios-arm64e-clang-toolchain/* $THEOS/toolchain/linux/iphone/ rm -r linux-ios-arm64e-clang-toolchain.tar.lzma $TMP
具有对 Swift 的支持(较大的 Toolchain 体积):
sudo apt install zstd curl -LO https://github.com/CRKatri/llvm-project/releases/download/swift-5.3.2-RELEASE/swift-5.3.2-RELEASE-ubuntu18.04.tar.zst TMP=$(mktemp -d) tar -xvf swift-5.3.2-RELEASE-ubuntu18.04.tar.zst -C $TMP mkdir -p $THEOS/toolchain/linux/iphone $THEOS/toolchain/swift mv $TMP/swift-5.3.2-RELEASE-ubuntu18.04/* $THEOS/toolchain/linux/iphone/ ln -s $THEOS/toolchain/linux/iphone $THEOS/toolchain/swift rm -r swift-5.3.2-RELEASE-ubuntu18.04.tar.zst $TMP
请注意,编译 Swift 代码需要相当新的 SDK。建议您使用可以获取到的最新 SDK
-
获取 iOS SDK:
您可以从 我们的 SDK 存储库 中获取修补过的 SDK
curl -LO https://github.com/theos/sdks/archive/master.zip TMP=$(mktemp -d) unzip master.zip -d $TMP mv $TMP/sdks-master/*.sdk $THEOS/sdks rm -r master.zip $TMP
Installation Windows(Windows 平台上的安装)
本指南将帮助您通过 Cygwin 在 Windows(7、8、8.1)的机器上安装 Theos
如果可能,请考虑使用 Windows Subsystem for Linux。Cygwin 虽然可以工作,但是非常有限
平台 :Windows
最低操作系统版本:XP
支持的目标平台:IOS
以下说明中展示的所有命令均应以 user
用户身份运行,而不是以 root
用户身份运行。同样地,Theos 也应该以普通用户的身份运行,而不是以根用户的身份运行
-
安装以下前置条件:
Cygwin
git(under Devel)
make(under Devel)
ca-certificates(under Net)
openssh(under Net)
perl(under Perl)
python(under Python) -
设置
THEOS
环境变量:echo "export THEOS=~/theos" >> ~/.profile
要使此更改生效,您必须重新启动 shell。打开一个新的 shell 界面并执行
echo $THEOS
以检查更改是否生效 -
将 Theos 克隆到您的设备:
git clone --recursive https://github.com/theos/theos.git $THEOS
-
获取 Toolchain:
在 32 位系统上:
git clone git://github.com/coolstar/iOSToolchain4Win.git $THEOS/toolchain/windows/iphone
在 64 位系统上:
git clone -b x86_64 git://github.com/coolstar/iOSToolchain4Win.git $THEOS/toolchain/windows/iphone
-
获取 iOS SDK:
您可以从 我们的 SDK 存储库 中获取修补过的 SDK
curl -LO https://github.com/theos/sdks/archive/master.zip TMP=$(mktemp -d) unzip master.zip -d $TMP mv $TMP/sdks-master/*.sdk $THEOS/sdks rm -r master.zip $TMP
Upgrading from legacy Theos(从 legacy 版的 Theos 升级)
目前状态下的 Theos 是 Dustin Howett 所做工作的延续,其中包括 Ryan Petrich 的 fork 分支。您可以轻松地从这两个最常用的 Theos 变体之一升级到目前状态下的 Theos
如果您的 Theos 副本是使用 Git 下载的,则请继续阅读。如果您的 Theos 副本是作为 ZIP 文件从 GitHub 或者 DHowett 的子版本下载的,则您需要备份您更改的所有内容、删除 Theos 目录,然后 从头开始安装 Theos
只需更改远程仓库的地址并进行拉取:
$ git remote set-url origin https://github.com/theos/theos.git
$ git pull origin master
然后指示 Git 像这样克隆子模块:
$ git submodule update --init --recursive
更改 Git 的仓库地址不是严格要求的,因为 DHowett/theos
已经重定向到 theos/theos
。但是,我们建议开发者显式地更改 Git 仓库的地址以避免混淆
-
Things to be aware of(需要注意的事项)
自 legacy Theos 以来所做的更改可能会让您措手不及。以下是我们认为您应该需要注意的一些事项:
-
Theos 严重依赖 Git。要始终按照 安装说明 安装 Theos;不要将其下载为 ZIP
-
theos
符号链接不再由 NIC 在新项目中创建。此符号链接的目的地址可能因计算机而异,因为 Theos 没有对其必须存储的位置强加要求。此符号链接也经常无意中被用于源代码控制(即 Git)。由于强烈建议在您的环境变量中设置$THEOS
,因此我们选择切换新的 Makefile 来使用$THEOS
,而不是使用符号链接。建议您在现有的项目中更改此设置。请参阅此 FAQ 条目 -
与您的环境而不是项目相关的配置应该存放在
~/.theosrc
中。如果您设置了特定于您自己的配置的变量,例如:Xcode 或者 SDK 的位置、设备 IP 等,您应该避免将它放在您的项目的 Makefile 中,因为这些类型的东西可能会因用户而异。将这些移动到~/.theosrc
,一个在 Theos 的common.mk
的早期阶段被读取和执行的 Makefile -
(项目中)构建的包已移动到一个名为
packages
的目录。这里的目的是减少项目根目录的混乱,并将构建输出从项目源中分离出来 -
(项目中的)
obj
目录已被移动到.theos
目录内部。同样地,这样做是为了让目录结构更加清晰。您可能需要在操作系统或者文件管理器中启用显示隐藏文件,才能找到隐藏目录.theos
-
不需要在(运行 iOS 9 的 64 位设备上的 32 位进程中)应用(Tweak 运行所需的链接器标志)。Theos 已经为您应用了它
-
为了您开发的方便,Theos 附带了一些内置的头文件和库。这些头文件和库被放置在
vendor
目录中并作为 Git Submodules 进行维护。特别的,这些库是 Xcode 7.0 支持的.tbd
纯文本格式。如果您有自己的头文件和库,请将它们放在Theos
根目录下的include
和lib
目录中,而不是vendor
目录中。您可以使用相同的文件路径和名称覆盖vendor
目录中的文件 -
Theos 不再依赖于
dpkg-deb
。在 lzma 压缩被dpkg-deb
弃用后,dm.pl 成为 Theos 创建 deb 的主要手段,以允许继续使用 lzma 压缩。此外,dm.pl
消除了 Theos 对dpkg
的依赖,从而为缺少dpkg
的平台(例如 Cygwin)提供更好的支持 -
当链接到 iOS 7.0 或者更新版本的 SDK 时,Theos 默认为
ARMv7
和ARM64
进行构建。如果将来需要更改默认支持的 CPU 架构,则 Theos 将相应地更新默认值。除非有特殊原因,否则不应在 Makefile 中进行$ARCHS
的设置 -
$THEOS_DEVICE_PORT
不再需要设置。如果您使用 SSH host alias,则将使用您在 SSH 配置文件中指定的端口。如果 SSH 配置文件中未设置端口,或者主机名不是别名,则将使用端口 22 -
不再支持 GCC 编译器。GCC 在 Xcode 4.2 中被删除,并在此之前的一段时间内不鼓励再使用它。在 iOS 上,非常旧的 iphone-gcc 包已被新的 LLVM/Clang Toolchain 所取代。如果您使用了 Clang 不喜欢的代码,则必须将其移植到 Clang 或者坚持使用 legacy 版的 Theos
-
如果您使用 iOS 8.3 或者更新版本的 SDK,则启用 Clang 的 modules 功能。这解决了通常依赖系统编译器使用的一些限制并提高了性能(模块以优化的文件格式缓存)。请注意,您可能会遇到一些限制
-
Makedeps
默认是禁用的。由于Makedeps
的错误输出可能会令人困惑,并且大多数项目不使用此功能,因此默认情况下已将其更改为禁用。要启用Makedeps
,请设置USE_MAKEDEPS = 1
如果您遇到应该在此处列出的内容,请编辑页面并添加它!
除了这些不应该影响大多数项目的更改之外,我们希望项目能够继续使用最新的 Theos 进行构建,而无需进行任何更改。如果您发现了奇怪的事情,请告诉我们!
-
Features(特性)
以下是自 Dustin Howett 的 original Theos 以来实现的功能列表。所述功能按其实现日期以升序排列(最新添加的功能,排在最底部)
(待做:这些功能应该被正确地文档化记录,并删除此文件)
-
回滚或者最新的重排序头文件可以放置在
include/_fallback
目录中;这可以用于为缺失的 SDK 头文件提供备用替换(作者:rpetrich) -
make update-theos
,可以预见,将 Theos 更新到最新的提交(作者:rpetrich) -
make package FINALPACKAGE=1
将优化 Assets(在 PNG 图像上运行 pincrush,将 plists 文件转换为二进制格式)并生成一个具有干净版本号的包(例如:没有内部版本号)。推荐在构建您即将发布的包时使用(作者:rpetrich/kirb) -
INSTALL_TARGET_PROCESSES = Preferences MobileMail
是杀死进程的快捷方式(以前的TWEAK_TARGET_PROCESS
)(作者:rpetrich) -
与 rpetrich 的 fork 版本不同,生成器
generator
由internal
(直接使用 Objective-C 运行时函数)被改回MobileSubstrate
(使用 MobileSubstrate 对运行时函数的包装以确保未来的兼容性) -
make do
是make package install
的快捷方式(作者:rpetrich) -
每个 CPU 架构都是单独编译的,而不是一次编译所有 CPU 架构。这避免了 Theos 原始设计中的一些问题(作者:rpetrich)
-
不同的 SDK 可用于不同的 CPU 架构。例如,可以使用 Xcode 4.4 进行
armv6
的编译,同时使用较新的 Xcode 进行armv7
/arm64
的编译(作者:rpetrich) -
项目中所有生成的文件都存储在
.theos
目录中,而不是存储在项目根目录下的许多不同目录中(作者:rpetrich) -
make clean-packages
删除非最终的包(作者:rpetrich) -
让
dpkg-deb
使用lzma
压缩,因为目前的dpkg-deb
格式(使用xz
压缩)不受Telesphoreo
旧版的dpkg
所支持(作者:kirb) -
项目中的包被输出到名为
packages
的子目录中(作者:kirb) -
使用 hbang/headers 作为子模块(作者:kirb)
-
支持 iOS 7 模拟器(作者:kirb)
-
添加
%property
指令,以允许在被 hook 的类上创建属性(作者:eswick) -
添加
File.m_CFLAGS
,用于支持在一个特定文件上有编译器标志(作者:rpetrich) -
在前缀头文件中提供
IS_IPAD
和IN_SPRINGBOARD
宏(作者:kirb) -
当目标平台是 macOS 时,导入
Cocoa
和AppKit
(作者:kirb) -
当使用 iOS SDK 7.0 或者更高版本,并部署到 iOS 5 或者更高版本时,Theos 默认为
armv7
和arm64
进行构建(作者:rpetrich/kirb) -
添加
simbltweak.mk
以帮助构建 macOS 的 SIMBL Tweak(作者:kirb) -
添加 Modern App 和 Preference Bundle 模板(作者:kirb)
-
添加
%dtor { ... }
指令以在进程析构时运行代码(作者:uroboro) -
改进了找不到 SDK 时的错误处理(作者:uroboro)
-
添加
%hookf
指令以编写 hook 函数,示例(作者:uroboro) -
支持构建 rpm 包(作者:rpetrich)
-
添加
STRIP=0
,用于在版本发布时不进行 strip(作者:rpetrich) -
添加了
libsubstrate.dylib
的 stub 二进制,因此您无需自己获取(作者:kirb) -
修复了缺少允许 Theos 在 arm64 上工作的符号链接的问题(作者:kirb)
-
支持 Swift 的编译和链接。不完整,因为不确定是否允许通过 Cydia 分发 Swift 库(作者:kirb)
-
弃用
NSLog
,而支持更详细的日志宏HBLogDebug
、HBLogInfo
、HBLogWarn
、HBLogError
(作者:kirb) -
使调试构建成为默认设置。使用
make DEBUG=0
、FOR_RELEASE=1
、FINALPACKAGE=1
无需调试即可构建(作者:kirb) -
使用 iOS SDK 6.0 时将默认部署目标提升到 iOS 4.3,使用 iOS SDK 7.0 时将默认部署目标提升到 iOS 5.0(作者:kirb)
-
支持在 Windows 上为 iOS 构建(作者:coolstar)
-
Theos 符号链接不再在项目中创建,取而代之的是使用环境变量
$THEOS
(作者:kirb) -
instance_USE_SUBSTRATE = 0
可用于将 Tweak 生成器切换到internal
(直接使用 Objective-C 运行时函数),而不是使用MobileSubstrate
(使用 MobileSubstrate 对运行时函数的包装以确保未来的兼容性)(作者:kirb) -
可以在
~/.theosrc
中(为 Makefile 文件)设置默认规则、变量等(作者:kirb) -
make show
用于打开操作系统的文件管理器并高亮显示最新的包(作者:kirb) -
将一个
THEOS_INSTANCE_NAME
常量传递给编译器,因此当前项目的名称可以在代码中使用(作者:kirb) -
PREINSTALL_TARGET_PROCESSES
和INSTALL_TARGET_PROCESSES
可以分别设置在包安装前后要杀死的进程列表(作者:rpetrich) -
instance_LIBRARY_EXTENSION
可以在构建 Library 或者 Tweak 时设置自定义文件的扩展名。如果设置为-
,则没有扩展名(作者:kirb) -
输出信息是彩色的,因此一目了然更容易阅读(作者:kirb)
-
instance_WEAK_FRAMEWORKS
和instance_WEAK_LIBRARIES
允许您对 Framework 或者 Library 进行 弱链接 -
启用 clang modules。请注意,在 macOS 上构建时,C++ 模块仅在 iOS 8.4 和 macOS 10.10 或者更高版本中启用(作者:kirb)
-
允许
%ctor
和%dtor
中使用参数int argc, char **argv, char **envp
(作者:uroboro) -
第三方框架可以放在
$THEOS/lib
目录里面,用于与instance_EXTRA_FRAMEWORKS
一起使用(作者:kirb) -
在使用不支持 nullability 关键字的旧版 clang 构建时,为
nullability
关键字添加向后兼容性(作者:kirb) -
现在为 iOS 模拟器构建时默认禁用链接 Substrate,允许链接 macOS 二进制文件,并在为 iOS 8.0 或者更高版本构建时默认仅构建 x86_64(而不是 i386 和 x86_64)(作者:kirb)
-
集成了 Tweak 在 iPhone 6s 上的 32 位进程中工作所需的修复程序(作者:saurik)
-
添加
make troubleshoot
,用于获取故障排除信息的快速链接并将 make 输出上传到 Ghostbin 以进行共享(作者:kirb) -
添加了对 watchOS 和 tvOS 构建的支持(作者:kirb)
NIC
NIC 全称叫 New Instance Creator(也叫 Nicolas!)。它提供了一种基于模板创建项目(即 Instance)的方法。Theos 附带了一些有用的模板,而其他的模板也可以从社区中的各种开发者那里获得
另请参阅 iPhone Dev Wiki: NIC
-
Usage(用法)
最常见的是,NIC 以交互方式使用,如下所示:
~$ $THEOS/bin/nic.pl NIC 2.0 - New Instance Creator ------------------------------ [1.] iphone/activator_event [2.] iphone/activator_listener [3.] iphone/application_modern [4.] iphone/application_swift [5.] iphone/control_center_module-11up [6.] iphone/cydget [7.] iphone/flipswitch_switch [8.] iphone/framework [9.] iphone/library [10.] iphone/notification_center_widget [11.] iphone/notification_center_widget-7up [12.] iphone/preference_bundle_modern [13.] iphone/theme [14.] iphone/tool [15.] iphone/tool_swift [16.] iphone/tweak [17.] iphone/tweak_with_simple_preferences [18.] iphone/xpc_service Choose a Template (required): 16 Project Name (required): Example Package Name [com.yourcompany.example]: dev.theos.example Authour/Maintainer Name [Craig Federighi]: Craig Federighi <notfederighi@theos.dev> [iphone/tweak] MobileSubstrate Bundle filter [com.apple.springboard]: [iphone/tweak] List of applications to terminate upon installation (space-separated, '-' for none) [SpringBoard]: Instantiating iphone/tweak in example/... Done. ~$ cd example ~/example$ ls Example.plist Makefile Tweak.xm control
如果方括号
[]
中显示了默认值,您无需输入值,只需按回车键,将使用默认值。强烈建议作者名称字段(Authour/Maintainer Name
)的值的格式为:Your Name <yourself@example.com>
,因为这将使用户可以轻松地就错误和其他问题与您联系在几乎所有情况下,您都可以在新项目的目录中输入
make
命令,新项目将成功构建(假设 Theos 设置正确)。所生成的二进制文件很可能不会做任何事情 —— 这是完全由您决定的有趣的部分!支持以下命令行参数。请注意,提供参数并不能保证 NIC 不会提示输入额外信息
-t
--template
字符串
。要使用的模板名称,如模板选择列表中所示。一次只能使用-t
--template
字符串
和--nic
字符串
其中的一个--nic
字符串
。要使用的.nic.tar
或者.nic
模板的路径。一次只能使用-t
--template
字符串
和--nic
字符串
其中的一个-n
--name
字符串
。要使用的项目名称-p
--packagename
字符串
。要使用的包标识符-u
--user
字符串
。要使用的作者名称
-
Included templates(包含的模板)
activator_event
:一个 Activator 的 事件activator_listener
:一个 Activator 的 监听器application_modern
:一个标准的 iOS 应用程序(供非沙盒越狱使用)application_swift
:一个标准的,基于 Swift 的 iOS 应用程序(供非沙盒越狱使用)control_center_module-11up
:一个通过 CCSupport 部署的 iOS 11+ 自定义控制中心模块cydget
:一个 Cydget 锁屏插件flipswitch_switch
:一个用于 Flipswitch 的开关framework
:一个供其他开发者使用的框架library
:一个可链接的库(例如/usr/lib/libblah.dylib
)notification_center_widget
:一个用于 iOS 5 – 6 今日通知中心的小部件(widget
)notification_center_widget-7up
:一个用于 iOS 7 – 9 今日通知中心的小部件(widget
)preference_bundle_modern
:一个基于 PreferenceLoader 的 preference bundle 子项目theme
:一种使用 Theos 的打包功能,轻松地将主题打包成.deb
的方法tool
:一个命令行工具(例如/usr/bin/blah
)tool_swift
:一个基于 Swift 的命令行工具(例如/usr/bin/blah
)tweak
:一个基于 Cydia Substrate 的 Tweaktweak_with_simple_preferences
:一个基于 Cydia Substrate 的 Tweak,带有基本的 preference bundlexpc_service
:基于 C 的 XPC 服务(XPC 是 macOS 下的一种进程间通讯技术,它实现了权限隔离,使得沙盒机制更加完备)
这只是 Theos 附带的模板列表,Theos 的功能远比您在上面的列表中能找到的要多得多。而且这些模板只能作为在不需要处理各种模板文件的前提下,开发越狱软件的起点
-
.nicrc
NIC 从
~/.nicrc
文件中读取配置数据。~/.nicrc
文件使用简单的键值对格式,key = "value"
。"value"
必须用引号" "
括起来,即使它是一个数字Instance Metadata(项目元数据)
-
package_prefix
字符串
。默认情况下用于反向 DNS 包标识符的前缀。默认为com.yourcompany
。例如:设置package_prefix = "ws.hbang"
,然后创建一个名为Example Instance
的新项目,将使默认包标识符变成ws.hbang.exampleinstance
-
skip_package_name
布尔值
。是提示输入包标识符,还是始终使用 NIC 生成的包标识符。如果您使用skip_package_name
布尔值
,则您很可能也想设置package_prefix
字符串
。默认为值为0
-
username
字符串
。用作新项目的author/maintainer
字段的值。设置此键值对将导致 NIC 跳过询问作者姓名的步骤。建议作者姓名中包含用尖括号<>
括起来的电子邮件地址。默认值为当前登录用户的名称。例子:username = "HASHBANG Productions <support@hbang.ws>"
Theos Reference(Theos 引用)
-
link_theos
布尔值
。是使用指向 Theos 位置的 Theos 符号链接(theos symlink
),还是依赖于 Theos 的环境变量($THEOS
)。默认值为0
。这与原始的 Theos 不同,原始的 Theos 的默认值为1
。如果使用默认值0
是不可取的,则您可以将其值重新设置为1
-
ignore_parent_theos
布尔值
。当link_theos
设置为1
,如果从父项目中创建子项目,则子项目使用父项目的符号链接目标地址(theos symlink
)。如果ignore_parent_theos
设置为0
,则子项目将使用 Theos 的环境变量($THEOS
)。默认值为0
-
-
Building templates(创建模板)
模板采用
.nic.tar
格式,一个标准的tar
存档,存档内部的布局可被 NIC 识别Theos 附带了与 NIC 一起使用的额外脚本:
nicify.pl
和denicify.pl
,它们分别用于创建和提取.nic.tar
文件# 提取存储在 tweak.nic.tar 存档中的模板文件到 tweak 目录 ~$ $THEOS/bin/denicify.pl $THEOS/templates/ios/theos/tweak.nic.tar tweak # 查看被提取到 tweak 目录中的模板文件 ~$ ls tweak/ @@PROJECTNAME@@.plist Makefile Tweak.xm control pre.NIC theos # 修改 tweak 目录中的模板文件 ... ... # 将 tweak 目录中的模板文件打包成 iphone_tweak.nic.tar 存档 ~$ $THEOS/bin/nicify.pl tweak/ [warning] Using legacy pre.NIC as ./NIC/control. [info] 6 entries. [info] 1 prompt. [info] 0 constraints. [info] Archived template "iphone/tweak" to iphone_tweak.nic.tar. # 查看打包好的 iphone_tweak.nic.tar 存档 ~$ ls *.nic.tar iphone_tweak.nic.tar
.nic.tar
文件的前身是.nic
文件,.nic
文件是一个纯文本文件。.nic
文件已经升级为当前的基于.tar
的格式,以实现更高的保真度,例如:保留文件权限 和 包含二进制文件(待做:应该在这里讨论模板的语法。不幸的是,DHowett 关于 NIC 的文档已经 消失,并且没有存档在 Wayback Machine 上。最好的替代方案就是对现有模板使用
denicify.pl
进行提取,然后看看它们是如何工作的)
Swift
Theos 能够编译 Swift 文件,并支持将它们与用其他语言(如 Objective-C)编写的文件结合使用。macOS、iOS 和 Linux 都支持这些功能。关于在 iOS 和 Linux 上安装 Swift Toolchain 的说明可以在它们各自的安装 wiki 页面上找到
-
Swift Runtime(Swift 运行时)
为了运行使用 Theos 构建的 Swift 二进制文件,您必须在 iOS 设备中安装 Swift 运行时。目前,Swift 运行时可以在 BigBoss 上的
org.swift.libswift
包(Swift 5+)或者com.modmyi.libswift4
包(Swift 4)下找到。建议您为libswift
依赖项在控制文件control
中添加Depends: ${LIBSWIFT}
,因为这将根据您的 Swift 版本自动选择正确的包 -
Interoperability with Objective-C(与 Objective-C 的互操作性)
-
Swift to Objective-C(Swift 到 Objective-C)
为了在 Objective-C 中使用 Swift 类,您必须通过在 Objective-C 文件中添加
#import <[instance]-Swift.h>
来导入自动生成的 swiftmodule header。您希望暴露给 Objective-C 的 Swift 声明必须用public
或者open
修饰符标记 -
Objective-C to Swift(Objective-C 到 Swift)
在项目目录中创建一个名为
<instance>-Bridging-Header.h
的文件,并将您希望暴露给 Swift 的 Objective-C 头文件导入其中。此头文件将会被自动导入到您创建的任何 Swift 文件中
-
-
Variables(变量)
<instance>_SWIFTFLAGS
或者<file>_SWIFTFLAGS
字符串
。默认值:空。为所有文件或者特定文件(分别)传递给 Swift 编译器的自定义标志<instance>_SWIFT_BRIDGING_HEADER
文件名
。默认值:<instance>-Bridging-Header.h
。在编译期间要导入到所有 Swift 文件中的 Objective-C bridging header 的路径。有关更多信息,请参阅 Objective-C to Swift Interoperability -
Tweaks
因为(Swift 和 Objective-C)ABI 之间的差异,以及 Logos 预处理器仅支持 Objective-C 的事实,所以目前无法在 Swift 中或者为 Swift 编写 Tweak。然而,很有可能在未来有办法制作 Swift Tweak,因为现在 Swift 是 ABI 稳定的
Technical(技术实现)
Structure(目录结构)
关于 Theos 内部目录结构的各部分的信息:
-
bin/
:包含 Theos 内部使用和用户外部使用的各种脚本 -
include/
:提供给您放置您自己的头文件 -
lib/
:提供给您放置您自己的库(Library)和框架(Framework) -
makefiles/
:构成了 Theos 本身的大部分内容-
install/
:关于在不同的平台上安装软件包的规则。这些命令将在安装和卸载软件包时执行 -
instance/
:在构建单个实例(项目)时,包含在 sub-make 中的 Makefile。这包括对源代码的编译 -
master/
:包含在master-make
中的 Makefile -
package/
:关于为各种打包格式构建软件包的规则。这些命令将在构建软件包时执行 -
platform/
:根据当前操作系统平台进行 Makefile。这些都为平台设置了适当的 Theos 环境 -
targets/
:根据当前操作系统平台和目标操作系统平台进行 Makefile。这些都为平台设置了适合构建的 Theos 环境
-
-
mod/
:提供给您放置模块(module)。Theos 会自动包含来自此目录的各种文件 -
sdks/
:提供给您放置 SDK -
templates/
:提供给您放置您自己的 NIC 模板 -
toolchain/
:提供给您放置 Toolchain。如 Installation 中所述 -
vendor/
:Theos 包含的子模块组件-
dm.pl/
:用于构建deb
包的 脚本文件,无需dpkg-deb
-
include/
:对大多数项目来说,可能有用也可能没有用的,内置头文件(Built-in headers) -
lib/
:对大多数项目来说,可能有用也可能没有用的,内置库(Built-in library) -
logos/
:Logos 的文件 -
nic/
:NIC 的文件 -
templates/
:可用于使用 NIC 搭建新项目的 内置模板(Built-in templates)
-
-
Prefix.pch
:导入到所有基于 C 语言的编译过程中的前缀头文件(prefix header
)。为旧(legacy)项目提供宏和框架导入
Help(帮助)
-
Places you can ask for help(您可以寻求帮助的地方)
-
首先在 iPhone Dev Wiki 上查看 Theos/Troubleshooting – 此处列出了常见的问题
-
加入我们的 Discord 并在那里提出您的问题
-
在 /r/jailbreakdevelopers 上发布问题
-
使用
theos
标签在 Stack Overflow 上发布问题
如果您认为您在 Theos 中发现了 bug,请提交 issue。请确保您实际报告的是 bug,而不是您系统、您项目配置、您代码中的错误。如果您不确定,请使用上面列出的地址之一进行询问
-
-
Advice(建议)
首先,确保您知道如何编程。一般来说,如果您问的是基本的编程问题,则上面列出的帮助地址会为您提供编程教程。尝试在网络上搜索 iOS 或者 Android 应用程序开发教程,或者购买一本书。它们将从一个想法开始,并指导您编写应用程序。请记住,您没有义务发布您在最初学习编程时制作的任何应用程序。只需将其当做用于学习的练习即可。如果您无法使用 Mac 电脑,则 Android 开发同样是 iOS 开发的一个很好的替代方案 — Android Studio 可运行在 Windows、Linux 和 macOS 上 — 并将帮助您学习许多类似的概念
在提出问题时,请提供尽可能多的信息。提供太多信息总比提供很少信息而最终得不到任何答案要好。仅提供您的代码不足以让其他人了解问题所在
确保您的问题不是 XY problem:这意味着您不是询问您的问题,而是询问您问题的具体解决方案。这使得回答您的问题变得更加困难,并且其他人可能会要求您更详细地解释您的问题。有关更详细的说明,请参阅该链接
准备好接受批评。如果您采取了错误的方式,有经验的程序员可能会说一些让您沮丧的话。请记住,他们提供的批评是为了帮助您成为更好的程序员。虽然世上没有十全十美的事情,但是您可以通过听取曾经处于您位置上的人的建议来变得更完美
共享代码片段时,通常最好将其发布到代码粘贴网站。我们推荐使用 Ghostbin,但是任何类似的网站都可以
-
在 Stack Overflow 和 Reddit 上,您可以将您的代码直接粘贴到正文中,然后选中它并单击工具栏上的
Code
,以确保其格式正确 -
在 GitHub 和 Discord 上,您可以将代码用三个反引号(
…
)包装起来,以确保其格式正确
-
-
make troubleshoot(进行故障排除)
您可以在项目目录中运行
make troubleshoot
以将一些诊断信息上传到 Ghostbin,并将链接复制到剪贴板。如果ghost
未安装,则您可以通过执行以下操作来安装:$ curl https://ghostbin.co/ghost.sh -o /usr/local/bin/ghost $ chmod +x /usr/local/bin/ghost
故障排除命令将执行
make clean all messages=yes
FAQ(常见问题解答)
-
All of my package versions contain +debug now! How do I stop this?(我所有的软件包版本号现在都包含 +debug!我该如何阻止?)
默认情况下,Theos 倾向于使用调试版本,而不是使用发布版本。调试版本为调试器提供更多信息,允许使用
HBLogDebug()
进行调试日志输出,并提供彩色的系统日志(使您的日志更容易在其他消息的海洋中被发现)要禁用调试模式,请将
DEBUG=0
作为命令行的一部分传递给make
。当您使用FINALPACKAGE=1
进行发布版本的构建时,调试也将被禁用(并且构建版本号也会被删除,以让您的版本号更加清晰) -
Where’s the theos symlink?(符号链接 theos symlink 在哪里?)
由于一些原因,Theos 默认选择停止使用此符号链接。首先,标准 Theos 在项目的根目录中丢弃了一些嘈杂的文件。这个分支更喜欢有尽可能少的项目根目录的结构(您可能已经注意到一些目录和文件现在隐藏在
.theos
目录中)。其次,Theos 的安装位置,在不同的开发人员之间甚至在同一个开发人员的不同设备之间,可能会有很大的不同,因为 Theos 可以被安装在任何地方。最后,很容易在无意中将这个符号链接提交到源代码控制,或者不知道该符号链接不应该被提交到源代码控制当然,这确实意味着您必须在您的环境中设置和导出
$THEOS
变量。在您的 shell 配置文件或者环境脚本(例如~/.bash_profile
、~/.zshrc
)中执行此操作以确保$THEOS
变量始终被设置,之后您不必再担心安装位置的问题。它可能看起来像以下这样:export THEOS = /usr/local/theos
如果在您的环境中设置和导出
$THEOS
变量是不可取的,则您可以告诉 NIC 恢复theos
符号链接:$ echo 'link_theos = "1"' >> ~/.nicrc
有关
.nicrc
的更多详细信息,请参阅此处 -
How do I use Swift in my projects?(如何在我的项目中使用 Swift?)
此信息已移至 Swift 页面
Parallel Building(并行构建 / 并行编译)
为了获得最佳结果,Theos 建议您使用最新版本的 GNU Make。不幸的是,Xcode Toolchain 不包含最新版本的 Make。事实上,Xcode Toolchain 包括的是 2006 年的 Make 3.81
!
尽管 Theos 的维护者尽最大的努力支持 Make 3.81
,但是他们所能做的事情有一定的限制。这些限制之一就是使用并行构建。并行构建是指像 Make 这样的构建工具划分其工作,以充分利用 CPU 的所有逻辑核心(线程)的方式。并行构建是加快构建速度的一种重要方式,尤其是对于大型的项目
Theos 输出的以下通知可能会将您引导到此处:
==> Notice: Build may be slow as Theos isn’t using all available CPU cores on this computer. Consider upgrading GNU Make:https://github.com/theos/theos/wiki/Parallel-Building
==> 注意:构建速度可能会很慢,因为 Theos 没有使用这台计算机上所有可用的 CPU 核心。考虑升级 GNU Make:https : //github.com/theos/theos/wiki/Parallel-Building
…在这种情况下,您使用的是 4.0 之前的 Make 版本。为了保持兼容性,Theos 不会激活其并行构建的支持,因为只会使用 CPU 的一个逻辑核心,所以会导致构建速度变慢
这些说明将帮助您在 macOS 上安装最新版本的 GNU Make。没有其他的现代操作系统会出现这种情况,因为 Make 4.0 于 2013 年发布。如果您在任何其他的操作系统(如 Linux)上看到此通知,您应该考虑升级整个操作系统
这些说明假设您使用 Homebrew 并按照 installation instructions 中的描述安装了 Theos
-
使用 Homebrew 安装 GNU Make:
brew install make
-
设置您的环境,使(上面安装的新版本的 Make)优先于(苹果提供的旧版本的 Make)。使用以下命令:
echo PATH=\"$(brew --prefix make)/libexec/gnubin:\$PATH\" >> ~/.zprofile
对于早于 macOS 10.15 Catalina 的版本,默认 shell 是 bash 而不是 zsh。因此,您需要在上面的命令中使用
~/.bash_profile
而不是~/.zprofile
-
为了使此更改生效,您必须重新启动 shell。打开一个新的 shell 界面并执行
make
。现在,上述的通知应该不会再出现,您应该会发现编译速度明显更快了!
如果您不想执行这些步骤,您可以通过使用以下方法永久忽略此通知:
echo 'THEOS_IGNORE_PARALLEL_BUILDING_NOTICE = yes' >> ~/.theosrc
arm64e Deployment(arm64e 的部署)
在 iOS 12 中,苹果推出了一种他们称之为 arm64e 的新架构。arm64e 实现了 armv8.3 架构,并由 Apple A12 和更新的处理器支持。特别地,arm64e 这种架构以实现指针身份认证(pointer authentication)而闻名
因为此架构目前处于不断变化中,并且被苹果视为私有架构,所以不建议使用此架构。但是,为了将代码注入到使用 arm64e 架构所构建的 iOS 平台的二进制文件中,Theos 需要为此架构提供代码构建功能。由于指针身份认证(pointer authentication)的性质,未实现与 arm64(即 armv8.0)二进制文件的向后兼容性
有关指针身份认证的更多信息,请参阅有关该主题的 官方文档
-
Building for iOS 12.0–13.7(为 iOS 12.0–13.7 进行构建)
Theos 输出的以下警告可能会将您引导到此处:
Warning: Building for iOS 7.0, but the current toolchain can’t produce arm64e binaries for iOS earlier than 14.0. More information:https://github.com/theos/theos/wiki/arm64e-Deployment
警告:为 iOS 7.0 进行构建,但是当前的 Toolchain 无法为 14.0 之前的 iOS 生成 arm64e 的二进制文件。更多信息:https : //github.com/theos/theos/wiki/arm64e-Deployment
在 iOS 14.0 和 Xcode 12.0(或者 clang 1200 以及其他平台上更新版本的 Toolchain)中,arm64e 的 ABI(应用程序二进制接口,Application Binary Interface)发生了变化。使用此版本编译器构建的二进制文件将与 iOS 12.0–13.7 上的 arm64e 的实现不兼容
有两种方法可以克服这个问题:
-
增加您的部署版本:如果您只想让您的越狱软件在 iOS 14.0 或者更高版本上运行,请通过在
TARGET
中进行这样的设置来明确地说明这一点。例如,在您的 Makefile 的顶部添加:export TARGET = iphone:latest:14.0
此
TARGET
变量表示要使用您已安装的最新版本的 SDK 为 iOS 进行构建,并为 iOS 14.0 及更新版本部署构建的二进制文件 -
安装 Xcode 11.7:如果您仍然计划支持 14.0 之前的 iOS 版本,则需要降级到 Xcode 11.7
您可以通过以下链接直接从苹果下载 Xcode 11.7:Xcode_11.7.xip。您需要使用您的 AppleID 进行身份验证才能下载
下载后,打开
.xip
文件将开始解压缩。解压后,重命名该应用程序以不与您的主 XCode 的安装发生冲突。一个不错的选择是Xcode-11.7.app
最后,更改您选择的 Xcode 命令行工具的版本:
# 更改您选择的 Xcode 命令行工具的版本为 Xcode 11.7 sudo xcode-select -switch /Applications/Xcode-11.7.app/Contents/Developer # 如果您需要使用命令行中最新的 Xcode Toolchain,则使用 --reset 进行重置: sudo xcode-select --reset # 或者,您可以临时更改命令行工具版本(仅用于此终端会话): export DEVELOPER_DIR=/Applications/Xcode-11.7.app/Contents/Developer
您还可以使用 Xcode 的 GUI 界面来更改您的命令行工具版本,方法是通过
Xcode → Preferences → Locations → Command Line Tools
License(许可证)
Theos(以及它的扩展 Logos)在 GNU 通用公共许可证第 3 版(或者更高版本)的规定下可用,可在此处获取:http://www.gnu.org/licenses/gpl-3.0.html
使用 Theos 和/或 Logos 创建的项目不被视为衍生作品(从许可的角度,或者就此而言的任何其他角度),因此不需要根据 GNU GPL 获得许可
包含的项目模板是免许可的。使用模板并不会向您的项目授予许可证
See also(请参阅)
iPhone Dev Wiki
/r/jailbreakdevelopers
theos-ref
补充(by:HCG)
Toolchain(工具链)
为了完成一套流程所用到的每个工具,以及为了完成此套流程工具之间的组织关系,所组成的集合,就称之为工具链(Toolchain)
绝大部分开发者开发 iOS 或者 macOS 的 App 都会选择 Xcode 作为集成开发环境。Xcode 是一款强大的 GUI IDE(Graphical User Interface - Integrated Development Environment),集(开发、编译、调试、代码分析)于一体。而在这背后,则是一系列工具和流程的支撑。在对 xcodebuild
进行 patch 之后,我们可以得到 Xcode 在编译一个工程时所涉及的工具的图谱:
-
xcodebuild
:编译 Xcode 工程的命令行工具 -
sh
:shell 工具 -
mkdir
:创建目录 -
xcexec
:执行 wrapper -
clang
:编译器,内部封装了编译、优化过程 -
ld
:链接器 -
ibtool
:nib
资源文件本地化 -
ibtoold
:资源文件链接 -
actool
:asset
资源文件编译 -
builtin-infoPlistUtility
:plist
文件编译工具 -
builtin-productPackagingUtility
:打包工具 -
touch
:文件创建 -
codesign
:创建、查看和修改签名 -
codesign_allocate
:为 Mach-O 文件增加签名数据 -
builtin-validationUtility
:校验工具
Tar 命令与 .tar 格式
tar
是 Unix 和类 Unix 系统上的(打包和压缩)工具,可以将多个文件合并为一个文件,打包后的文件后缀名为 .tar
。tar
文件格式已经成为 POSIX 标准,最初是 POSIX.1-1988,当前是 POSIX.1-2001。tar
工具最初的设计目的是将文件备份到磁带上(tape archive),因而得名 tar
常用的 tar
工具是自由软件基金会开发的 GNU 版,稳定版本是 1.28,发布于 2014 年 7 月 27 日。tar
命令是 Unix/Linux 系统中备份文件的可靠方法,几乎可以工作于任何环境中,它的使用权限是所有用户
.tar
代表已打包但未压缩的文件。已压缩的 tar
文件则会附加压缩文件的扩展名,如经过 gzip
压缩后的 tar
文件,扩展名为 .tar.gz
。由于受到 DOS8.3
文件名格式的限制,常使用下列缩写:
- .
tgz
==.tar.gz
.tbz
与.tb2
==.tar.bz2
.taz
==.tar.Z
.tlz
==.tar.lzma
.txz
==.tar.xz
本文参考链接
- 链接地址:Theos 官方文档