Logos: Difference between revisions

From iPhone Development Wiki
m (Updated %hookf syntax for dynamic lookups)
m (It’s confusing to keep this around, so replacing with a link to the current documentation)
Tag: Replaced
 
Line 1: Line 1:
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.
{{soft redirect|https://theos.dev/docs/logos}}


= Overview =
This article is obsolete, and has been replaced by the [https://theos.dev/docs/logos theos.dev website].


The syntax provided by Logos greatly simplifies the development of MobileSubstrate extensions ("tweaks") which can hook other methods throughout the OS.
If you need historical installation instructions, you can find the last version of this article [https://iphonedev.wiki/index.php?title=Logos&oldid=5734 here].
In this context, "method hooking" refers to a technique used to replace or modify methods of classes found in other applications on the OS.
 
= 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 [[Theos|its page]].
 
= Command Line Interface =
 
Logos can be invoked on the command line via <code>logos.pl</code>. Usage is as follows:
 
<source lang="shell">
logos.pl [--config <setting=value>] <filename>
</source>
 
Below are two examples, one using the default generator (Substrate) and one using the internal generator:
 
<source lang="shell">
logos.pl Tweak.xm
logos.pl --config generator=internal Tweak.xm
</source>
 
= List of Logos Directives =
 
== Block level ==
 
The directives in this category open a block of code which must be closed by an <tt>[[Logos#.25end|%end]]</tt> directive (shown below). These should not exist within functions or methods.
 
=== %group ===
 
<source lang="logos">
%group Groupname
</source>
 
Groups are for conditional initialization or code organization. Grouping can be useful for managing backwards compatibility with older code.
 
Begin a hook group with the name ''Groupname''. Groups cannot be inside another <code>[[Logos#.25group|%group]]</code> block. All ungrouped hooks are in the implicit "_ungrouped" group. The _ungrouped group is initialized for you if there are no other groups. You can use the <code>%init</code> directive to initialize it manually. Other groups must be initialized with the <code>%init(Groupname)</code> directive.
 
<source lang="logos">
%group iOS8
%hook IOS8_SPECIFIC_CLASS
// your code here
%end // end hook
%end // end group ios8
 
%group iOS9
%hook IOS9_SPECIFIC_CLASS
// your code here
%end // end hook
%end // end group ios9
 
%ctor {
if (kCFCoreFoundationVersionNumber > 1200) {
%init(iOS9);
} else {
%init(iOS8);
}
}
</source>
 
=== %hook ===
 
<source lang="logos">
%hook Classname
</source>
 
Open a hook block for the class named ''Classname''.
 
Can be inside a <tt>[[Logos#.25group|%group]]</tt> block.
 
Here's a trivial example:
 
<source lang="logos">
%hook SBApplicationController
-(void)uninstallApplication:(SBApplication *)application {
NSLog(@"Hey, we're hooking uninstallApplication:!");
%orig; // Call the original implementation of this method
return;
}
%end
</source>
 
==== %new ====
 
<source lang="logos">
%new
%new(signature)
</source>
 
Add a new method to a hooked class or subclass by adding this directive above the method definition. ''signature'' is the Objective-C type encoding for the new method; if it is omitted, one will be generated.
 
Must be inside a <tt>[[Logos#.25hook|%hook]]</tt> block.
 
You should also declare the new method within an interface as Logos does not do that automatically. For example:
 
<source lang="logos">
@interface TheClass (TweakMethods)
-(void)yourNewMethod;
@end
 
%hook TheClass
%new
-(void)yourNewMethod { /* code */ }
%end
</source>
 
=== %subclass ===
 
<source lang="logos">
%subclass Classname: Superclass <Protocol list>
</source>
 
Subclass block - the class is created at runtime and populated with methods. ivars are not yet supported (use associated objects).
The <tt>[[Logos#.25new|%new]]</tt> specifier is needed for a method that doesn't exist in the superclass.
To instantiate an object of the new class, you can use the <tt>[[Logos#.25c|%c]]</tt> operator.
 
Can be inside a <tt>[[Logos#.25group|%group]]</tt> block.
 
Here's an example:
 
<source lang="logos">
%subclass MyObject : NSObject
 
- (id)init {
self = %orig;
[self setSomeValue:@"value"];
return self;
}
 
//the following two new methods act as `@property (nonatomic, retain) id someValue;`
%new
- (id)someValue {
return objc_getAssociatedObject(self, @selector(someValue));
}
 
%new
- (void)setSomeValue:(id)value {
objc_setAssociatedObject(self, @selector(someValue), value, OBJC_ASSOCIATION_RETAIN_NONATOMIC);
}
 
%end
 
%ctor {
MyObject *myObject = [[%c(MyObject) alloc] init];
NSLog(@"myObject: %@", [myObject someValue]);
}
</source>
 
==== %property ====
 
<source lang="logos">
%property (nonatomic|assign|retain|copy|weak|strong|getter|setter) Type name;
</source>
 
Add a property to a <tt>[[Logos#.25subclass|%subclass]]</tt> just like you would with <tt>@property</tt> to a normal Objective-C subclass as well as adding new properties to existing classes within <tt>[[Logos#.25hook|%hook]]</tt>.
 
Must be inside a <tt>[[Logos#.25subclass|%subclass]]</tt> or <tt>[[Logos#.25hook|%hook]]</tt> block.
 
=== %end ===
 
<source lang="logos">
%end
</source>
 
Close a group/hook/subclass block.
 
== Top level ==
 
The directives in this category should not exist within a group/hook/subclass block.
 
=== %config ===
 
<source lang="logos">
%config(Key=Value);
</source>
 
Set a logos configuration flag.
 
==== Configuration Flags ====
 
{| class="wikitable"
|-
! Key
! Values
! Notes
|-
| rowspan="2" | generator
| MobileSubstrate
| generate code that uses [[MobileSubstrate]] for hooking.
|-
| internal
| generate code that uses only internal Objective-C runtime methods for hooking.
|-
| rowspan="3" | warnings
| none
| suppress all warnings
|-
| default
| non-fatal warnings
|-
| error
| make all warnings fatal
|-
| rowspan="2" | dump
| yaml
| dump the internal parse tree in YAML format
|-
| <strike>perl</strike>
| <strike>dump the internal parse tree in a format suitable for evaluation as perl source.</strike><br /> dump to the perl source feature is removed since [https://github.com/DHowett/theos/commit/a05354a7b9839a5dce48f7c07114f30dd195b537 this commit].
|}
 
=== %hookf ===
 
<source lang="logos">
%hookf(rtype, symbolName, args...) { … }
</source>
 
Generate a function hook for the function named ''symbolName''. If the name is passed as a literal string then the function will be dynamically looked up.
 
<source lang="logos">
// Given the function prototype
FILE *fopen(const char *path, const char *mode);
// The hook is thus made
%hookf(FILE *, fopen, const char *path, const char *mode) {
NSLog(@"Hey, we're hooking fopen to deny relative paths!");
if (path[0] != '/') {
return NULL;
}
return %orig; // Call the original implementation of this function
}
</source>
 
It is common for people to hook the function that its address is resolved at run-time like, <tt>MGGetBoolAnswer</tt>, for example:
 
<source lang="logos">
bool (*orig_MGGetBoolAnswer)(CFStringRef);
bool fixed_MGGetBoolAnswer(CFStringRef string)
{
if (CFEqual(string, CFSTR("StarkCapability"))) {
return kCFBooleanTrue;
}
return orig_MGGetBoolAnswer(string);
}
 
%ctor {
MSHookFunction(((void *)MSFindSymbol(NULL, "_MGGetBoolAnswer")), (void *)fixed_MGGetBoolAnswer, (void **)&orig_MGGetBoolAnswer);
...
}
</source>
 
You can also do:
 
<source lang="logos">
%hookf(bool, MGGetBoolAnswer, CFStringRef string)
{
if (CFEqual(string, CFSTR("StarkCapability"))) {
return true;
}
return %orig;
}
%ctor() {
%init(MGGetBoolAnswer = MSFindSymbol(NULL, "_MGGetBoolAnswer"));
}
</source>
 
And replace <code>MSFindSymbol(NULL, "_MGGetBoolAnswer")</code> with any expression for a function pointer.
 
=== %ctor ===
 
<source lang="logos">
%ctor { … }
</source>
 
Generate an anonymous constructor (of default priority).
 
=== %dtor ===
 
<source lang="logos">
%dtor { … }
</source>
 
Generate an anonymous deconstructor (of default priority).
 
== Function level ==
 
The directives in this category should only exist within a function block.
 
=== %init ===
 
<source lang="logos">
%init;
%init([<class>=<expr>, …]);
%init(Group[, [+|-]<class>=<expr>, …]);
</source>
 
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. The class name replacement is specially useful for classes that contain characters that can't be used as the class name token for the <tt>[[Logos#.25hook|%hook]]</tt> directive, such as spaces and dots.
 
Usage:
<source lang="logos">
 
%hook SomeClass
-(id)init {
    return %orig;
}
%end
 
%ctor {
    %init(SomeClass=objc_getClass("class with spaces or dots in the name"));
}
</source>
 
=== %class ===
 
<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 <tt>[[Logos#.25c|%c]]</tt>, but still exists. Creates a $Class variable, and initializes it with the "_ungrouped" group.
 
=== %c ===
 
<source lang="logos">
%c([+|-]Class)
</source>
 
Evaluates to <tt>Class</tt> at runtime. If the + sigil is specified, it evaluates to MetaClass instead of Class. If not specified, the sigil defaults to -, evaluating to Class.
 
=== %orig ===
 
<source lang="logos">
%orig
%orig(arg1, …)
</source>
 
Call the original hooked method. It doesn't function in a <tt>[[Logos#.25new|%new]]</tt>'d method. It 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 <tt>self</tt> and <tt>_cmd</tt>, Logos does this for you.
 
=== %log ===
 
<source lang="logos">
%log;
%log([(<type>)<expr>, …]);
</source>
 
Dump the method arguments to syslog. Typed arguments included in <tt>%log</tt> will be logged as well.
 
= File Extensions for Logos =
 
{| class="wikitable"
|-
! Extension
! Process order
|-
| .x
| will be processed by Logos, then preprocessed and compiled as objective-c.
|-
| .xm
| will be processed by Logos, then preprocessed and compiled as objective-c++.
|-
| .xi
| will be preprocessed as objective-c first, then Logos will process the result, and then it will be compiled.
|-
| .xmi
| will be preprocessed as objective-c++ first, then Logos will process the result, and then it will be compiled.
|}
 
xi or xmi files can use Logos directives in #define macros.
 
= 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.<br>
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.
 
== Groups ==
 
Normally, it isn't possible to initialize hooking groups across multiple Logos files, but there is a workaround that can be used to unlock this functionality. This is done by wrapping group initializations inside of static methods that can then be called from other files.<br>
 
Take a look at the following code. All it does is log a message when the SpringBoard application has finished launching. It is inside of a group called '''TweakGroup''', which is initialized in a static function called '''InitGroup()'''.
<source lang="logos">
// Group.xm
#import "Shared.h"
 
%group TweakGroup
%hook SpringBoard
 
- (void)applicationDidFinishLaunching:(id)arg1 {
    %orig;
    NSLog(@"[Group Test] SpringBoard has finished launching");
}
 
%end
%end
 
extern "C" void InitGroup() {
    %init(TweakGroup);
}
</source>
 
As you may have noticed, there is an import for ''Shared.h'' at the top of ''Group.xm''. That is simply a header file that will be imported into our main Logos file so that we may call the function there:
<source lang="logos">
// Shared.h
extern "C" void InitGroup();
</source>
 
Finally, ''Shared.h'' can be imported into the Logos file that contains your constructor. Calling the static function will initialize the group from ''Group.xm'' and run its hooks:
<source lang="logos">
// Tweak.xm
#import "Shared.h"
 
%ctor {
NSLog(@"[Group Test] Our hook for SpringBoard should show up below this");
InitGroup();
}
</source>
 
If done correctly and compiled without errors, this could should log two messages: one from the constructor and the other one from the method inside the group. Keep in mind that this doesn't apply to hooks that aren't inside of a group.
 
'''A few things to note''':
* This doesn't work in normal C, so you must use ''.xm'' files for your groups and constructor.
* You have to pay attention to how many times you call the initialization as Logos will no longer tell you if it is called more than once.
 
= logify.pl =
 
You can use logify.pl to create a Logos source file from a header file that will log all of the functions of that header file. Here is an example of a very simple Logos tweak generated by logify.pl
 
Given a header file:
 
<source lang="logos">
@interface SSDownloadAsset : NSObject
- (NSString *)finalizedPath;
- (NSString *)downloadPath;
- (NSString *)downloadFileName;
+ (id)assetWithURL:(id)url type:(int)type;
- (id)initWithURLRequest:(id)urlrequest type:(int)type;
- (id)initWithURLRequest:(id)urlrequest;
- (id)_initWithDownloadMetadata:(id)downloadMetadata type:(id)type;
@end
</source>
 
You can find logify.pl at $THEOS/bin/logify.pl and you would use it as so:
 
<source lang="bash">
$THEOS/bin/logify.pl ./SSDownloadAsset.h
</source>
 
The resulting output should be:
 
<source lang="logos">
%hook SSDownloadAsset
- (NSString *)finalizedPath { %log; NSString * r = %orig; NSLog(@" = %@", r); return r; }
- (NSString *)downloadPath { %log; NSString * r = %orig; NSLog(@" = %@", r); return r; }
- (NSString *)downloadFileName { %log; NSString * r = %orig; NSLog(@" = %@", r); return r; }
+ (id)assetWithURL:(id)url type:(int)type { %log; id r = %orig; NSLog(@" = %@", r); return r; }
- (id)initWithURLRequest:(id)urlrequest type:(int)type { %log; id r = %orig; NSLog(@" = %@", r); return r; }
- (id)initWithURLRequest:(id)urlrequest { %log; id r = %orig; NSLog(@" = %@", r); return r; }
- (id)_initWithDownloadMetadata:(id)downloadMetadata type:(id)type { %log; id r = %orig; NSLog(@" = %@", r); return r; }
%end
</source>
 
= External links =
 
* [https://github.com/theos/logos/blob/master/bin/logos.pl Main ''logos.pl'' file]
* [https://github.com/theos/logos/blob/master/bin/logify.pl ''logify.pl'' file]
* [https://twitter.com/_uroboro/status/1167878520820813824 %hookf syntax change]
 
[[Category:Development Tools]]

Latest revision as of 18:12, 19 February 2022

Error creating thumbnail: File missing

https://theos.dev/docs/logos

This article is obsolete, and has been replaced by the theos.dev website.

If you need historical installation instructions, you can find the last version of this article here.