Skip to content

Commit

Permalink
READMEification
Browse files Browse the repository at this point in the history
  • Loading branch information
comex committed Mar 2, 2015
1 parent 1c1c09d commit fc183d6
Showing 1 changed file with 36 additions and 10 deletions.
46 changes: 36 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,52 @@
(lib)substitute
---------------

NOT EVEN ALPHA YET:

I wrote the below disclaimer assuming I would at least fix the boot process
before publishing this. I need to sleep, so that will happen tomorrow, but
for now it's simply broken. Please don't install the package yet, but feel
free to look at the code.

[3/1/15] Time flies whether or not you're having fun? "Tomorrow" became a
month, thanks to work, but at least we're getting somewhere.

ALPHA VERSION:

This code has not yet been tested anywhere near adequately and is probably
completely broken. Especially sharp edges are the iOS bootstrap stuff and
the disassemblers.

Please only try to install this on iOS 8 (TODO make this a dpkg
dependency). Before installing this, *please* install
[safestrat](https://github.com/comex/safestrat) so that if Substitute
breaks booting, you can SSH in and uninstall it.

Please reboot after installing and uninstalling. Magic rebootless
installation and uninstallation is planned, but not implemented yet!

Known issue: For some reason, unrestrict seems to not work until something
(amfid?) has loaded, which is a chicken and egg problem because amfid is
restricted; so restricted binaries might not load bundles. This only
affects a few binaries: afcd, amfid, installd, mobile_house_arrest.

Automatically entering a safe mode after SpringBoard crashes is not
implemented yet (though you can see the UI in progress in
ios-bootstrap/SafetyDance). Manually disabling the system by holding
volume up while booting (the same shortcut as Substrate) should work,
though.

...If you read through all that and still want to install, you can build it
on a Mac with:

make ARCH="-arch armv7 -arch arm64 -isysroot <xxx>" && ./script/gen-deb.sh

or use the deb I uploaded to GitHub.

Extensions should be placed in /Library/Substitute/DynamicLibraries, with
the same layout as Substrate. If you want to quickly test whether an
existing Substrate extension works with Substitute, you can run

install_name_tool -change \
/Library/Frameworks/CydiaSubstrate.framework/CydiaSubstrate \
/usr/lib/libsubstitute.0.dylib \
extension.dylib

and move it to the new directory.

Substitute is a system for modifying code at runtime by substituting custom
implementations for arbitrary functions and Objective-C methods. It is also a
Free Software substitute for [Cydia Substrate](http://www.cydiasubstrate.com).
Expand All @@ -29,12 +55,13 @@ It currently has full support for iOS and limited support for OS X; in the

License: LGPLv2.1+ with optional extra permissiveness; see LICENSE.txt

Note: x86 support should be functional now, although I haven't tested it much.

Substitute compared to Substrate
================================
* `+` Free software, so you can actually use it somewhere other than iOS or
Android, e.g. by bundling whatever parts of it you need with your app.
(Well, you could if it didn't lack x86 support, which will be fixed
quite soon.) See below for more on this.
See below for more on this.
* `+` More sophisticated, partially automatically generated disassemblers,
which handle a larger portion of the space of possible PC-relative
instructions that might be found in a patch target function - though I'm
Expand Down Expand Up @@ -68,7 +95,6 @@ Todo list (approx. priority order)
- iOS: safe mode
- iOS: ensure re-patching launchd (for upgrades) works
- iOS: install without reboot
- x86
- On-the-fly hooking and unhooking support:
- support for optimistically trying to unhook, in the hope that no further modifications were made to that memory
- some API to load/unload from all existing processes
Expand Down

0 comments on commit fc183d6

Please sign in to comment.