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

Last change on this file since 370 was 230, checked in by rchin, 18 years ago

Auto installation of F-Script as requested by Philippe Mougin. We'll optimize the FSA framework package later (not sure if it would be a good idea to remove headers in framework, etc.)

File size: 10.3 KB
Line 
1F-Script Anywhere 1.2 [5 January 2004]
2=====================
3
4Add a F-Script interpreter to Cocoa applications dynamically.
5
6Written by Nicholas Riley <mailto:fsa@sabi.net>.
7Obtain updates from <http://web.sabi.net/nriley/software/>.
8
9
10WHAT IS IT?
11-----------
12
13Ever wanted to inspect a Cocoa applicationÕs objects from the inside?
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
26F-Script Anywhere 1.2 was tested with FScript.framework 1.2.5
27(20031020) and Mac OS X 10.3.2 (7D24). If you are using an earlier
28F-Script version, please upgrade. F-Script Anywhere 1.2 should also
29work with Mac OS X 10.2.x, but will not work with Mac OS X 10.1 or
30earlier: please use F-Script Anywhere 1.1.5 instead.
31
32
33USAGE
34-----
35
36Open the F-Script Anywhere application. Pick a Cocoa application from
37the list and click Install or press return. F-Script Anywhere will
38either install itself in that application, give you an error message,
39or crash. (Hopefully not the latter!)
40
41Switch to the application, and you should find a ÒFSAÓ menu there.
42Select ÒNew F-Script WorkspaceÓ to display a F-Script workspace.
43This behaves like any other workspace, except it's executing within
44the context of the application.
45
46You can also install F-Script Anywhere by using its dock menu. If
47the frontmost application is a Cocoa application, just pick ÒInstallÉÓ
48from the menu and F-Script Anywhere will install in that application.
49If F-Script Anywhere canÕt install, the menu item will tell you so,
50or F-Script AnywhereÕs icon will bounce to indicate a pending sheet
51explaining the problem.
52
53To remove F-Script Anywhere from an application, quit the application.
54Because of limitations in Apple's Objective-C runtime, it is
55impossible to remove F-Script Anywhere while the application is
56running.
57
58
59BUILDING
60--------
61
62The source to F-Script Anywhere is included. It has a number of
63dependencies.
64
651. Install FScript.framework (see above).
66
672. Check out the source of 'otool' from the Darwin CVS repository.
68 This is required because there's a bug in the function that returns
69 the 'flavo(u)r' of an application: Cocoa, Carbon, Classic, etc.
70 It identifies all Cocoa applications as Carbon ones. So as a
71 workaround, F-Script Anywhere examines the application itself to
72 see what libraries it links with. (This may fail if you're doing
73 something weird like linking to development versions of Foundation
74 and AppKit, but since I don't work for Apple, I couldn't test that
75 eventuality.)
76
77 Check out Commands/Apple/cctools/{include,libstuff} from Darwin
78 CVS into the "Darwin source" directory. If you don't have a CVS
79 account, go to <http://www.opensource.apple.com/> and get one.
80
81 cd to the libstuff directory and type 'make' (it doesn't use
82 jam/pbxbuild). I _think_ this is all you need.
83
843. Unzip DSTools-60.1.zip. Open the folder up and open
85 DSTools.xcodeproj. Change the active target to the DSCL framework,
86 change the build configuration to Deployment, and then build the
87 framework. Copy the resulting framework into the FSA Source/
88 directory. Alternatively if you're on PPC, you can just remove the
89 DSCL framework from the dependancies. The DSCL framework is used
90 to determine if you are in the procmod group on intel machines
91 (and if not, to prompt you if you want to add yourself) -- something
92 that is necessary for use of FSA on x86.
93
944. Unzip FScript.framework.zip, or put a newer version of FScript.framework
95 in the project path. This is used for the FScript framework auto installer.
96
975. Open 'F-Script Anywhere.xcodeproj' in Xcode and build the Application
98 target. This target depends on the Bundle and Bundle Loader
99 targets, so you don't need to build them separately. You
100 shouldnÕt see any errors or warnings, and the F-Script Anywhere
101 application (as well as two bundles, which you can ignore because
102 they are copied into the application bundle) will appear in the
103 build product directory.
104
105If you have any problems building F-Script Anywhere, please let me
106know.
107
108
109FREQUENTLY ASKED QUESTIONS
110--------------------------
111
112Q. What is F-Script?
113
114A. F-Script is a dialect of Smalltalk which includes a bridge to
115 the Objective-C runtime on Mac OS X. It's open-source, and
116 very nice. Its author, Philippe Mougin, has written several
117 articles on it, and documentation is available from the
118 F-Script Web site:
119
120 <http://www.fscript.org/>
121
122
123Q. How do you access user interface elements?
124
125A. One way is to access a window and its views programmatically:
126
127 > app := NSApplication sharedApplication
128
129 > windows := app windows
130
131 > windows
132 NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
133 0x1f0cea0>}
134
135 > windows collect: [:each | each title]
136
137 error: an instance of NSWindow does not respond to "collect:"
138
139 (...a gentle reminder that this is not Smalltalk...)
140
141 > windows title
142 {'F-Script', '', ''}
143
144 (...but F-Script has some tricks of its own...)
145
146 > fsw := windows at: 0
147
148 > fswView := fsw contentView
149
150 To open an F-Script object browser on fswView, type:
151
152 > sys browse: fswView
153
154 Or, click ÒNew Browser: Object...Ó, then click on fswView.
155 Click 'subviews' in the message list. You can use 'subviews'
156 repeatedly on container views if needed.
157
158
159Q. ThatÕs too hard, especially all that scrolling.
160
161A. If you need to access a view (such as a button or text field), menu or
162 window, youÕre in luck. Click in an F-Script workspace window, then
163 choose ÒAssociate With InterfaceÓ from the ÒFSAÓ menu.
164 Follow the instructions in the window to select a user interface
165 element, view it in an object browser or assign it to a variable.
166
167 The F-Script object browser now provides a similar feature: click the
168 "Select view" button.
169
170
171Q. I donÕt like F-ScriptÕs syntax. I don't like the object browser.
172 I donÕt like you either.
173
174A. I didnÕt write F-Script. Please address your questions to
175 F-ScriptÕs author or the F-Script mailing list.
176
177 <http://www.fscript.org/contacts.htm>
178
179 Oh, and get lost.
180
181
182Q. My question isn't answered here.
183
184A. That's not a question. But if you have a question about F-Script
185 Anywhere, a suggestion or a bug to report, please email it to me at
186 <fsa@sabi.net>. Please try to keep your messages short and to the
187 point, and I'll get back to you as soon as my schedule will allow.
188 Thanks!
189
190
191VERSION HISTORY
192---------------
1931.3 - 5 May 2006 - Fixed leaking of file handles
194 - Removed deprecated F-Script functions
195 - New associate option that automatically
196 brings up a new browser without an
197 interpreter window
198 - Auto-inject feature
1991.2 - 5 January 2004 - fixed window behavior on startup, delaying
200 display until launch is complete
201 - replaced libPatch with mach_inject and
202 SCPatch: provides improved compatibility
203 with Mac OS X 10.3 (doesn't crash randomly
204 any more!)
205 - no longer requires F-Script Anywhere
206 application to be running while installed
207 in applications
208 - F-Script Anywhere can now be installed in
209 itself
210 - check for F-Script version on startup
211 - use new, documented F-Script API for
212 identifier validation in associate window
213 - prepared for localization
214 - enable "Install" button when appropriate at
215 application startup
216 - fixed focus ring "flicker" on Mac OS X 10.3
2171.1.5 - 1 October 2002 - better identify Cocoa vs. Carbon applications
218 on Jaguar; added hierarchical window list to
219 FSA menu; fixed startup crash on Puma with
220 certain Carbon CFM applications
2211.1.4 - 25 August 2002 - fixed miscellaneous Jaguar issues; worked
222 around broken application quit notifications;
223 added unique interpreter/associate window titles
2241.1.3 - 24 July 2002 - added bullseye-menu targeting cursor; added menu
225 association; work around bug by stopping capture
226 on suspend; added delegate, data source, target,
227 cell selection for views; window controller for
228 windows
2291.1.2 - 18 July 2002 - fixed more startup issues with list management;
230 properly scale icons of apps which have no
231 small icons; added user interface association
2321.1.1 - 3 July 2002 - fixed inefficiencies responsible for long
233 startup time; reorganized Window menu; support
234 paths to applications which contain non-ASCII
235 characters [Martin HŠcker]; added sample code
236 to grab UI elements [Philippe Mougin]; cleaned
237 up code and distribution layout
2381.1 - 25 April 2002 - revised terminology; updated for F-Script 1.2;
239 zoom to fit in application list; added help
240 tags for workspace; focus workspace initially
2411.0.2 - (unreleased) - minor cleanups, added error messages, updated
242 scroll view component for faster UI response,
243 removed help menu item because it's useless
2441.0.1 - 1 March 2002 - corrected message for error 5; libPatch 1.2;
245 fixed endless confirmation on window close
2461.0.1d1 1 February 2002 - added error messages
2471.0 - 3 February 2002 - added dock menu, URL launching, check for
248 F-Script framework, floating window,
249 application name in interpreter window title,
250 fixed bugs, cleaned up error handling,
251 licensed under the GPL (because of ASM code),
252 packaged, added Read Me file and license
2531.0d1 - 1 February 2002 - proof of feasibility, private test version
254
255
256CREDITS
257-------
258
259Thanks to the following people for their software and generous
260donations of source code:
261
262Philippe Mougin, for F-Script
263Jonathan 'Wolf' Rentsch, for mach_inject
264Jon Gotow, for SCPatch and lots of advice
265Mike Ferris, for TextExtras
266Apple, for Darwin
267Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.