Theos: Difference between revisions

From iPhone Development Wiki
(26 intermediate revisions by 9 users not shown)
Line 1: Line 1:
<small>'''Languages: English &bull; [[Theos/de|Deutsch]]'''</small>
'''Theos''' is a cross-platform suite of development tools for managing, developing, and deploying iOS software without the use of Xcode. It is an important tool for people building extensions (tweaks) for jailbroken iOS; most extension developers use Theos.
'''Theos''' is a cross-platform suite of development tools for managing, developing, and deploying iOS software without the use of Xcode. It is an important tool for people building extensions (tweaks) for jailbroken iOS; most extension developers use Theos.


Line 15: Line 17:
== How to start using Theos ==
== How to start using Theos ==


See [[Theos/Setup]].
See [https://theos.dev/docs/installation Installation].


[http://stackoverflow.com/questions/6118814/is-there-anywhere-where-i-could-start-mobilesubstrate-tweaks-programming/11553722#11553722 This Stack Overflow answer] may also be helpful.
[http://stackoverflow.com/questions/6118814/is-there-anywhere-where-i-could-start-mobilesubstrate-tweaks-programming/11553722#11553722 This Stack Overflow answer] may also be helpful.
Line 23: Line 25:
== Theos variables ==
== Theos variables ==


You can configure theos by setting variables in a project's Makefile.
You can configure Theos by setting variables in a project's Makefile or having them exported as environment variables (affecting all your projects).
 
Appending <code>export</code> before a variable will cause the variable to affect all subprojects as well. This is very useful for certain variables such as <code>SYSROOT</code> and <code>TARGET</code>
 
''This list is incomplete. You can help by expanding it. [https://theos.dev/docs/features From here]?''


Here is an incomplete list of the variables:
=== Building ===


{| class="wikitable sortable"
<div style="overflow-x: scroll;">
|-
{| class="wikitable" style="max-width: 100%; overflow-x: scroll;"
! Variable name
! Variable name
! Description
! Description
Line 34: Line 40:
! Notes
! Notes
|-
|-
| <code>PACKAGE_VERSION</code>
| THEOS
| The directory where Theos is installed on your machine. It is platform dependent
|  
|  
|
|-
| PACKAGE_VERSION
| The current build's number
| <code>$(THEOS_PACKAGE_BASE_VERSION)-$(VERSION.INC_BUILD_NUMBER)</code>
| <code>$(THEOS_PACKAGE_BASE_VERSION)-$(VERSION.INC_BUILD_NUMBER)</code>
| [https://www.reddit.com/r/jailbreakdevelopers/comments/2mmc98/how_to_stop_theos_from_adding_a_build_number_to/cmd71fi/]
| [1]
<code>PACKAGE_VERSION=$(THEOS_PACKAGE_BASE_VERSION)</code> Can be used to disable debug build numbers
|-
|-
| <code>ARCHS</code>
| ARCHS
| List of architectures to build for.
| List of architectures to build for.
Possible values: <code>i386 x86_64 armv6 armv7 armv7s armv7f armv7v arm64</code>
Possible values: <code>i386 x86_64 armv6 armv7 armv7s armv7f armv7v arm64 arm64e</code>
| <code>armv7 arm64 arm64e</code>
| arm64e devices in most cases can run arm64 binaries.
PreferenceLoader, however, cannot typically load arm64 bundles on arm64e devices.
|-
| TARGET
| Target specification for the build. Some values can be excluded
Formatting: <code>platform:compiler:sdk_version:deployment_version</code>
|
|
|-
| SYSROOT
| Root directory of the SDK you want to build this project with.
e.g. <code>$(THEOS)/sdks/iPhoneOS11.2.sdk</code>
 
This value is only necessary if you need to build your project against a specific SDK
| <code>$(THEOS)/SDKs/iPhoneOS<sdk_version>.sdk</code>
|
|-
| TWEAK_NAME
| In _Tweak_ projects, the name of this project.
|  
|  
| Theos will look for <TWEAK_NAME>.plist in your project directory, so ensure it shares the name defined here
|-
| $(TWEAK_NAME)_FILES
| A list of files to compile for the project. .x* files will be preprocessed via logos before compilation
Example value: <code>Tweak.xm AnotherFileWithHooks.x MyCoolObjcClass.m </code>
|  
|  
| shellscript macros can be used to include large amounts of files without having to manually type all of them.
|-
| $(TWEAK_NAME)_GENERATOR
| Specify the hooking generator for Logos. Possible values are <code>MobileSubstrate</code> and <code>internal</code> and are case-sensitive.
Example:</br>
<code>$(TWEAK_NAME)_GENERATOR = internal</code>
| <code>MobileSubstrate</code>
|
|-
|-
| <code>TARGET</code>
| THEOS_BUILD_DIR
| Target specification for the build. Some values can be obviated. Formatting: platform:compiler:sdk_version:deployment_version
| Packages will be placed in the specified directory
| local machine platform, gcc, 3.0 and 3.0
| <code>.</code>
|  
|  
|-
| DEBUG
| Set to 1 to enable debug mode.
| <code>undefined</code>
|
|}
</div>
=== Installation ===
<div style="overflow-x: scroll;">
{| class="wikitable" style="max-width: 100%; overflow-x: scroll;"
! Variable name
! Description
! Default value
! Notes
|-
| THEOS_DEVICE_IP
| IP used to install packages to a remote device.
|
| (Can also be the name of a host defined in ~/.ssh/config)
|-
| THEOS_DEVICE_PORT
| Port used to install packages to a remote device.
|
|
|-
| INSTALL_TARGET_PROCESSES
| Specify a list of processes to reload upon installation.
Example:<br/>
<code>INSTALL_TARGET_PROCESSES = SpringBoard Spotlight</code>
|
|
|-
| TARGET_INSTALL_REMOTE
| Should Packages be installed locally?
| 1, if THEOS_DEVICE_IP is set
| Leaving THEOS_DEVICE_IP blank when building on-device should install packages locally.
|-
| THEOS_DEVICE_USER
| User to log in as when installing the package
| root
| You shouldn't ever need to worry about this.
|-
| PREINSTALL_TARGET_PROCESSES
| Space delimited list of processes to unload before installation
|
|
|}
</div>
== Theos directories ==
''This list is incomplete. You can help by expanding it. [https://github.com/DHowett/theos/blob/master/documentation/makefiles.docbook From here]?''
{| class="wikitable"
|-
! Path
! Description
! Notes
|-
| <code>layout</code>
| Acts as the root directory for the target device. Useful for Maintainer scripts and placing resources outside the project install path.
|
|-
| <code>layout/DEBIAN</code>
| Directory inside layout folder where one can place [https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html maintainer scripts] to execute commands upon installation or removal.
| See https://wiki.debian.org/MaintainerScripts
|}
|}


[[Category:Development Tools]]
[[Category:Development Tools]]

Revision as of 14:02, 29 December 2021

Languages: English • Deutsch

Theos is a cross-platform suite of development tools for managing, developing, and deploying iOS software without the use of Xcode. It is an important tool for people building extensions (tweaks) for jailbroken iOS; most extension developers use Theos.

Overview

The Theos suite of tools consists of a handful of important components:

  • A project templating system (NIC), which creates ready-to-build empty projects for varying purposes
  • A robust build system driven by GNU Make, capable of directly creating .deb packages for distribution in Cydia
  • Logos, a built-in preprocessor-based library of directives designed to make MobileSubstrate extension development easy

Theos is primarily used for jailbreak-centric iOS development (such as MobileSubstrate extensions, PreferenceLoader bundles, and applications intended for distribution in Cydia), but can be used for other types of projects as well. This can be helpful for someone wishing to develop an iPhone SDK-based application without using Mac OS X or Xcode to do so, as Theos can be used on Linux and iOS as well.

Theos also includes Logify, which accepts a class header and generates a MobileSubstrate extension which hooks all of that class's methods, printing log messages when they are called. This helps a hook developer see when certain methods are invoked during use.

How to start using Theos

See Installation.

This Stack Overflow answer may also be helpful.

For reference, check out this Theos documentation by theiostream.

Theos variables

You can configure Theos by setting variables in a project's Makefile or having them exported as environment variables (affecting all your projects).

Appending export before a variable will cause the variable to affect all subprojects as well. This is very useful for certain variables such as SYSROOT and TARGET

This list is incomplete. You can help by expanding it. From here?

Building

Variable name Description Default value Notes
THEOS The directory where Theos is installed on your machine. It is platform dependent
PACKAGE_VERSION The current build's number $(THEOS_PACKAGE_BASE_VERSION)-$(VERSION.INC_BUILD_NUMBER) [1]

PACKAGE_VERSION=$(THEOS_PACKAGE_BASE_VERSION) Can be used to disable debug build numbers

ARCHS List of architectures to build for.

Possible values: i386 x86_64 armv6 armv7 armv7s armv7f armv7v arm64 arm64e

armv7 arm64 arm64e arm64e devices in most cases can run arm64 binaries.

PreferenceLoader, however, cannot typically load arm64 bundles on arm64e devices.

TARGET Target specification for the build. Some values can be excluded

Formatting: platform:compiler:sdk_version:deployment_version

SYSROOT Root directory of the SDK you want to build this project with.

e.g. $(THEOS)/sdks/iPhoneOS11.2.sdk

This value is only necessary if you need to build your project against a specific SDK

$(THEOS)/SDKs/iPhoneOS<sdk_version>.sdk
TWEAK_NAME In _Tweak_ projects, the name of this project. Theos will look for <TWEAK_NAME>.plist in your project directory, so ensure it shares the name defined here
$(TWEAK_NAME)_FILES A list of files to compile for the project. .x* files will be preprocessed via logos before compilation

Example value: Tweak.xm AnotherFileWithHooks.x MyCoolObjcClass.m

shellscript macros can be used to include large amounts of files without having to manually type all of them.
$(TWEAK_NAME)_GENERATOR Specify the hooking generator for Logos. Possible values are MobileSubstrate and internal and are case-sensitive.

Example:
$(TWEAK_NAME)_GENERATOR = internal

MobileSubstrate
THEOS_BUILD_DIR Packages will be placed in the specified directory .
DEBUG Set to 1 to enable debug mode. undefined

Installation

Variable name Description Default value Notes
THEOS_DEVICE_IP IP used to install packages to a remote device. (Can also be the name of a host defined in ~/.ssh/config)
THEOS_DEVICE_PORT Port used to install packages to a remote device.
INSTALL_TARGET_PROCESSES Specify a list of processes to reload upon installation.

Example:
INSTALL_TARGET_PROCESSES = SpringBoard Spotlight

TARGET_INSTALL_REMOTE Should Packages be installed locally? 1, if THEOS_DEVICE_IP is set Leaving THEOS_DEVICE_IP blank when building on-device should install packages locally.
THEOS_DEVICE_USER User to log in as when installing the package root You shouldn't ever need to worry about this.
PREINSTALL_TARGET_PROCESSES Space delimited list of processes to unload before installation

Theos directories

This list is incomplete. You can help by expanding it. From here?

Path Description Notes
layout Acts as the root directory for the target device. Useful for Maintainer scripts and placing resources outside the project install path.
layout/DEBIAN Directory inside layout folder where one can place maintainer scripts to execute commands upon installation or removal. See https://wiki.debian.org/MaintainerScripts