Getting Started: Difference between revisions

From iPhone Development Wiki
m (updated the page with actual working links to some more up to date working resources. only the ones with broken links)
 
(7 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== Learning C and Objective-C ==
= Learning C and Objective-C =


If you have no programming experience and you want to write extensions/tweaks, you'll need to learn a lot about Objective-C and developing ordinary apps for iOS. (If you'd like to first try modifying code in simple ways to explore some possibilities, you can try the paid package [http://getflex.co/ Flex], on the BigBoss repository in Cydia.)
If you have no programming experience and you want to write extensions/tweaks, you'll need to learn a lot about Objective-C and developing ordinary apps for iOS. (If you'd like to first try modifying code in simple ways to explore some possibilities, you can try the paid package [http://getflex.co/ Flex], on the BigBoss repository in Cydia.)


To give you a taste, [https://www.codeschool.com/paths/ios Code School has an iOS programming course for beginners], with a [https://www.codeschool.com/courses/try-objective-c free interactive guide to getting started with Objective-C]. You can also try the [http://www.codecademy.com/ free courses offered by Codecademy] - they're not about Objective-C or iOS, but they can give you a general sense of what programming is like.
To give you a taste, [https://drive.google.com/drive/folders/17k9xjQEt1Vy6gF3WeDWjBn_TsSOBgCCMhas heres an insane amount of Free iOS Programming videos in a google drive], with a [https://www.tutorialspoint.com/objective_c/index.htm free interactive guide to getting started with Objective-C]. You can also try the [http://www.codecademy.com/ free courses offered by Codecademy] - they're not about Objective-C or iOS, but they can give you a general sense of what programming is like.


For further study:
For further study:
Line 9: Line 9:
* Apple's developer documentation - see [https://developer.apple.com/xcode/ the Xcode page] and [https://developer.apple.com/library/ios/referencelibrary/GettingStarted/RoadMapiOS/index.html#//apple_ref/doc/uid/TP40011343 Start Developing iOS Apps Today].
* Apple's developer documentation - see [https://developer.apple.com/xcode/ the Xcode page] and [https://developer.apple.com/library/ios/referencelibrary/GettingStarted/RoadMapiOS/index.html#//apple_ref/doc/uid/TP40011343 Start Developing iOS Apps Today].


* Videos: [https://itunes.apple.com/us/course/developing-ios-7-apps-for/id733644550 Stanford's "Developing iOS 7 Apps for iPhone and iPad" class on iTunes U] and [http://thenewboston.org/list.php?cat=33 The New Boston video tutorials].
* Videos: [https://itunes.apple.com/us/course/developing-ios-7-apps-for/id733644550 Stanford's "Developing iOS 7 Apps for iPhone and iPad" class on iTunes U] and [https://www.thenewboston.com/videos.php?cat=33 The New Boston video tutorials]. There are more recommendations for videos and blogs in [https://www.codementor.io/learn-ios-development this list from CodeMentor].


* Books: [http://www.amazon.com/Programming-Objective-C-Edition-Developers-Library/dp/0321967607 ''Programming in Objective-C'' by Stephen G. Kochan] and [http://www.amazon.com/Objective-C-Programming-Ranch-Guide-Guides/dp/0321706285 ''Objective-C Programming: The Big Nerd Ranch Guide'' by Aaron Hillegass].
* Books: [http://www.amazon.com/Programming-Objective-C-Edition-Developers-Library/dp/0321967607 ''Programming in Objective-C'' by Stephen G. Kochan], [http://www.amazon.com/Objective-C-Programming-Ranch-Guide-Guides/dp/032194206X ''Objective-C Programming: The Big Nerd Ranch Guide'' by Aaron Hillegass], and [http://www.amazon.com/iOS-Programming-Ranch-Guide-Guides/dp/0321942051 ''iOS Programming: The Big Nerd Ranch Guide'' by Aaron Hillegass, Joe Conway, and Christian Keur].


* Forums: [http://iphonedevsdk.com/ unofficial iPhone Dev SDK forum] and [http://stackoverflow.com/questions/tagged/ios Stack Overflow].
* Forums: [http://iphonedevsdk.com/ unofficial iPhone Dev SDK forum] and [http://stackoverflow.com/questions/tagged/ios Stack Overflow].
Line 19: Line 19:
Ideally you'll get to a point where you're comfortable writing and running code for iOS. If you're already there, definitely keep reading!
Ideally you'll get to a point where you're comfortable writing and running code for iOS. If you're already there, definitely keep reading!


== Setting up Theos ==
= Setting up Theos =


Follow [[Theos/Setup]] to set up your [[Theos]] environment by installing Theos and creating your first project. These links may also be helpful: [http://stackoverflow.com/questions/6118814/is-there-anywhere-where-i-could-start-mobilesubstrate-tweaks-programming/11553722#11553722 guide on Stack Overflow], [https://github.com/theiostream/theos-ref this Theos documentation by theiostream], and [https://github.com/r-plus/dotfiles/blob/master/install_theos.sh Theos Install Script].
Follow [[Theos/Setup]] to set up your [[Theos]] environment by installing Theos and creating your first project. These links may also be helpful: [http://stackoverflow.com/questions/6118814/is-there-anywhere-where-i-could-start-mobilesubstrate-tweaks-programming/11553722#11553722 guide on Stack Overflow], [https://github.com/theiostream/theos-ref this Theos documentation by theiostream], and [https://github.com/r-plus/dotfiles/blob/master/install_theos.sh Theos Install Script].
Line 25: Line 25:
You'll probably also want to read more about [[MobileSubstrate|Cydia Substrate]] - see [http://www.cydiasubstrate.com/id/264d6581-a762-4343-9605-729ef12ff0af/ saurik's Substrate documentation].
You'll probably also want to read more about [[MobileSubstrate|Cydia Substrate]] - see [http://www.cydiasubstrate.com/id/264d6581-a762-4343-9605-729ef12ff0af/ saurik's Substrate documentation].


== Finding example projects ==
= Finding example projects =


Here is a list of just a few of the many open source projects that can be used as examples: [[Open Source Projects]].
Here is a list of just a few of the many open source projects that can be used as examples: [[Open Source Projects]].
Line 41: Line 41:
Using the above code will search GitHub for all files with the extension .xm (because Theos by default creates a Tweak.xm file when creating a new tweak). The example above will result in finding [https://github.com/search?q=extension%3Axm+SBAwayController&ref=cmdform tweaks that reference SBAwayController]. Not all developers use the .xm file extension, but a large number do, and this will help you in finding those examples.
Using the above code will search GitHub for all files with the extension .xm (because Theos by default creates a Tweak.xm file when creating a new tweak). The example above will result in finding [https://github.com/search?q=extension%3Axm+SBAwayController&ref=cmdform tweaks that reference SBAwayController]. Not all developers use the .xm file extension, but a large number do, and this will help you in finding those examples.


== Looking at frameworks, classes, and processes ==
= Looking at frameworks, classes, and processes =


To figure out what code to modify, you'll want to explore around iOS and apps.
To figure out what code to modify, you'll want to explore around iOS and apps.
Line 47: Line 47:
You can extract Objective-C class interfaces with [http://stevenygard.com/projects/class-dump/ class-dump], [https://code.google.com/p/networkpx/wiki/class_dump_z class_dump_z], or [https://github.com/limneos/classdump-dyld classdump-dyld]. Remember that the resulting files are not the original headers, so use them with caution.
You can extract Objective-C class interfaces with [http://stevenygard.com/projects/class-dump/ class-dump], [https://code.google.com/p/networkpx/wiki/class_dump_z class_dump_z], or [https://github.com/limneos/classdump-dyld classdump-dyld]. Remember that the resulting files are not the original headers, so use them with caution.


You can also find other developers have done this process for many frameworks and compiled their work into github repositories. Here's two of them:
You can also find other developers have done this process for many frameworks and compiled their work into github repositories (e.g. [https://github.com/nst/iOS-Runtime-Headers iOS-Runtime-Headers]).
* [https://github.com/nst/iOS-Runtime-Headers iOS-Runtime-Headers]
* [https://github.com/rpetrich/iphoneheaders/ iphoneheaders]


For further help, take a look at [https://www.youtube.com/watch?v=aabrNwI1-Go Finding classes/methods and using them] by Sassoty.
For further help, take a look at [https://www.youtube.com/watch?v=aabrNwI1-Go Finding classes/methods and using them] by Sassoty.
Line 57: Line 55:
See [[Notifications]] for information about observing and posting notifications informing observers of events within a process and for IPC purposes, for example.
See [[Notifications]] for information about observing and posting notifications informing observers of events within a process and for IPC purposes, for example.


== Prototyping a tweak ==
= Prototyping a tweak =


You can use [[Cycript]] to explore running processes. Check out the [http://www.cycript.org/manual/ official manual], especially the [http://www.cycript.org/manual/#5719c21b-68d2-4647-9d97-bcdbeea7f929 section about process injection]. For a demo, see [http://www.youtube.com/watch?v=Ox09rWJTuCA&feature=youtu.be Adam Bell's JailbreakCon talk] ([https://github.com/b3ll/JailbreakCon2013 example code and slides]).
You can use [[Cycript]] to explore running processes. Check out the [http://www.cycript.org/manual/ official manual], especially the [http://www.cycript.org/manual/#5719c21b-68d2-4647-9d97-bcdbeea7f929 section about process injection]. For a demo, see [http://www.youtube.com/watch?v=Ox09rWJTuCA&feature=youtu.be Adam Bell's JailbreakCon talk] ([https://github.com/b3ll/JailbreakCon2013 example code and slides]).


== Building your tweak ==
= Building your tweak =


After prototyping you will want to make your tweak into a project to build it and debug it. To achieve this you will most likely use [[Theos]]. It is available for different platforms including iOS and Mac OS, and, to a certain extent, Linux. On Mac OS you can use Xcode's command line tools, but for the other platforms you should use a toolchain. On iOS there are two available toolchains ([[On-device toolchains]]), and [http://coolstar.org/iOSToolchainOnWindows.html there is a project for Windows].
After prototyping you will want to make your tweak into a project to build it and debug it. To achieve this you will most likely use [[Theos]]. It is available for different platforms including iOS and Mac OS, and, to a certain extent, Linux. On Mac OS you can use Xcode's command line tools, but for the other platforms you should use a toolchain. On iOS there are two available toolchains ([[On-device toolchains]]), and [http://coolstar.org/iOSToolchainOnWindows.html there is a project for Windows].
Line 67: Line 65:
To learn about setting up your package's control file, see [http://www.saurik.com/id/7 saurik's article on building packages]. If you need to list dependencies or conflicting packages, Debian's packaging manual may be useful (because Cydia packaging is based on Debian packaging): [https://www.debian.org/doc/debian-policy/ch-relationships.html#s-depsyntax Syntax of relationship fields], [https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps Dependencies], [https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts Conflicts] -- or if you're submitting this package to a default repository, you can just ask your repository maintainer for help with this.
To learn about setting up your package's control file, see [http://www.saurik.com/id/7 saurik's article on building packages]. If you need to list dependencies or conflicting packages, Debian's packaging manual may be useful (because Cydia packaging is based on Debian packaging): [https://www.debian.org/doc/debian-policy/ch-relationships.html#s-depsyntax Syntax of relationship fields], [https://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps Dependencies], [https://www.debian.org/doc/debian-policy/ch-relationships.html#s-conflicts Conflicts] -- or if you're submitting this package to a default repository, you can just ask your repository maintainer for help with this.


== Debugging ==
= Debugging =


See [[Debugging on iOS 7]] for how to run gdb and/or lldb.
See [[Debugging on iOS 7]] for how to run gdb and/or lldb.
Line 77: Line 75:
[http://sharedinstance.net/2014/02/debugging-memory-issues/ Debugging memory issues in Substrate tweaks]
[http://sharedinstance.net/2014/02/debugging-memory-issues/ Debugging memory issues in Substrate tweaks]


== A few problems you may run into while getting started ==
= A few problems you may run into while getting started =


''Problem: Whenever I run programs I compile with your toolchain, they are immediately "Killed". I hate Apple :(.''<br/>
''Problem: Whenever I run programs I compile with your toolchain, they are immediately "Killed". I hate Apple :(.''<br/>
Line 95: Line 93:
exec "${dir}"/MyProgram_ "$@"</source>
exec "${dir}"/MyProgram_ "$@"</source>


== Publishing your package in a default repository ==
= Publishing your package in a default repository =


When you've completed a project, you may want to submit it to one of Cydia's default repositories (sources) for distribution.
When you've completed a project, you may want to submit it to one of Cydia's default repositories (sources) for distribution.
Line 111: Line 109:
For questions about the Cydia Store system for paid packages, you can ask your repository manager; they've helped many developers figure this out. See also: [[Cydia Store Integration]].
For questions about the Cydia Store system for paid packages, you can ask your repository manager; they've helped many developers figure this out. See also: [[Cydia Store Integration]].


== Some guides on other sites ==
= Some guides on other sites =


* [http://www.youtube.com/playlist?list=PLFfSWxWm1or7fqB340OYjF8deWRWSDytc YouTube playlist that teaches you how to write Cydia tweaks] by Sassoty + [https://www.youtube.com/watch?v=sH60TbYkyYs&list=PLFfSWxWm1or4JPINH2_bCHoG2kgGuC0_6 more videos about learning to use libraries].
* [http://www.youtube.com/playlist?list=PLFfSWxWm1or7fqB340OYjF8deWRWSDytc YouTube playlist that teaches you how to write Cydia tweaks] by Sassoty + [https://www.youtube.com/watch?v=sH60TbYkyYs&list=PLFfSWxWm1or4JPINH2_bCHoG2kgGuC0_6 more videos about learning to use libraries].
Line 121: Line 119:
* [http://www.reddit.com/r/jailbreak/comments/20nxy8/flex_to_mobilesubstrate_a_beginners_guide_to/ Flex to MobileSubstrate: A beginner's guide to making a tweak]
* [http://www.reddit.com/r/jailbreak/comments/20nxy8/flex_to_mobilesubstrate_a_beginners_guide_to/ Flex to MobileSubstrate: A beginner's guide to making a tweak]
* [http://www.reddit.com/r/jailbreak/comments/1o4e2a/i_made_a_really_really_really_boring_video_of_me/ "I made a really really (really) boring video of me setting up a basic jailbreak-development-environment from scratch."]
* [http://www.reddit.com/r/jailbreak/comments/1o4e2a/i_made_a_really_really_really_boring_video_of_me/ "I made a really really (really) boring video of me setting up a basic jailbreak-development-environment from scratch."]
* [https://github.com/iosre/iOSAppReverseEngineering The free book iOS App Reverse Engineering] is by far the most serialized and thorough tutorial of jailbreak development and iOS reverse engineering.


Also check out the [[list of development blogs]] for more writing by tweak developers.
Also check out the [[list of development blogs]] for more writing by tweak developers.


== Theos challenges ==
= Theos challenges =


This section is a set of tweaks/apps that can be created with Theos for new or experienced developers to practice with.
This section is a set of tweaks/apps that can be created with Theos for new or experienced developers to practice with.
Line 152: Line 151:


If you're interested in ideas for something else to build, the [http://www.reddit.com/r/jailbreak/search?q=request&sort=new&restrict_sr=on "Request" tag on /r/jailbreak] has lots of tweak ideas from real people.
If you're interested in ideas for something else to build, the [http://www.reddit.com/r/jailbreak/search?q=request&sort=new&restrict_sr=on "Request" tag on /r/jailbreak] has lots of tweak ideas from real people.
= See also =
* [[Next Steps After Getting Started]]
* [[Getting Help]]
[[Category:Getting Started]]

Latest revision as of 15:50, 3 January 2024

Learning C and Objective-C

If you have no programming experience and you want to write extensions/tweaks, you'll need to learn a lot about Objective-C and developing ordinary apps for iOS. (If you'd like to first try modifying code in simple ways to explore some possibilities, you can try the paid package Flex, on the BigBoss repository in Cydia.)

To give you a taste, heres an insane amount of Free iOS Programming videos in a google drive, with a free interactive guide to getting started with Objective-C. You can also try the free courses offered by Codecademy - they're not about Objective-C or iOS, but they can give you a general sense of what programming is like.

For further study:

It's good to learn some C too; it'll give you a better foundation for learning Objective-C. You'll want to know about pointer arithmetic, the Objective-C runtime, buffer overflows, bitwise operations, the model-view-controller pattern, etc.

Ideally you'll get to a point where you're comfortable writing and running code for iOS. If you're already there, definitely keep reading!

Setting up Theos

Follow Theos/Setup to set up your Theos environment by installing Theos and creating your first project. These links may also be helpful: guide on Stack Overflow, this Theos documentation by theiostream, and Theos Install Script.

You'll probably also want to read more about Cydia Substrate - see saurik's Substrate documentation.

Finding example projects

Here is a list of just a few of the many open source projects that can be used as examples: Open Source Projects.

For some simple example projects you can build with Theos, see codyd51's Theos Examples.

Not finding what you are looking for? Try searching through GitHub for iOS Tweaks with a simple trick, "extension:xm".

Example:

extension:xm SBAwayController

Using the above code will search GitHub for all files with the extension .xm (because Theos by default creates a Tweak.xm file when creating a new tweak). The example above will result in finding tweaks that reference SBAwayController. Not all developers use the .xm file extension, but a large number do, and this will help you in finding those examples.

Looking at frameworks, classes, and processes

To figure out what code to modify, you'll want to explore around iOS and apps.

You can extract Objective-C class interfaces with class-dump, class_dump_z, or classdump-dyld. Remember that the resulting files are not the original headers, so use them with caution.

You can also find other developers have done this process for many frameworks and compiled their work into github repositories (e.g. iOS-Runtime-Headers).

For further help, take a look at Finding classes/methods and using them by Sassoty.

See Reverse Engineering Tools for detailed information about these tools and many others, including Logify.

See Notifications for information about observing and posting notifications informing observers of events within a process and for IPC purposes, for example.

Prototyping a tweak

You can use Cycript to explore running processes. Check out the official manual, especially the section about process injection. For a demo, see Adam Bell's JailbreakCon talk (example code and slides).

Building your tweak

After prototyping you will want to make your tweak into a project to build it and debug it. To achieve this you will most likely use Theos. It is available for different platforms including iOS and Mac OS, and, to a certain extent, Linux. On Mac OS you can use Xcode's command line tools, but for the other platforms you should use a toolchain. On iOS there are two available toolchains (On-device toolchains), and there is a project for Windows.

To learn about setting up your package's control file, see saurik's article on building packages. If you need to list dependencies or conflicting packages, Debian's packaging manual may be useful (because Cydia packaging is based on Debian packaging): Syntax of relationship fields, Dependencies, Conflicts -- or if you're submitting this package to a default repository, you can just ask your repository maintainer for help with this.

Debugging

See Debugging on iOS 7 for how to run gdb and/or lldb.

The System Log article on TheiPhoneWiki has useful tips about accessing the device's syslog.

The Crash Reporter package in Cydia is a convenient way to grab crash reports, and it's helpful to run symbolicate (also available in Cydia) on crash reports to get more detail.

Debugging memory issues in Substrate tweaks

A few problems you may run into while getting started

Problem: Whenever I run programs I compile with your toolchain, they are immediately "Killed". I hate Apple :(.
Solution: iOS only wants to run signed code. Jailbreaks patch the signature verification out of the kernel, but you still need to at least add a valid CodeDirectory to the binary that contains SHA1 hashes of the executable. See Code Signing for a few ways to do this.

Problem: I tried copying a graphical program to the iPhone, and ran it from the command line. I am nearly 100% certain my program is correct, and I did your codesign instructions, but it doesn't work.
Solution: You can't run things from the command line, you have to run them from SpringBoard.

Problem: OK, but when I copied the file to /Applications it didn't even show up in SpringBoard.
Solution: iOS caches the Info.plist files of all installed applications in a centralized place. The fastest/best way to handle this cache is to install UIKit Tools and then run its uicache as mobile:

su mobile -c uicache

Problem: When I add setuid bits to my program, it no longer starts up and syslog doesn't seem to provide any useful information, either (True?).
Solution: I am not quite certain what is preventing this. However, it is easy to defeat: replace your program with a two line shell script that, in turn, runs your program. Example, maybe MyProgram (setuid) gets renamed to MyProgram_, and MyProgram (not setuid) becomes the script:

#!/bin/bash
dir=$(dirname "$0")
exec "${dir}"/MyProgram_ "$@"

Publishing your package in a default repository

When you've completed a project, you may want to submit it to one of Cydia's default repositories (sources) for distribution.

[Context about Cydia: Unlike the App Store, which is a centralized system, Cydia itself does not host/distribute packages - instead, Cydia is a way to browse and install packages from repositories. By default, Cydia comes with a list of good repositories (independently-owned but work closely with the makers of Cydia) - so if you want to distribute a package to the general audience of Cydia users, submitting it to a default repository is a good plan. If you use a default repository and want to sell your package, you can choose to use the Cydia Store system so that people have a simple way to purchase it. You can also choose to run your own repository (see Repository Management) and ask interested users to type your repository address into Cydia to get your package.]

These are your options for default repositories, with links to information about submitting:

If you aren't sure which to pick, look up what your favorite developers use, or ask other developers for suggestions (if you don't already know any other developers, IRC may be helpful). If you have questions, email is usually the best way to get in contact with repository managers.

For questions about the Cydia Store system for paid packages, you can ask your repository manager; they've helped many developers figure this out. See also: Cydia Store Integration.

Some guides on other sites

Also check out the list of development blogs for more writing by tweak developers.

Theos challenges

This section is a set of tweaks/apps that can be created with Theos for new or experienced developers to practice with.

Title Description Example Need Help?
LaunchNotifier Show a UIAlertView on the screen after any app has been launched. The title of the UIAlertView is the name of the app being opened. Example Guide
AskLaunch Show a UIAlertView after tapping an app, asking the user whether they want to launch it or not. Example
TransparentSBEditor Make the SpringBoard icons transparent while editing, instead of jittering. Example

If you're interested in ideas for something else to build, the "Request" tag on /r/jailbreak has lots of tweak ideas from real people.

See also