ios-logos-tweak — скилл

---
name: ios-logos-tweak
description: Best practices for iOS jailbreak tweaks using Theos and Logos (%hook, %hookf, %new, %orig, %init). Prefer Logos and Substrate helpers (MSHookIvar) over manual hook/ivar runtime APIs. Covers firmware checks (IS_IOS_OR_NEWER vs @available vs respondsToSelector) and bracket messaging. Use when writing or reviewing .x/.xm tweak code, MobileSubstrate/libhooker hooks, swizzling, or Theos Tweak projects.
---

# iOS Logos Tweak Best Practices

## Core rule

Put hooking code in **Logos files** (`.x`, `.xm`, `.xi`) and express hooks with **Logos directives**. Let the Logos preprocessor emit `MSHookMessageEx`, `MSHookFunction`, `class_addMethod`, constructors, and class registration.

Do **not** hand-write Substrate hook boilerplate in tweak source unless Logos cannot express the case (rare; see [reference.md](reference.md)).

## File layout

**Default: `.x`.** Most tweaks use a single `Tweak.x` (Logos + Objective-C). Theos runs Logos on the file, then compiles the result as ObjC.

| Extension | Compiles as | When to use |
|-----------|-------------|-------------|
| **`.x`** | Objective-C | **Default.** `%hook`, `%hookf`, `%new`, `%orig`, `%property`, blocks, and normal Foundation/UIKit code. |
| **`.xm`** | Objective-C++ | Only when this **translation unit** needs C++ or Substrate’s C++ APIs (see below). |
| **`.xi` / `.xmi`** | Included fragments | Rare: Logos inside `#define` macros or `#include` chains; prefer splitting into separate `.x`/`.xm` files with `extern` instead ([Theos docs](https://theos.dev/docs/logos-file-extensions)). |

### Use `.xm` when this file contains

- **`MSHookIvar<T>`** or **`MSIvarHook`** (implemented as C++ templates in `<substrate.h>`).
- **C++** only valid in ObjC++: `std::`, `namespace`, templates, lambdas, C++ types in hook bodies.
- **`%orig`** forms that embed **block literals** in the hook implementation when your toolchain/setup requires ObjC++ for those expansions (uncommon; most hooks stay in `.x`).

### Stay on `.x` when

- Hooks are plain Objective-C (even with blocks, `@autoreleasepool`, etc.).
- You do not call `MSHookIvar` in that file.

If only one hook file needs ivar access, keep **`Tweak.x`** and add a small **`Something.xm`** (or move just those hooks to `.xm`) rather than renaming the whole project to `.xm` without reason.

Keep **interfaces and constants** in normal `.h` / `.m` when they are not hooks. Keep **all hooks** in Logos (`.x` / `.xm`, not raw `.m` with `MSHook*`).

Do not `#include <substrate.h>` in Logos files; Theos/Logos adds it in generated code.

## Objective-C methods: `%hook`

```logos
%hook YTPlayerViewController