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

Last change on this file since 7 was 7, checked in by Nicholas Riley, 22 years ago

F-Script Anywhere 1.1.2a1

File size: 7.8 KB
RevLine 
[7]1F-Script Anywhere 1.1.2a1 [17 July 2002]
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.1.2 was tested with FScript.framework 1.2.1 (20020422)
27and Mac OS X 10.1.5 (5S66). It may or may not work with earlier or
28later versions, I don't know. If you are using an earlier F-Script
29version, please upgrade.
30
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
52When you're finished, quit the application before quitting F-Script
53Anywhere, otherwise the application will crash. This is an inherent
54limitation of the Objective-C runtime, and I can't do anything about
55it. F-Script Anywhere will warn you if you try to quit it when it's
56still installed in active applications.
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. Install libPatch by Ed Wynne.
68
69 <http://www.phasic.com/~arwyn/libPatch-1.2.tgz>
70
71 I'd suggest you do it this way:
72
73 % cd /
74 % sudo gnutar --preserve-permissions -zxf libPatch-1.2.tgz
75 Password:
76 (please don't use StuffIt Expander)
77
78 This installs files in /Developer/Examples and
79 /usr/local/{bin,include,lib}. If you're paranoid, you may want to
80 check the contents of the directory before installing.
81
82 Please note that the layout of the libPatch distribution has changed
83 since libPatch 1.0; the above instructions will not work for 1.0.
84
853. Check out the source of 'otool' from the Darwin CVS repository.
86 This is required because there's a bug in the function that returns
87 the 'flavo(u)r' of an application: Cocoa, Carbon, Classic, etc.
88 It identifies all Cocoa applications as Carbon ones. So as a
89 workaround, F-Script Anywhere examines the application itself to
90 see what libraries it links with. (This may fail if you're doing
91 something weird like linking to development versions of Foundation
92 and AppKit, but since I don't work for Apple, I couldn't test that
93 eventuality.)
94
95 Check out Commands/Apple/cctools/{include,libstuff} from Darwin
96 CVS into the "Darwin source" directory. If you don't have a CVS
97 account, go to <http://www.opensource.apple.com/> and get one.
98
99 cd to the libstuff directory and type 'make' (it doesn't use
100 jam/pbxbuild). I _think_ this is all you need.
101
1024. Open 'F-Script Anywhere.pbproj' in Project Builder and build the
103 Application target. It depends on the Library target, so you don't
104 need to build it separately. You shouldn't see any errors or
105 warnings, and the F-Script Anywhere application (as well as the
106 library, which you can ignore because it is also copied into the
107 application bundle) will appear in the build product directory.
108
109If you have any problems building F-Script Anywhere, please let me
110know.
111
112
113FREQUENTLY ASKED QUESTIONS
114--------------------------
115
116Q. What is F-Script?
117
118A. F-Script is a dialect of Smalltalk which includes a bridge to
119 the Objective-C runtime on Mac OS X. It's open-source, and
120 very nice. Its author, Philippe Mougin, has written several
121 articles on it, and documentation is available from the
122 F-Script Web site:
123
124 <http://www.fscript.org/>
125
126
127Q. How do you access user interface elements?
128
129A. Like this:
130
131 > app := NSApplication sharedApplication
132
133 > windows := app windows
134
135 > windows
136 NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
137 0x1f0cea0>}
138
139 > windows collect: [:each | each title]
140
141 error: an instance of NSWindow does not respond to "collect:"
142
143 (...a gentle reminder that this is not Smalltalk...)
144
145 > windows title
146 {'F-Script', '', ''}
147
148 (...but F-Script has some tricks of its own...)
149
150 > fsw := windows at: 0
151
152 > fswView := fsw contentView
153
154 At this point, click "New Browser: Object...", click on fswView,
155 then 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. [XXX fix me for 1.1.2 support]
162
163
164Q. I don't like F-Script's syntax. I don't like the object browser.
165 I don't like you either.
166
167A. I didn't write F-Script. Please address your questions to
168 F-Script's author or the F-Script mailing list.
169
170 <http://www.fscript.org/contacts.htm>
171
172 Oh, and get lost.
173
174
175Q. My question isn't answered here.
176
177A. That's not a question. But if you have a question about F-Script
178 Anywhere, a suggestion or a bug to report, please email it to me at
179 <fsa@sabi.net>. Please try to keep your messages short and to the
180 point, and I'll get back to you as soon as my schedule will allow.
181 Thanks!
182
183
184VERSION HISTORY
185---------------
186
1871.1.2a1 - 17 July 2002 - fixed more startup issues with list management;
188 properly scale icons of apps which have no
189 small icons; added UI association interface
1901.1.1 - 3 July 2002 - fixed inefficiencies responsible for long
191 startup time; reorganized Window menu; support
192 paths to applications which contain non-ASCII
193 characters [Martin HŠcker]; added sample code
194 to grab UI elements [Philippe Mougin]; cleaned
195 up code and distribution layout
1961.1 - 25 April 2002 - revised terminology; updated for F-Script 1.2;
197 zoom to fit in application list; added help
198 tags for workspace; focus workspace initially
1991.0.2 - (unreleased) - minor cleanups, added error messages, updated
200 scroll view component for faster UI response,
201 removed help menu item because it's useless
2021.0.1 - 1 March 2002 - corrected message for error 5; libPatch 1.2;
203 fixed endless confirmation on window close
2041.0.1d1 1 February 2002 - added error messages
2051.0 - 3 February 2002 - added dock menu, URL launching, check for
206 F-Script framework, floating window,
207 application name in interpreter window title,
208 fixed bugs, cleaned up error handling,
209 licensed under the GPL (because of ASM code),
210 packaged, added Read Me file and license
2111.0d1 - 1 February 2002 - proof of feasibility, private test version
212
213
214CREDITS
215-------
216
217Thanks to the following people for their software and generous
218donations of source code:
219
220Philippe Mougin, for F-Script
221Mike Ferris, for TextExtras
222Apple, for Darwin
223Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.