Difference between revisions of "Logos"

From iPhone Development Wiki
Jump to: navigation, search
(%class: Add an official deprecation warning.)
Line 67: Line 67:
  
 
<source lang="logos">%class Class</source>
 
<source lang="logos">%class Class</source>
 +
 +
{{warning|<tt>%class</tt> is deprecated. Do not use it in new code.}}
  
 
Forward-declare a class. Outmoded by %c, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group.
 
Forward-declare a class. Outmoded by %c, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group.

Revision as of 23:40, 4 December 2012

Logos is a component of the Theos development suite that allows method hooking code to be written easily and clearly, using a set of special preprocessor directives.

Overview

The syntax provided by Logos greatly simplifies the development of MobileSubstrate extensions ("tweaks") which can hook other methods throughout the OS. In this context, "method hooking" refers to a technique used to replace or modify methods of classes found in other applications on the phone.

Getting Logos

Logos is distributed with Theos, and you can use Logos' syntax in any Theos-built project without any extra setup. For more information about Theos, visit its page.

Using Logos

Examples

Write me!

List of Logos Directives

Initialization

%init
%init
%init([<class>=<expr>, …])
%init(Group[, [+|-]<class>=<expr>, …])

Initialize a group (or the default group). Passing no group name will initialize "_ungrouped", and passing class=expr arguments will substitute the given expressions for those classes at initialization time. The + sigil (as in class methods in Objective-C) can be prepended to the classname to substitute an expression for the metaclass. If not specified, the sigil defaults to -, to substitute the class itself. If not specified, the metaclass is derived from the class.

Block-level

The directives in this category open a block of code which must be closed by an %end directive (shown below).

%hook
%hook Classname

Open a hook block for the class named Classname.

Here's a trivial example:

%hook SBApplicationController
-(void)uninstallApplication:(SBApplication *)application {
    NSLog(@"Hey, we're hooking uninstallApplication:!");
    %orig; // Call the original implementation of this method
    return;
}
%end
%subclass
%subclass Classname: Superclass <Protocol, Protocol>

Subclass block - the class is created at runtime and populated with methods. ivars are not yet supported.

%group
%group Groupname

Begin a hook group (for conditional initialization or code organization) with the name Groupname. All ungrouped hooks are in the implicit "_ungrouped" group.

%class
%class Class
%class is deprecated. Do not use it in new code.

Forward-declare a class. Outmoded by %c, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group.

%new
%new
%new(signature)

Add a new method to a hooked class or subclass. signature is the Objective-C type encoding for the new method; if it is omitted, one will be generated.

%ctor
%ctor {  }

Generate an anonymous constructor (of default priority).

%end
%end

Close a hook/subclass/group block.

Inline

%config
%config(X=Y);

Set a logos configuration flag.

Configuration Flags
  • generator
    • MobileSubstrate
      generate code that uses MobileSubstrate for hooking.
      internal
      generate code that uses only internal Objective-C runtime methods for hooking.
  • warnings
    • none
      suppress all warnings
      default
      non-fatal warnings
      error
      make all warnings fatal
  • dump
    • yaml
      dump the internal parse tree in YAML format
  • patches
    • full
      when dumping data, include text substitutions for patch points
%c
%c(Class)

Effectively evaluates to Class, at runtime. Technically, creates $Class and populates it when the "_ungrouped" group is initialized.

%orig
%orig
%orig(args)

Call the original hooked method. Doesn't function in a `%new`'d method. Works in subclasses, strangely enough, because MobileSubstrate will generate a supercall closure at hook time. (If the hooked method doesn't exist in the class we're hooking, it creates a stub that just calls the superclass implementation.) args is passed to the original function - don't include `self` and `_cmd`, Logos does this for you.

%log
%log

Dump the method arguments to syslog.

Splitting Logos Hooking Code Across Multiple Files

By default, the Logos pre-processor will only process one .xm file at build time. However, it is possible to split the Logos hooking code into multiple files. First, the main file has to be renamed to an .xmi file. Then, other .xm files can be included in it using the #include directive. The Logos pre-processor will add those files to the main file before processing it.