README.markdown
1## Description
2
3mach_override enables you to override ("patch") program- and system-supplied functions at runtime. You can fully replace functions with your implementations, or merely head- or tail-patch the original implementations to add functionality and/or work around bugs.
4
5## Must Be This Tall To Ride
6
7Dynamic function overriding is tricky business. You should be familiar with assembly and runtime calling conventions (ABIs) before using mach_override.
8
9mach_override is certainly not bug free and patches are extremely welcome, but the onus is on you when things don't work. Please don't file a bug report stating mach_override is crashing for you when you try to use it -- you have to be hard-core enough to debug the problem yourself.
10
11## Contributing
12
13Please base your work off the unstable branch. After making your changes please re-run `rake` to ensure it compiles cleanly and the tests pass. Then submit your Pull Request.
14
15## TODO
16
17* Test the entire matrix, not just the current ARCH that `gcc` defaults to:
18
19<table>
20 <tr>
21 <th>CC</th> <th>ARCH</th>
22 </tr>
23 <tr>
24 <td>gcc</td> <td>ppc</td>
25 </tr>
26 <tr>
27 <td>clang</td> <td>ppc</td>
28 </tr>
29 <tr>
30 <td>gcc</td> <td>i386</td>
31 </tr>
32 <tr>
33 <td>clang</td> <td>i386</td>
34 </tr>
35 <tr>
36 <td>gcc</td> <td>x86_64</td>
37 </tr>
38 <tr>
39 <td>clang</td> <td>x86_64</td>
40 </tr>
41</table>
42
43Obviously ppc can only be tested on ppc Macs or on 10.5 and 10.6 (Rosetta-supporting) Intel Macs.
44
45## Version History
46
47### mach_override 1.2: Aug 9 2012
48
49* [NEW] i386 and x86_64 support.
50
51* [CHANGE] Decoupled from mach_star. Most of folks were just using the side or the other of mach_star and this simplifies things (docs, tests).
52
53* [CHANGE] Threw away Xcode projects. Trying to get them to work across new and old system versions and Xcode versions is a fool's game. Now there's a Rakefile. Type `rake`. You've built and tested. Ta-da.
54
55### mach_star 1.1.1: Dec 18 2005
56
57* General Xcode 2.2 project cleanup. mach_star now includes `.xcodeproj` Xcode 2.2 project files for all of its projects. The old `.xcode` project files have been left in place, but they aren't maintained and may not work. Xcode 2.2 is the recommended mach_star development environment -- Xcode 2.1 had a bug with inter-project dependancies which would cause compilation failure. It works now again in Xcode 2.2.
58
59* Inter-project dependancies should working under Xcode 2.2. Any project you pick, you should just be able to hit the "Build" button and everything should Just Work™.
60
61* There was a stray reference to my username in one of the project, which causes compilation headaches for some folks.
62
63* Bug fix: in `mach_inject_bundle.c`'s `mach_inject_bundle_pid()` I no longer call `CFRelease()` on the framework bundle reference. Reported by Scott Kevill.
64
65* Added some explicit casts now required by gcc 4.
66
67* Added this document.
68
69### mach_star 1.1: Apr 06 2005
70
71* New package added: `mach_inject_bundle`. It has a private subproject: `mach_inject_bundle_stub`. The stub is a generic reusable implementation of the code that gets squirted across the address spaces, which was always tricky to write. `mach_inject_bundle` is an embeddable framework that wraps `mach_inject` and the stub with a simple fire-and-forget API.
72
73* The "DisposeWindowBeeperOverride" example is replaced by "DisposeWindow+Beep".
74
75* The "FinderDisposeWindowBeeperInjector" is replaced by "DisposeWindow+Beep_Injector".
76
77* All the text is now wrapped to 80 chars wide. Done to print nicely in Scott Knaster's [Hacking Mac OS X Tiger](http://www.amazon.com/exec/obidos/ASIN/076458345X). Probably will undo this word-wrap in the future. We all have widescreens nowadays, right? ;-)
78
79* Thanks to Jon Gotow for letting me peek at `SCPatch`, which I used as a guide for `mach_inject_bundle`. It saved me a bunch of time. Also thanks to Bob Ippolito for `CALL_ON_LOAD` assistance.
80
81### mach_star 1.0: Jun 18 2003
82
83* Initial release at MacHack 2003.