You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Make](https://www.gnu.org/software/make/) is a language used to outline the procedure for a program's creation. The steps are written in Makefiles which are then read by `make` and used to route your project files to tools such as `clang` or `ld` via rules. Theos relies on a [collection of such Makefiles](https://github.com/theos/theos/tree/master/makefiles) to build and package your project. While this allows for significant configuration, the interaction between the various Makefiles severely limits the speed from `make` invocation to build completion.
9
+
10
+
#### Logos
11
+
12
+
[Logos](https://github.com/theos/logos) is a preprocessor written by the Theos team to simplify C-based hooking. This "hooking" is technically swizziling, which is the process of replacing a method/function's implementation at runtime. Logos translates simple statements such as `%hook` into the equivalent [MobileSubstate](http://www.cydiasubstrate.com/api/c/MSHookMessageEx/), [libhooker](https://libhooker.com/docs/), or [internal](https://developer.apple.com/documentation/objectivec/objective-c_runtime?language=objc) (i.e., ObjC Runtime) hooking API. Logos syntax is converted to these APIs during the preprocessing of your [Logos files](Logos-File-Extensions).
13
+
14
+
#### Instance
15
+
16
+
Theos projects are defined through instances, where each instance is a separate piece of the project. For example, a tweak with a preferences subproject is said to be comprised of two instances. These instances' names are given by the user via the `XXX_NAME` variable, where `XXX` is the project type (e.g., tool, tweak, etc). Each instance is built separately and then combined, if specified, in staging (see below).
17
+
18
+
#### Objects
19
+
20
+
When your project files (e.g., .c, .m, .x, etc) are compiled, they are converted into object files (.o). These files reside in `THEOS_OBJ_DIR` along with a number of other files. The object directory is configured as such:
21
+
22
+
```
23
+
.theos/
24
+
obj/
25
+
$(THEOS_SCHEMA)/
26
+
$(THEOS_CURRENT_ARCH)/
27
+
$(THEOS_CURRENT_INSTANCE)
28
+
```
29
+
30
+
If a schema is configured, Theos will place the object files within an aptly named subdirectory in order to differentiate between possible schema builds. If a `release` schema is specified, the files will be placed within the object directory itself and not a schema-based subdirectory. Within said directory, there will be any number of additional subdirectories for the specified architecture(s) your project is built for (e.g., armv7, arm64, arm64e, etc). Within these directories will be the object files for the given project along with a thin binary built from said objects for the given architecture. Outside of these architecture subdirectories will be a fat binary created from each of the architecture thin binaries via `lipo`. This fat binary is considered the final object.
31
+
32
+
To solely build objects, run `make` within your project.
33
+
34
+
#### Staging
35
+
36
+
Staging is the term given to the two step pre-packaging process comprised of:
37
+
38
+
1) The creation of the package hierarchy for the chosen project type
39
+
40
+
2) The placement of the product objects within this structure in preparation for packaging
41
+
42
+
This staging occurs within the `THEOS_STAGING_DIR` which has a number of potential configurations all of which reside in ```.theos/_/``` by default. If present, the contents of `THEOS_LAYOUT_DIR` are copied into the staging directory along with any resource bundles that may be associated with your project.
43
+
44
+
If a `THEOS_PACKAGE_SCHEME` containing a `THEOS_PACKAGE_INSTALL_PREFIX` is provided, Theos will create a second stage with the install prefix in `.theos/_tmp/` in order to separate the project type's package structure from the scheme's packaging prefix. The two will be merged prior to packaging.
45
+
46
+
To build and complete staging without packaging, run `make stage` within your project.
Copy file name to clipboardExpand all lines: docs/Configuration.md
+14Lines changed: 14 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -50,6 +50,20 @@ Such rule names include:
50
50
- `after-$(THEOS_CURRENT_INSTANCE)-all`
51
51
- `internal-$(_THEOS_CURRENT_TYPE)-all`
52
52
53
+
## Schemas ("Schemata")
54
+
55
+
Schemas are a way to manage a group of specific master variables which can have their effect easily turned on or off. An example is the built-in debug schema, which when enabled adds extra options to `CFLAGS`, `LDFLAGS`, and `SWIFTFLAGS`.
56
+
57
+
They are enabled via `THEOS_SCHEMA`, with a space-separated list of the schemas you'd like to enable.
58
+
59
+
Theschemaisdescribedbyspecifyingwhatvariableshavetheirvaluesaffectedbyitsenabling.Doingsocanbedonebydeclaringavariablewiththeformat`schema.VARIABLE`,sothatenablingschemawilldochangestoapossiblequeryofvariable`VARIABLE`(e.g.,`DEBUG.CFLAGS`).`VARIABLE`mustbeusedinTheosforthechangestohaveaneffect.See[common.mk](https://github.com/theos/theos/blob/master/makefiles/common.mk) for schema logic implementation.
60
+
61
+
Example:
62
+
```
63
+
# Enabling schema1 will add the '-DSCHEMA1ENABLED' additional compiler flags.
64
+
schema1.CFLAGS = -DSCHEMA1ENABLED
65
+
```
66
+
53
67
## Utilizing Theos' message commands
54
68
55
69
Theos utilizes a variety of custom `echo` and `printf` commands which it defines as variables in $THEOS_MAKE_PATH/messages.mk. These can be utilized by users in their own project makefiles if so desired.
Copy file name to clipboardExpand all lines: docs/Installation-macOS.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,7 +16,7 @@ All of the commands shown in the following instructions are meant to be run as a
16
16
* [Homebrew](https://brew.sh/)
17
17
* or [MacPorts](https://www.macports.org/install.php)
18
18
* or [Procursus](https://docs.procurs.us/Installation/macOS.html)
19
-
* [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12)<sup>1</sup> is mandatory. The Command Line Tools package isn’t sufficient for Theos to work. Xcode includes toolchains for all Apple platforms.
19
+
* [Xcode](https://developer.apple.com/download/applications/)<sup>1</sup> is mandatory. The Command Line Tools package isn’t sufficient for Theos to work. Xcode includes toolchains for all Apple platforms.
20
20
21
21
<sup>
22
22
<sup>1</sup> Xcode 5.0 or newer. Xcode 4.4 supported, but only when building for ARMv6 (1st/2nd generation iPhone/iPod touch).
With Theos being Makefile-based, additional functionality can be provided as-desired through "modules."
8
+
9
+
Modules are directories containing Makefiles with additional rules, variables, and/or checks that you would like your Theos install to contain. A module structure may look something like
10
+
```
11
+
my-module/
12
+
├── instance
13
+
│ ├── framework.mk
14
+
│ ├── library.mk
15
+
│ └── rules.mk
16
+
├── package
17
+
│ └── deb.mk
18
+
└── package.mk
19
+
```
20
+
where each `.mk` file contains custom code such as
Modules' structure and the respective `.mk` filenames tell Theos where to add your provided functionality. For example, `my-module/package/deb.mk` tells Theos to add the functionality contained in the module's `deb.mk` file to `$(THEOS_MAKE_PATH)/package/deb.mk`. Providing additional functionality through modules is only supported for specific parts of Theos, however. These parts include:
27
+
28
+
-`rules.mk`
29
+
-`common.mk`
30
+
-`package.mk`
31
+
-`platform/*.mk`
32
+
-`targets/**/*.mk`
33
+
-`package/*.mk`
34
+
-`install/*.mk`
35
+
-`instance/*.mk`
36
+
- Except `aggregate.mk`
37
+
-`master/*.mk`
38
+
39
+
Modules should be placed in `$(THEOS_MODULE_PATH)` and are imported by Theos *only* when you explicitly ask them to be through `MODULES = my-module`. The exception to this are package schemes, which can be provided in module form (see `$THEOS/vendor/mod/rootless` for an example). For package schemes, the scheme specified by `THEOS_PACKAGE_SCHEME` will be imported without needing to specify the module explicitly via `MODULES`. These are "enabled" through Makefile's `-include` feature and are typically included *after* all of the stock Theos functionality has been defined. Thus, modules support all Theos variables that have been defined by the time your specific Module is imported.
Copy file name to clipboardExpand all lines: docs/Rootless.md
+37-19Lines changed: 37 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,6 +7,8 @@ layout: docs
7
7
8
8
Practically all jailbreaks prior to iOS 15 have been 'rootful' as they work on and install files to the (root) system directories (e.g., `/usr`, `/Library`, `/Applications`, etc). Moving forward with iOS 15 and beyond, most if not all jailbreaks will have to be 'rootless' as Apple now prevents writing to the system directories with a protection called [Signed System Volume (SSV)](https://support.apple.com/guide/security/signed-system-volume-security-secd698747c9/web). There are workarounds for this, namely bindFS, but these are less than ideal.
9
9
10
+
Note that 'rootless' does not imply lack of `root` user permissions, contrary to what its name might suggest.
11
+
10
12
To work around SSV, the [Procursus Team](https://github.com/procursusteam/) has thought up a rootless scheme that is now the de facto rootless standard. The changes namely involve working in and installing tweaks/addons to `/var/jb` and using the `iphoneos-arm64` package architecture. To learn more about the specifics of this implementation, see [The Apple Wiki](https://theapplewiki.com/wiki/Rootless).
11
13
12
14
With this new target location, *all* projects will have to be recompiled to reference resources from and install to `/var/jb`. This involves changing the internal structure of .deb's to include this new path and specifying library and framework install paths using `@rpath` instead of absolute paths. Theos will handle both of these changes for you. For more information on what `@rpath` is and how it works, see Mike Ash's [informative blog post](http://www.mikeash.com/pyblog/friday-qa-2009-11-06-linking-and-install-names.html).
@@ -18,47 +20,63 @@ With this new target location, *all* projects will have to be recompiled to refe
18
20
**Important Notes**:
19
21
- You must run `make clean` when switching between a rootful and rootless build
20
22
21
-
- If you maintain a library, you'll want to add some variation of the following to your code so that it will have the correct install path:
- Likewise, if you maintain a framework, you'll want to add some variation of the following to your code so that it will have the correct install path:
- The iOS 14 arm64e ABI mentioned in [arm64e Deployment](arm64e-Deployment.html) is now *required* for the relevant devices
36
-
- Currently, it's only possible to build for the new ABI on macOS
37
-
- If you want to maintain support for earlier versions, you can grab the toolchain from an earlier Xcode release as specified in [arm64e Deployment](arm64e-Deployment.html) and switch between it and the newer toolchain as desired by setting the `PREFIX` variable to the older toolchain's bin (i.e., `<xcode-ver>.xctoolchain/usr/bin/`) in your project's makefile
24
+
- Currently, it's only possible to build for the new ABI on macOS as the necessary `ld64` changes, included in Xcode, have not been made open source
25
+
- Unfortunately, this newer toolchain does not support building for the old ABI. If you want to maintain support for earlier versions, you can grab the toolchain from an earlier Xcode release as specified in [arm64e Deployment](arm64e-Deployment.html) and switch between it and the newer toolchain as desired by setting the `PREFIX` variable to the older toolchain's bin (i.e., `<xcode-ver>.xctoolchain/usr/bin/`) in your project's makefile
38
26
- That being said, developers on other platforms can circumvent this *if necessary*:
39
-
- By adding `oldabi` as a dependency to their package (preferably only as a last resort)
27
+
- By [using GitHub Actions](https://github.com/p0358/SilentScreenshots/blob/master/.github/workflows/build.yml) to compile their tweaks (free for both public and private repos)
28
+
- By using a macOS virtual machine
29
+
- See KVM on Linux and VMware on Windows
30
+
- If you want to reduce resources used by the VM (after installing Xcode and Theos):
31
+
-[Enable SSH access in System Preferences](https://osxdaily.com/2022/07/08/turn-on-ssh-mac/)
32
+
- Disable the WindowServer daemon with `sudo launchctl disable system/com.apple.WindowServer` and reboot.
33
+
- This will disable macOS's graphical user interface, reducing the idle CPU and RAM usage to ~900 MB
34
+
- Reboot and SSH into the VM to use Theos
35
+
- By using [allemande](https://github.com/p0358/allemande) (static binary converter to old ABI)
36
+
- This is currently the best solution if you cannot use macOS and Xcode
37
+
- It does not work with tweaks containing Swift code (including the Cephei v2.0 library)
38
+
- By adding `oldabi` as a dependency to their package (preferably only for testing or as a last resort as it applies system-wide and may cause instability for users)
39
+
- If you intend to release packages without the `oldabi` dependency, make sure to uninstall `oldabi` from your device during testing to avoid accidentally releasing a tweak that silently relies on it without your knowledge!
40
+
-**Please note**: this only applies to arm64e binaries (i.e., system binaries and libraries). It does not apply to App Store apps or regular CLI binaries as arm64e is disallowed due to its unstable ABI. That is, you can continue compiling tweaks for non-system apps with any toolchain and do not need to target arm64e for your apps or CLI binaries.
40
41
41
42
---
42
43
43
44
Theos supports building for the rootless scheme in a few ways:
44
45
- Provides rootless-compatible libraries and frameworks in `$THEOS_VENDOR_LIBRARY_PATH/iphone/rootless`
45
46
46
-
- Provides `rootless.h` -- a header that contains convenient macros to easily convert rootful paths to rootless ones in your code at compile-time, assuming you compile for the rootless scheme (see below)
47
+
- Provides [`rootless.h`](https://github.com/theos/headers/blob/master/rootless.h) -- a header that contains convenient macros to easily convert rootful paths to rootless ones in your code at compile-time, assuming you compile for the rootless scheme (see below)
47
48
-`#import <rootless.h>`
48
-
- Courtesy of [opa334](https://github.com/theos/headers/commit/9f00c9663aff892b512f87666dbfbf8fe4943e84)
49
+
- Courtesy of opa334
49
50
50
51
-`THEOS_PACKAGE_SCHEME=rootless` -- a variable to enable a handful of internal changes including:
51
52
- Searching for libraries and frameworks when linking in `$THEOS_LIBRARY_PATH/iphone/rootless` and `$THEOS_VENDOR_LIBRARY_PATH/iphone/rootless`
53
+
- Handling install_name changes to use @rpath for libraries and frameworks
52
54
- Passing the relevant prefixed rpaths to the linker so your project can find the linked rootless libraries and frameworks on-device
53
55
- Sharing the install prefix (`THEOS_PACKAGE_INSTALL_PREFIX=/var/jb`) with the compiler for use in your code
54
56
- Setting the package architecture to `iphoneos-arm64` if your control file specifies `iphoneos-arm`
55
57
56
58
Additional notes:
57
59
- You do *not* need to create separate package identifiers for rootful/rootless versions of the same package
58
60
- Newer versions of rootless-compatible package managers (e.g., Sileo and Zebra) will present only the compatible version to users
61
+
- Cydia will display duplicate packages, but both point to the rootful version
62
+
- This can be corrected with [cyarchfix](https://github.com/PoomSmart/cyarchfix) by PoomSmart
59
63
- The behavior of other package managers varies and may or may not supply the correct package to users
60
64
61
65
- All non-DEBIAN items (e.g., maintainer scripts) are placed in `/var/jb`
66
+
- Please ensure that any additional resources you provide (e.g., newly created or laid out files and directories) are stored in a prefixed path and not a rootful path, as the latter could lead to jailbreak detection in a non-jailbroken state
62
67
63
68
- This new rootless scheme only supports iOS 15+, which itself only supports newer devices
64
69
- This means that you do not need to compile for legacy architectures (e.g., `armv7(s)` or older) if you were previously and can bump your deployment target to 15.0 when building for rootless
70
+
71
+
---
72
+
73
+
If desired, you can conditionally check for the package scheme in your project's Makefile to selectively apply rootless build settings:
0 commit comments