How lessica/trollspeed works
Project type and purpose
• TrollSpeed is an iOS system‐level utility (packaged as a Theos “.tipa” and/or Xcode‐built IPA) that displays real‐time upload and download network speeds below the status bar.
• It leverages root‐privileged daemons, a HUD (overlay) process with AssistiveTouch entitlements, and a Settings preferences bundle.
File structure
• Top‐level build & CI:
• .github/workflows/* – CI pipelines (build & analyze, release)
• Makefile, build.sh, devkit/*, gen-control.sh – scripts for Theos packaging and Xcode builds
• Gemfile – Ruby dependencies (e.g., for bartycrouch translation workflow)
• Packaging layout:
• layout/DEBIAN/*, layout/Library/LaunchDaemons/*.plist – Debian control files and a LaunchDaemon PLIST for the HUD service
• libraries/, headers/, libroot/ – static libraries and private iOS headers required at compile time
• Source code:
• sources/ – HUD app code (Objective-C & Swift), Intents handlers, KIF tests, third‐party controller extensions (SPLarkController, SnapshotSafeView)
• prefs/ – Preference bundle for Settings App, with Makefile, Resources, and a TSPrefsRootListController
• Xcode project:
• TrollSpeed.xcodeproj & supporting files under supports/ – for building with Xcode (bridging headers, entitlements, assets)
• Localization & assets:
• Resources/ and .lproj folders – localized strings and InfoPlist.strings
README for additional insights
• Confirms four main building blocks:
a. TrollStore host app (spawn with root privilege)
b. HUD process (AssistiveTouch entitlements via UIDaemon)
c. NetworkSpeed13 library to fetch bandwidth data
d. Preference observing and self‐termination on uninstall
• Build instructions: either Theos (make package) or Xcode (./build.sh)
Main components & interactions (to be shown
A. Build & Packaging Layer
• Theos Build System (Makefile + devkit) → .tipa package
• Xcode Build (TrollSpeed.xcodeproj + supports/) → .ipa
B. Installer/Host Environment
• TrollStore on device installs the package with root privileges
C. Daemon & LaunchDaemon
• layout/Library/LaunchDaemons/ch.xxtou.hudservices.plist registers a LaunchDaemon
• Daemon spawns the HUD process at boot or on demand
D. HUD Process
• Runs with AssistiveTouch entitlements (via UIDaemon)
• Uses NetworkSpeed13 to poll Rx/Tx metrics
• Renders overlay UI with custom windows (HUDMainWindow, HUDRootViewController)
E. Settings & Preferences
• PreferenceLoader hook loads TSPrefsRootListController under Settings
• User changes written to NSUserDefaults → observed by HUD process (CFNotification or KVO)
F. System Integration
• SpringBoard ensures persistence of the HUD (root privileges prevent SpringBoard from killing it on unlock)
• Observes app removal events to terminate HUD cleanly
Architectural patterns & design principles
• Separation of concerns: build vs packaging vs runtime
• Process isolation: host app vs HUD overlay service vs preferences bundle
• Privilege boundaries: Theos package → LaunchDaemon → root‐privileged HUD
• MVC in HUD code: view controllers under sources/, model from NetworkSpeed13, views under HUDBackdropView/Label
Detail
• Debian layout directory and its mapping onto /Library/LaunchDaemons and other filesystem targets
• Call out the private headers and static libraries as dependencies in a “Compile‐time” bubble