source: trunk/Cocoa/F-Script Anywhere/Source/Read Me@ 437

Last change on this file since 437 was 412, checked in by Nicholas Riley, 17 years ago

Fewer warnings and extraneous build settings.

File size: 9.4 KB
RevLine 
[409]1F-Script Anywhere 2.0d2 [24 February 2008]
2=======================
[7]3
4Add a F-Script interpreter to Cocoa applications dynamically.
5
[409]6Written by Nicholas Riley <mailto:fsa@sabi.net> and Robert Chin.
[7]7Obtain updates from <http://web.sabi.net/nriley/software/>.
8
9
10WHAT IS IT?
11-----------
12
[14]13Ever wanted to inspect a Cocoa applicationÕs objects from the inside?
[7]14Frustrated with using GDB to debug Objective-C?
15
16You need F-Script Anywhere! (with apologies to Guido van Rossum)
17
18
19INSTALLATION
20------------
21
22Install F-Script; you can download it at <http://www.fscript.org/>.
23In particular, make sure the framework is installed in a Frameworks
24directory, such as /Library/Frameworks or ~/Library/Frameworks.
25
[409]26F-Script Anywhere 2.0d2 was tested with FScript.framework 2.0a2 and
27Mac OS X 10.5.2 (9C31). If you are using an earlier F-Script version,
28please upgrade. F-Script Anywhere 2.0 requires Mac OS X 10.5 or
29later; if you're using Mac OS X 10.4, download F-Script 1.3.5
30(20070421) which includes F-Script Anywhere 1.3.
[7]31
32USAGE
33-----
34
35Open the F-Script Anywhere application. Pick a Cocoa application from
36the list and click Install or press return. F-Script Anywhere will
37either install itself in that application, give you an error message,
38or crash. (Hopefully not the latter!)
39
40Switch to the application, and you should find a ÒFSAÓ menu there.
41Select ÒNew F-Script WorkspaceÓ to display a F-Script workspace.
42This behaves like any other workspace, except it's executing within
43the context of the application.
44
45You can also install F-Script Anywhere by using its dock menu. If
46the frontmost application is a Cocoa application, just pick ÒInstallÉÓ
47from the menu and F-Script Anywhere will install in that application.
48If F-Script Anywhere canÕt install, the menu item will tell you so,
49or F-Script AnywhereÕs icon will bounce to indicate a pending sheet
50explaining the problem.
51
[153]52To remove F-Script Anywhere from an application, quit the application.
53Because of limitations in Apple's Objective-C runtime, it is
54impossible to remove F-Script Anywhere while the application is
55running.
[7]56
57
58BUILDING
59--------
60
61The source to F-Script Anywhere is included. It has a number of
62dependencies.
63
641. Install FScript.framework (see above).
65
[409]662. In the "Darwin source" directory, check out Darwin's cctools from
67 <http://www.opensource.apple.com/>, untar it and rename the
68 directory to "cctools". cd to the libstuff directory and type
69 'make RC_CFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch i386 -arch ppc" RC_XBS=YES dynamic'.
[7]70
[409]713. Put a version of FScript.framework into the Source folder. This
72 is used for the F-Script framework auto installer.
[229]73
[409]744. Open 'F-Script Anywhere.xcodeproj' in Xcode and build the Application
[153]75 target. This target depends on the Bundle and Bundle Loader
76 targets, so you don't need to build them separately. You
77 shouldnÕt see any errors or warnings, and the F-Script Anywhere
78 application (as well as two bundles, which you can ignore because
79 they are copied into the application bundle) will appear in the
80 build product directory.
[7]81
82If you have any problems building F-Script Anywhere, please let me
83know.
84
85
86FREQUENTLY ASKED QUESTIONS
87--------------------------
88
89Q. What is F-Script?
90
91A. F-Script is a dialect of Smalltalk which includes a bridge to
92 the Objective-C runtime on Mac OS X. It's open-source, and
93 very nice. Its author, Philippe Mougin, has written several
94 articles on it, and documentation is available from the
95 F-Script Web site:
96
97 <http://www.fscript.org/>
98
99
100Q. How do you access user interface elements?
101
[14]102A. One way is to access a window and its views programmatically:
[7]103
104 > app := NSApplication sharedApplication
105
106 > windows := app windows
107
108 > windows
109 NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
110 0x1f0cea0>}
111
112 > windows collect: [:each | each title]
113
114 error: an instance of NSWindow does not respond to "collect:"
115
116 (...a gentle reminder that this is not Smalltalk...)
117
118 > windows title
119 {'F-Script', '', ''}
120
121 (...but F-Script has some tricks of its own...)
122
123 > fsw := windows at: 0
124
125 > fswView := fsw contentView
126
[14]127 To open an F-Script object browser on fswView, type:
128
129 > sys browse: fswView
130
131 Or, click ÒNew Browser: Object...Ó, then click on fswView.
132 Click 'subviews' in the message list. You can use 'subviews'
[7]133 repeatedly on container views if needed.
134
135
[14]136Q. ThatÕs too hard, especially all that scrolling.
[7]137
[16]138A. If you need to access a view (such as a button or text field), menu or
[14]139 window, youÕre in luck. Click in an F-Script workspace window, then
[409]140 click or choose ÒBrowser for TargetÉÓ from the ÒFSAÓ menu.
[14]141 Follow the instructions in the window to select a user interface
142 element, view it in an object browser or assign it to a variable.
[7]143
[153]144 The F-Script object browser now provides a similar feature: click the
[409]145 ÒSelect ViewÓ button.
[7]146
[14]147
[16]148Q. I donÕt like F-ScriptÕs syntax. I don't like the object browser.
149 I donÕt like you either.
150
[14]151A. I didnÕt write F-Script. Please address your questions to
152 F-ScriptÕs author or the F-Script mailing list.
[7]153
154 <http://www.fscript.org/contacts.htm>
155
156 Oh, and get lost.
157
158
159Q. My question isn't answered here.
160
161A. That's not a question. But if you have a question about F-Script
162 Anywhere, a suggestion or a bug to report, please email it to me at
[409]163 <fsa@sabi.net>. I'll get back to you as soon as my schedule will
164 allow. Thanks!
[7]165
166
167VERSION HISTORY
168---------------
[409]1692.0 - unreleased - Injectable into Cocoa garbage collected apps
[412]170 (64-bit applications are not yet supported)
[409]171 - Requires F-Script 2.0 and Mac OS X 10.5
1721.3.1 - 17 October 2007 - Compatible with Mac OS X 10.5
1731.3 - 5 May 2006 - Fixed leaking of file handles
[227]174 - Removed deprecated F-Script functions
175 - New associate option that automatically
176 brings up a new browser without an
177 interpreter window
178 - Auto-inject feature
[153]1791.2 - 5 January 2004 - fixed window behavior on startup, delaying
180 display until launch is complete
181 - replaced libPatch with mach_inject and
182 SCPatch: provides improved compatibility
183 with Mac OS X 10.3 (doesn't crash randomly
184 any more!)
185 - no longer requires F-Script Anywhere
186 application to be running while installed
187 in applications
188 - F-Script Anywhere can now be installed in
189 itself
190 - check for F-Script version on startup
191 - use new, documented F-Script API for
192 identifier validation in associate window
193 - prepared for localization
194 - enable "Install" button when appropriate at
195 application startup
196 - fixed focus ring "flicker" on Mac OS X 10.3
[16]1971.1.5 - 1 October 2002 - better identify Cocoa vs. Carbon applications
198 on Jaguar; added hierarchical window list to
199 FSA menu; fixed startup crash on Puma with
200 certain Carbon CFM applications
2011.1.4 - 25 August 2002 - fixed miscellaneous Jaguar issues; worked
202 around broken application quit notifications;
203 added unique interpreter/associate window titles
2041.1.3 - 24 July 2002 - added bullseye-menu targeting cursor; added menu
205 association; work around bug by stopping capture
206 on suspend; added delegate, data source, target,
207 cell selection for views; window controller for
208 windows
[14]2091.1.2 - 18 July 2002 - fixed more startup issues with list management;
[7]210 properly scale icons of apps which have no
[14]211 small icons; added user interface association
[7]2121.1.1 - 3 July 2002 - fixed inefficiencies responsible for long
213 startup time; reorganized Window menu; support
214 paths to applications which contain non-ASCII
215 characters [Martin HŠcker]; added sample code
216 to grab UI elements [Philippe Mougin]; cleaned
217 up code and distribution layout
2181.1 - 25 April 2002 - revised terminology; updated for F-Script 1.2;
219 zoom to fit in application list; added help
220 tags for workspace; focus workspace initially
2211.0.2 - (unreleased) - minor cleanups, added error messages, updated
222 scroll view component for faster UI response,
223 removed help menu item because it's useless
2241.0.1 - 1 March 2002 - corrected message for error 5; libPatch 1.2;
225 fixed endless confirmation on window close
2261.0.1d1 1 February 2002 - added error messages
2271.0 - 3 February 2002 - added dock menu, URL launching, check for
228 F-Script framework, floating window,
229 application name in interpreter window title,
230 fixed bugs, cleaned up error handling,
231 licensed under the GPL (because of ASM code),
232 packaged, added Read Me file and license
2331.0d1 - 1 February 2002 - proof of feasibility, private test version
234
235
236CREDITS
237-------
238
239Thanks to the following people for their software and generous
240donations of source code:
241
242Philippe Mougin, for F-Script
[409]243Robert Chin, for maintenance and Intel/Leopard porting
244Jonathan 'Wolf' Rentsch and Bertrand GuihŽneuf, for mach_inject
[153]245Jon Gotow, for SCPatch and lots of advice
[7]246Mike Ferris, for TextExtras
247Apple, for Darwin
[153]248Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.