Next generation debugging framework for iOS
Objective-C Swift Other
Latest commit 0cd2d09 Jan 3, 2017 @Legoless committed on GitHub Update README.md

README.md

alpha

 

Issues on Waffle Built by Dominus Build Status Carthage compatible Obj-C Code Pod Version Pod Platform Pod License

Alpha is the idea of a next generation debugging framework for iOS applications. It combines multiple debugging tools built on top of a simple, unified API. It lives entirely in your application sandbox and collects information during your application lifetime. Only 1 minute is needed to integrate and requires no code changes.

Watch presentation by Dal Rupnik of Alpha ideas at SwiftConf 2015.

The project is work in progress and might be too unstable to be used in real environment yet. Feel free to open GitHub issues (especially Swift projects). Currently the most unstable is the Heap plugin, so it might be best to avoid using it (might be removed in the future, as it is technically impossible to know when memory is freed).

intro

Features

Features are separated into multiple plugins, which can be enabled or disabled, depending on application requirements.

  • Application - displays a list of all installed applications on the device.
  • Bootstrap - checks for KZBootstrap environments and allows modifying them in real-time.
  • Console - displays console logs (logged by NSLog) inside the application.
  • Event - logs and displays application wide events such as background state transitions and view controller appearances.
  • File - allows browsing the sandboxed file system and previewing common file types, such as images, videos and text.
  • Global - information plugin displays linked frameworks, libraries and classes.
  • Heap - allows inspection of active object instances on ther heap and helps with debugging memory errors.
  • Interface - plugin is a specific plugin and is required to display Alpha menu interface and actions.
  • Keychain - browse items in keychain added by the application.
  • Network - logs network connections made using NSURLSession and NSURLConnection API's.
  • Notification - displays scheduled and fired local notifications, received push notifications and notification permissions.
  • Object - allows for inspection of any class or object in the application, including NSUserDefaults, arrays and dictionaries.
  • Permission - displays current permissions and adds the ability to request specific permission.
  • Remote - plugin allows connecting to Alpha from another device (needs Bonjour running on target).
  • Screenshot - plugin allows taking screenshots of the application with a single action.
  • Server - contains a simple Bonjour server allowing Alpha to work over local Wi-Fi network.
  • State - allows inspecting the device state and settings, such as locale, time and available memory.
  • Touch - plugin displays touches on screen when activated and their force touch.
  • View - allows view hierarchy manipulation and inspection in real-time.

Currently work in progress:

0.4.0

  • Application State Snapshot
  • Display crashes inside Alpha
  • Font Family list
  • Remote client target
  • Larger example apps with more functionality
  • In-app debugger
  • Resetting permissions (if possible to implement over TCC framework)

Themes

Alpha is meant to work with any application, but the default dark theme does not always fit best with the application color scheme.

To fit in with any application Alpha has theme support, which allows you to choose the color palette you wish to display Alpha in.

Default Formentera Notio

There are 6 themes available:

If is also possible to create your own theme and use it in Alpha system.

Read more on Themes.

Triggers

Triggers are a way to activate Alpha interface from your application. By default Alpha provides two triggers:

  • Shake Trigger - Activates when device is shaken two times in less than 5 seconds.
  • Tap Trigger - Activates when 3 fingers are pressed for 3 seconds anywhere in the application.

Both triggers are activated by default. Alternatively you can implement your own trigger or use the manual trigger.

Read more on Triggers.

Integration

Alpha is separated into 2 frameworks:

  • Service
    • Plugins
  • Interface

Service module is installed into your app and executed when the application launches. It automatically initializes plugins and starts collecting data from your application.

Service framework includes Bonjour server, which can be activated by any of the available triggers.

Alpha.framework includes both Service framework and interface module.

To use Alpha in your project, all you need to do is add a CocoaPods library:

pod 'Alpha'

This automatically includes all plugins and features. To avoid clashes with any libraries used in application, all Alpha classes use ALPHA prefix (even classes ported from other libraries). The recommended way is to ignore Alpha version and always use the latest version, to ensure best stability possible.

You can also pick only the plugins you need manually.

pod 'Alpha/Bonjour'
pod 'Alpha/Interface'
pod 'Alpha/State'

To use automatic integration feature, add Integration subspec (when using Alpha pod, it is automatically included).

pod 'Alpha/Integration'

Alpha supports iOS 8 and up. Not all features are available on all versions. tvOS and watchOS versions coming soon.

Read more on Integration.

The Story

Alpha originally started as an unofficial fork from FLEX (Flipboard Explorer). It began with a simple desire to add multiple features to FLEX, but looking at it more and more, it was obvious that many architectural changes were required to support remote clients. Those kind of changes are the hardest to merge into original repository without breaking multiple features, it was obvious that it fits more to create a separate repository.

So Alpha was converted into a separate repository and work began on top of that. Many features were added and there are many architectural changes under the hood. Alpha is now not a separate tool, but a framework that offers a full API. Features from tools are now working on top of plugin API, which allows dynamic loading and incredible extensibility.

Documentation

The entire Alpha documentation is available on Wiki and on CocoaDocs.

Contributions

To contribute to Alpha, please open pull requests. Any feature implementations or improvements, bug fixes, documentation are very welcome.

Thanks

This project would not be possible without all the work done by many respected community contributors. Thanks to all contributors of the following projects:

Contact

Dal Rupnik

License

Alpha is released under the MIT license. See LICENSE file for more information.