JBDev is designed for jailbreak development and TrollStore development in Xcode. It provides the same development experience as a normal app: build → install → debug in Xcode. Tested environments:

• Xcode 12-16
• iOS 12-16
• arm64/arm64e
• Checkra1n/Unc0ver/Taurine/Palera1n/Dopamine
• Rootful/Rootless/Roothide jailbreak

• Supports Jailbreak(Rootful/Rootless/Roothide) development & source-level debugging with Xcode
• Supports TrollStore development & source-level debugging with Xcode
• Supports using Xcode to debug any process on iOS
• No developer account required; use Xcode to develop apps with no device limits

Notes

• JBDev can only be used for debugging on jailbroken devices
• When using JBDev for jailbreak development, the packaging feature depends on Theos
• When using JBDev for TrollStore development, make sure TrollStore is installed

Debugging methods overview for common project types

Notes:

• Launch debug: launch the app via Xcode and make it wait for the debugger to attach
• Attach debug: attach when the process is already running; LLDB usage: debugserver --attach=[pid|name] (same as Xcode)
• Wait debug: wait for the process to start and auto-attach; LLDB usage: debugserver -waitfor=[name] (same as Xcode)

• Get ready with a jailbreak iDevice
• Install appsync(optional); Download and install jbdev.deb from https://github.com/lich4/JBDev/releases
• Install Theos on macOS, https://github.com/roothide/Developer
• Test the demo JBDevJBTest with THEOS setting to your install path of Theos
• After getting familiar with the basic usage of JBDev, try setting up a whole new project as described in Readme, and build your own project with JBDev
• Enjoy

Core files

• jbdev.plist, Control the behaviour of JBDev on iOS. It must be packaged together with app(target type) during development stage, fields:
• • type, Specify packaging type, can be app/jailbreak/trollstore
• jbdev.build.sh, script that controls JBDev packaging

Core settings (environment variables)

• THEOS, Specify the installing path of Theos
• JBDEV_PACKAGE, Control packaging, for app type target only

See JBDevJBTest for details

The following setup does not depend on iOSOpenDev/MonkeyDev.

Use Xcode to create a project equivalent to theos/application

• File - New - Target - iOS - App
• This is the main target, used for JBDev packaging/install/debug

Use Xcode to create a project equivalent to theos/tweak

• File - New - Target - macOS - Library
• Build Settings - set Base SDK to iOS，and set the deployment target to your iOS device

Use Xcode to create a project equivalent to theos/tool

• File - New - Target - macOS - CommandLineTool
• Build Settings - set Base SDK to iOS，and set the deployment target to your iOS device

Configuration files

• Put jbdev.build.sh in the same directory as .xcodeproj
• Put jbdev.plist in the same directory as .xcodeproj, and set type to jailbreak

Configure Build Settings

• For all targets that require ldid signing, set the Code Signing Entitlements path
• Set Installation Directory for all targets
• Add CODE_SIGNING_ALLOWED to project and set to NO
• Add THEOS to project according to the path of your theos
• Add JBDEV_PACKAGE to the main target and set to YES

Configure Build Phase

• For all targets, add a final Run Script phase: bash jbdev.build.sh
• Set other targets as dependencies of the main target

JBDev support Rootful/Rootless/Roothide well as follows

• layout_root directory，stores the diffs from Rootful to Rootless/Roothide
• layout_rootless directory，stores the diffs from Rootless to Rootful/Roothide
• layout_roothide directory，stores the diffs from Roothide to Rootful/Rootless

Commonly used diffs

• layout*/DEBIAN/control，
• • Architecture is iphoneos-arm for Rootful jailbreak
• • Architecture is iphoneos-arm64 for Rootless jailbreak
• • Architecture is iphoneos-arm64e for Roothide jailbreak
• layout*/DEBIAN/{preinst,postinst,extrainst_,prerm,postrm}
• layout*/Library/LaunchDaemons/*.plist

Notes

• The value of Architecture in layout/DEBIAN/control is unrelated to the Architecture in Xcode Build Settings, available arch for Rootful is armv7/arm64/arm64e, and arm64/arm64e for Rootless/Roothide jailbreak
• There must be uicache in postinst/extrainst_ file in layout/DEBIAN, or installing from Xcode will fail for system app not installed

general

• For tweak target, set Runpath Search Paths Header Search Paths Framework Search Paths
• For tweak target, link libsubstrate.tbd

Rootful jailbreak

• For all targets, remove THEOS_PACKAGE_SCHEME from Build Settings

Rootless jailbreak

• For all targets, set THEOS_PACKAGE_SCHEME in Build Settings to rootless
• Set THEOS_PACKAGE_SCHEME_ROOTLESS in Preprocessor Macros

Roothide jailbreak

• For all targets, set THEOS_PACKAGE_SCHEME in Build Settings to roothide
• Set Preprocessor Macros in THEOS_PACKAGE_SCHEME_ROOTHIDE
• For tweak target, link libroothide.tbd

See JBDevTweakTest for details. JBDev can debug any app, as well as debug the tweak injected to app at source-level, The idea:

• Setup an empty app target with the same BundleID as the target App(FakeApp)
• Perform packaging & installing & debugging with Xcode, and JBDev will skip installing FakeApp
• Start debugging after target app spawned

Set up FakeApp

• File - New - Target - iOS - App

Prepare files

• Add entitlement plist files to the target sourcecode directory for each target
• Put jbdev.build.sh to the same directory level of .xcodeproj
• Putjbdev.plist to the same directory level of .xcodeproj, and set type to jailbreak

Configure Build Settings

• Add CODE_SIGNING_ALLOWED to project and set to NO
• Add JBDEV_PACKAGE to the target and set to YES
• Add JBDEV_NO_COPY to FakeApp to prevent JBDev from installing itself

Configure Build Phase

• Add Run Script to all targets as the last phase，and set the content to bash jbdev.build.sh

Notes

• SpringBoard is not an app-type target and cannot be launch-debugged

Build Rules - Add:

• Files '*.x' using Script
  • Source files with names matching: "*.x"
  • Custom script(uncheck 'Run once'): $THEOS/bin/logos.pl -c warnings=error $INPUT_FILE_PATH > $DERIVED_FILE_DIR/$INPUT_FILE_NAME.m
  • Output Files: ${DERIVED_FILE_DIR}/${INPUT_FILE_NAME}.m
• Files '*.xm' using Script
  • Source files with names matching: "*.xm"
  • Custom script(uncheck 'Run once'): $THEOS/bin/logos.pl -c warnings=error $INPUT_FILE_PATH > $DERIVED_FILE_DIR/$INPUT_FILE_NAME.mm
  • Output Files: ${DERIVED_FILE_DIR}/${INPUT_FILE_NAME}.mm

• Build Phases - Compile Sources - add ".x/.xm" file
• View - Inspector - File, select ".x" file in project navigator, under 'Identity and Type' change 'Type' to 'Objctive-C Source', reopen ".x" file. The same steps for ".xm" file.
• You can now click the left gutter in the Xcode editor to set breakpoints directly in your Logos source code.

See JBDevTSTest for details. Prerequisites: iOS must be jailbreaked and able to use TrollStore.

Set up an iOS App project

• File - New - Target - iOS - App

Prepare files

• Add entitlement plist files to the target sourcecode directory for each target
• Put jbdev.build.sh to the same directory level of .xcodeproj
• Putjbdev.plist to the same directory level of .xcodeproj, and set type to trollstore

Configure Build Settings

• Add CODE_SIGNING_ALLOWED to project and set to NO
• Add JBDEV_PACKAGE to the target and set to YES

Configure Build Phase

• Add Run Script to the target as the last phase，and set the content to bash jbdev.build.sh

Notes

• For TrollStore app development, because a “pure TrollStore” environment differs significantly from a jailbreak environment, you should further test in a pure TrollStore environment later.

cd JBDev
make clean; make package
make clean; make package THEOS_PACKAGE_SCHEME=rootless
make clean; make package THEOS_PACKAGE_SCHEME=roothide

When you encounter issues while using JBDev, first identify which stage the problem occurs in before proceeding:

• Compilation stage: indicates an issue with the code itself and is unrelated to JBDev
• Packaging stage: check the error output from Xcode’s jbdev.build.sh; it may be a macOS environment issue such as missing basic commands
• Installation stage: check iOS system logs (prefix JBDev) or the file log /tmp/jbdev.log to locate the error. For example, if dpkg fails and causes the Xcode install step to fail, you can manually install the deb to pinpoint the specific cause.
• Debugging stage: the USB cable may need to be replugged, or the app may have anti-debugging protections

Other notes:

• For iOS >= 15, the first time connecting to a Mac you must use Xcode >= 13. Otherwise, the generated symbol cache may be incorrect, causing extremely long LLDB initialization times. If an incorrect symbol cache has already been generated, you can manually delete it under: ~/Library/Developer/Xcode/iOS DeviceSupport/[device]

jbdev.build.sh: line 78: ldid: command not found

• Cause: There is no ldid in $PATH
• Fix: if ldid is already installed, link it to $PATH as ln -s /path/to/ldid /usr/local/bin/ldid
• Note: handle lzma errors in similar way

A system application with the given bundle identifier is already installed on the device and cannot be replaced.

• Cause: uicache is not specified in extrainst_/postinst
• Fix: Reinstall and uninstall deb package manually, or run uicache after deleting app directory manully

Failed to start remote service "com.apple.debugserver" on device.

• Fix: Replug the usb cable

dyld[15323]: terminating because inserted dylib '/Developer/usr/lib/libBacktraceRecording.dylib' could not be loaded: tried: '/usr/lib/system/introspection/libBacktraceRecording.dylib' (no such file, not in dyld cache), '/Developer/usr/lib/libBacktraceRecording.dylib' (no such file), '/private/preboot/Cryptexes/OS/Developer/usr/lib/libBacktraceRecording.dylib' (no such file), '/Developer/usr/lib/libBacktraceRecording.dylib' (no such file)

• Cause: Debugging iOS>=16 with Xcode<=13 mistakenly
• Fix: Use Xcode>=14 instead, or adjust options in Product - Edit Scheme - Run - Options/Diagnostics

dpkg: error processing archive /var/mobile/Media/PublicStaging/JBDevTestApp.app/payload.deb (--install):
 package architecture (iphoneos-arm) does not match system (iphoneos-arm64)
Errors were encountered while processing:
 /var/mobile/Media/PublicStaging/JBDevTestApp.app/payload.deb

• Cause: The deb package does not match Rootful/Rootless/Roothide jailbreak
• Fix: Use the corresponding Xcode settings to compile deb for Rootful/Rootless/Roothide jailbreak

Xcode build error

error: Sandbox: bash(27852) deny(1) file-read-data /path/to/jbdev.build.sh

• Cause: From Xcode15 User Script Sandboxing is enabled by default
• Fix: Disable User Script Sandboxing in Build Settings

Xcode build error

error: Multiple commands produce ...

• Cause: duplicated target name
• Fix: Rename target or use Legacy build system instead

Xcode installation never finishes

• Fix: kill iOS process streaming_zip_conduit/installd

Remove app sandbox directory failed with rm in Rootless/Roothide/trollstore environment:

• Fix: resign rm with following entitlement

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>platform-application</key>
	<true/>
	<key>com.apple.private.MobileContainerManager.allowed</key>
	<true/>
	<key>com.apple.private.security.no-container</key>
	<true/>
	<key>com.apple.private.security.storage.AppBundles</key>
	<true/>
	<key>com.apple.private.security.storage.AppDataContainers</key>
	<true/>
	<key>com.apple.private.skip-library-validation</key>
	<true/>
	<key>com.apple.security.exception.files.absolute-path.read-write</key>
	<string>/var/</string>
	<key>task_for_pid-allow</key>
	<true/>
</dict>
</plist>

JBDev用于Xcode越狱开发及巨魔开发，提供和普通App一样的开发体验，使用Xcode进行编译——安装——调试，已测试环境：

• Xcode12-16
• iOS12-16
• arm64/arm64e
• Checkra1n/Unc0ver/Taurine/Palera1n/Dopamine
• 有根/无根/隐根

• 支持越狱(有根/无根/隐根)App开发&源码级调试
• 支持巨魔App开发&源码级调试
• 支持Xcode调试任意进程
• 无需开发者账号，无设备限制的使用Xcode开发App

注意事项

• JBDev只能用于越狱设备上调试
• 使用JBDev越狱开发时，打包功能依赖于Theos
• 使用JBDev巨魔开发时，确保已安装TrollStore

常见项目类型调试方式一览

注：

• 启动调试，使用Xcode启动App并使其等待调试器附加
• 附加调试，进程已启动情况下附加调试，lldb使用方式debugserver --attach=[pid|name]，Xcode同理
• 等待调试，等待进程启动并自动附加调试，lldb使用方式debugserver -waitfor=[name]，Xcode同理

• iOS端越狱；安装appsync(可选，用于调试普通未签名App)；从https://github.com/lich4/JBDev/releases下载安装合适的jbdev.deb
• Mac端安装支持隐根的Theos，参考https://github.com/roothide/Developer
• 测试JBDevJBTest，将变量THEOS改成Theos安装路径
• 全新创建你自己的项目，并使用JBDev开发

JBDev核心文件

• jbdev.plist，控制JBDev在iOS端行为配置文件，开发阶段需随App一起打包，字段如下
• • type: 指定JBDev以何种方式打包安装，可指定app/jailbreak/trollstore
• jbdev.build.sh，控制JBDev打包的脚本

JBDev核心设置(环境变量)

• THEOS，指定Theos安装路径
• JBDEV_PACKAGE，应用于App类型Target，用于控制最终打包&安装&调试

详细实例见JBDevJBTest

以下配置不依赖于iOSOpenDev/MonkeyDev

使用Xcode建立等同于theos/application的项目

• File - New - Target - iOS - App
• 此为主Target，用于JBDev交互打包/安装/调试

使用Xcode建立等同于theos/tweak的项目

• File - New - Target - macOS - Library
• Build Settings - Base SDK设置为iOS，同时部署Device设置为iOS设备

使用Xcode建立等同于theos/tool的项目

• File - New - Target - macOS - CommandLineTool
• Build Settings - Base SDK设置为iOS，同时部署Device设置为iOS设备

配置文件

• 将jbdev.build.sh放在.xcodeproj同级目录
• 将jbdev.plist放在.xcodeproj同级目录，设置type为jailbreak

配置Build Settings

• 所有需要ldid签名的Target设置Code Signing Entitlements路径
• 所有Target调整Installation Directory
• Project新增CODE_SIGNING_ALLOWED，设置为NO
• Project新增THEOS，设置为theos路径
• 主Target新增JBDEV_PACKAGE，设置为YES(此变量控制是否打包)

配置Build Phase

• 所有Target添加Run Script最后执行，设置为bash jbdev.build.sh
• 主Target将其他Target设置为依赖项

Theos支持为有根/无根/隐根提供layout扩展

• layout_root目录，存放有根与无根/隐根文件diff
• layout_rootless目录，存放无根与有根/隐根文件diff
• layout_roothide目录，存放隐根与有根/无根文件diff

常用diff文件如下

• layout*/DEBIAN/control，
• • 有根Architecture为iphoneos-arm
• • 无根Architecture为iphoneos-arm64
• • 隐根Architecture为iphoneos-arm64e
• layout*/DEBIAN/{preinst,postinst,extrainst_,prerm,postrm}
• layout*/Library/LaunchDaemons/*.plist

注意事项

• layout/DEBIAN/control的Architecture和Xcode Build Settings的Architecture没有关系，有根包的实际arch可以为armv7/arm64/arm64e，无根包/隐根包的实际arch可以为arm64/arm64e
• 必须在layout/DEBIAN的postinst或extrainst_中执行uicache否则因系统App未注册而安装失败

此方式每次可编译有根/无根/隐根中的一种，操作方式如下

通用

• Tweak设置Runpath Search Paths Header Search Paths Framework Search Paths
• Tweak链接libsubstrate.tbd

有根

• 所有Target的Build Settings的THEOS_PACKAGE_SCHEME删除

无根

• 所有Target的Build Settings的THEOS_PACKAGE_SCHEME设置为rootless
• Preprocessor Macros中设置THEOS_PACKAGE_SCHEME_ROOTLESS

隐根

• 所有Target的Build Settings的THEOS_PACKAGE_SCHEME设置为roothide
• Preprocessor Macros中设置THEOS_PACKAGE_SCHEME_ROOTHIDE
• Tweak链接libroothide.tbd

详细实例见JBDevTweakTest。由于JBDev可以调试任意App，因此可以源码级调试注入App的Tweak。原理如下：

• 建立一个和目标App的BundleID相同的空App(FakeApp)
• Xcode执行打包安装调试，JBDev跳过安装
• 目标App启动，开始调试Tweak

使用Xcode建立FakeApp

• File - New - Target - iOS - App

配置文件

• 将jbdev.build.sh放在.xcodeproj同级目录
• 将jbdev.plist放在.xcodeproj同级目录，设置type为jailbreak

配置Build Settings

• 所有Target新增CODE_SIGNING_ALLOWED，设置为NO
• FakeApp新增JBDEV_PACKAGE，设置为YES(此变量控制是否打包)
• FakeApp新增JBDEV_NO_COPY，防止安装FakeApp本身

配置Build Phase

• 所有Target添加Run Script最后执行，设置为bash jbdev.build.sh
• FakeApp将Tweak设置为依赖项

注意

• SpringBoard不属于App类型，不可以启动调试

Build Rules - Add:

• Files '*.x' using Script
  • Source files with names matching: "*.x"
  • Custom script(uncheck 'Run once'): $THEOS/bin/logos.pl -c warnings=error $INPUT_FILE_PATH > $DERIVED_FILE_DIR/$INPUT_FILE_NAME.m
  • Output Files: ${DERIVED_FILE_DIR}/${INPUT_FILE_NAME}.m
• Files '*.xm' using Script
  • Source files with names matching: "*.xm"
  • Custom script(uncheck 'Run once'): $THEOS/bin/logos.pl -c warnings=error $INPUT_FILE_PATH > $DERIVED_FILE_DIR/$INPUT_FILE_NAME.mm
  • Output Files: ${DERIVED_FILE_DIR}/${INPUT_FILE_NAME}.mm

• Build Phases - Compile Sources - 添加".x/.xm"文件
• View - Inspector - File, 选中".x"文件, 在'Identity and Type'设置'Type'为'Objctive-C Source', 关闭并重新打开".x"文件. ".xm"文件操作方式类似.
• 此时可以在Xcode中左侧下断点了

详细实例见JBDevTSTest。前置条件：iOS系统需要能越狱且能使用巨魔

使用Xcode建立普通iOS-App的项目

• File - New - Target - iOS - App

配置文件

• 将jbdev.build.sh放在.xcodeproj同级目录
• 将jbdev.plist放在.xcodeproj同级目录，设置type为trollstore

配置Build Settings

• Target设置Code Signing Entitlements路径，用于ldid签名
• Target新增CODE_SIGNING_ALLOWED，设置为NO
• Target新增JBDEV_PACKAGE，设置为YES(此变量控制是否打包)

配置Build Phase

• 所有Target添加Run Script最后执行，设置为bash jbdev.build.sh

注意事项

• 巨魔App开发，由于纯巨魔环境与越狱环境有较大差异，因此后续需要在纯巨魔环境进一步测试

cd JBDev
make clean; make package
make clean; make package THEOS_PACKAGE_SCHEME=rootless
make clean; make package THEOS_PACKAGE_SCHEME=roothide

在使用JBDev遇到问题时，先判断问题在哪个环节再进行下一步处理：

• 编译环节，说明代码本身有问题，与JBDev无关
• 打包环节，须检查Xcode的jbdev.build.sh报错内容排查问题，可能是Mac环境问题如基础命令缺失
• 安装环节，查看iOS系统日志(前缀JBDev)或文件日志/tmp/jbdev.log以定位错误，比如dpkg失败导致的Xcode安装失败，可手动安装deb排查具体失败原因
• 调试环节，或USB未插拔或App本身有反调试

其他注意事项

• 对于iOS>=15，首次连接Mac必须使用XCode>=13，否则会因生成的符号缓存有误导致lldb初始化时间巨长，若已生成错误的符号缓存可以在此目录手动删除~/Library/Developer/Xcode/iOS DeviceSupport/[设备]

jbdev.build.sh: line 78: ldid: command not found

• 原因：ldid不在$PATH目录下
• 解决：若已安装ldid则链接到$PATH目录下，如ln -s /path/to/ldid /usr/local/bin/ldid
• 注意：类似的方式处理lzma

A system application with the given bundle identifier is already installed on the device and cannot be replaced.

• 原因：安装成功但获取App信息失败(如extrainst_未执行uicache)
• 解决：直接dpkg卸载报错，需要先手动安装deb，再卸载deb；或者手动删App目录再uicache
• 注意：uicache根据越狱工具不同参数不同

Failed to start remote service "com.apple.debugserver" on device.

• 解决：插拔usb重试

dyld[15323]: terminating because inserted dylib '/Developer/usr/lib/libBacktraceRecording.dylib' could not be loaded: tried: '/usr/lib/system/introspection/libBacktraceRecording.dylib' (no such file, not in dyld cache), '/Developer/usr/lib/libBacktraceRecording.dylib' (no such file), '/private/preboot/Cryptexes/OS/Developer/usr/lib/libBacktraceRecording.dylib' (no such file), '/Developer/usr/lib/libBacktraceRecording.dylib' (no such file)

• 原因: 使用Xcode<=13调试iOS>=16
• 解决: 使用Xcode>=14调试 或 在Product - Edit Scheme - Run - Options/Diagnostics关闭对应选项

dpkg: error processing archive /var/mobile/Media/PublicStaging/JBDevTestApp.app/payload.deb (--install):
 package architecture (iphoneos-arm) does not match system (iphoneos-arm64)
Errors were encountered while processing:
 /var/mobile/Media/PublicStaging/JBDevTestApp.app/payload.deb

• 原因: 有根/无根/隐根越狱环境和deb包不匹配
• 解决: 有根/无根/隐根分别使用对应Xcode设置编译deb

Xcode编译错误

error: Sandbox: bash(27852) deny(1) file-read-data /path/to/jbdev.build.sh

• 原因: Xcode15默认开启User Script Sandboxing
• 解决: 在Build Settings中禁用User Script Sandboxing

Xcode编译错误

error: Multiple commands produce ...

• 原因: target名重复
• 解决: 修改target名或使用Legacy build system

Xcode一直安装不停止

• 解决: 杀掉iOS进程streaming_zip_conduit/installd

在无根/隐根/巨魔下用rm命令无法删除沙盒目录

• 解决: 重签名rm

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>platform-application</key>
	<true/>
	<key>com.apple.private.MobileContainerManager.allowed</key>
	<true/>
	<key>com.apple.private.security.no-container</key>
	<true/>
	<key>com.apple.private.security.storage.AppBundles</key>
	<true/>
	<key>com.apple.private.security.storage.AppDataContainers</key>
	<true/>
	<key>com.apple.private.skip-library-validation</key>
	<true/>
	<key>com.apple.security.exception.files.absolute-path.read-write</key>
	<string>/var/</string>
	<key>task_for_pid-allow</key>
	<true/>
</dict>
</plist>