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

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

F-Script Anywhere 1.1.2a1

File size: 7.8 KB
Line 
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.