Theos: Difference between revisions

From iPhone Development Wiki
(Add _GENERATOR)
(4 intermediate revisions by 2 users not shown)
Line 25: Line 25:
== Theos variables ==
== 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).
You can configure Theos by setting variables in a project's Makefile or having them exported as environment variables (affecting all your projects).


''This list is incomplete. You can help by expanding it. [https://github.com/DHowett/theos/blob/master/documentation/makefiles.docbook From here]?''
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://github.com/theos/theos/wiki/Features From here]?''


{| class="wikitable"
<div style="overflow-x: scroll;">
|-
{| class="wikitable" style="max-width: 100%; overflow-x: scroll;"
! Variable name
! Variable name
! Description
! Description
Line 36: Line 38:
! Notes
! Notes
|-
|-
| <code>THEOS</code>
| THEOS
| The directory where Theos is installed on your machine. It is platform dependent
| The directory where Theos is installed on your machine. It is platform dependent
|  
|  
|  
|  
|-
|-
| <code>PACKAGE_VERSION</code>
| PACKAGE_VERSION
| The current build's number
| 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 arm64e</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>
|
|  
|  
| There are no working toolchains for arm64e for Linux or Windows yet.
arm64e devices in most cases can run arm64 binaries
|-
|-
| <code>TARGET</code>
| INSTALL_TARGET_PROCESSES
| Target specification for the build. Some values can be obviated.
| Specify a list of processes to reload upon installation.
Formatting: <code>platform:compiler:sdk_version:deployment_version</code>
Example:<br/>
| <code><local machine platform>:gcc:3.0:3.0</code>
<code>INSTALL_TARGET_PROCESSES = SpringBoard Spotlight</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>THEOS_DEVICE_IP</code>
| THEOS_DEVICE_IP
| IP used to install packages to a remote device.
| IP used to install packages to a remote device.
|  
|  
| (Can also be the name of a host defined in <code>~/.ssh/config</code>)
| (Can also be the name of a host defined in ~/.ssh/config)
|-
|-
| <code>THEOS_DEVICE_PORT</code>
| THEOS_DEVICE_PORT
| Port used to install packages to a remote device.
| Port used to install packages to a remote device.
|  
|  
|  
|  
|-
|-
| <code>THEOS_BUILD_DIR</code>
| THEOS_BUILD_DIR
| Packages will be placed in the specified directory
| Packages will be placed in the specified directory
| <code>.</code>
| <code>.</code>
|  
|  
|-
|-
| <code>DEBUG</code>
| DEBUG
| Set to 1 to enable debug mode.
| Set to 1 to enable debug mode.
| undefined
| <code>undefined</code>
|  
|  
|}
|}
</div>


== Theos directories ==
== Theos directories ==
Line 95: Line 136:
|-
|-
| <code>layout/DEBIAN</code>
| <code>layout/DEBIAN</code>
| Directory inside layout folder where one can place maintainer scripts[https://www.debian.org/doc/debian-policy/ch-maintainerscripts.html] to execute commands upon installation or removal.
| 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
| See https://wiki.debian.org/MaintainerScripts
|}
|}


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

Revision as of 17:22, 1 February 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?

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

INSTALL_TARGET_PROCESSES Specify a list of processes to reload upon installation.

Example:
INSTALL_TARGET_PROCESSES = SpringBoard Spotlight

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_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.
THEOS_BUILD_DIR Packages will be placed in the specified directory .
DEBUG Set to 1 to enable debug mode. undefined

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