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

Last change on this file since 229 was 229, checked in by rchin, 14 years ago

Created DSCL framework from DSCL open source code (distributed as a part of Darwin from Apple). This is for programmatically testing and adding entries to directory services, so that I can add the user to the procmod group. The modified DSCL code is in a zip file available for people to use (had to add some methods to provide better read functionality). Also has a binary that does the adding to procmod group with escalated privileges when the user authenticates via the authorization services security framework. Updated the readme to reflect this additional step for building.

File size: 10.2 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   
943. Open 'F-Script Anywhere.xcodeproj' in Xcode and build the Application
95   target.  This target depends on the Bundle and Bundle Loader
96   targets, so you don't need to build them separately.  You
97   shouldnÕt see any errors or warnings, and the F-Script Anywhere
98   application (as well as two bundles, which you can ignore because
99   they are copied into the application bundle) will appear in the
100   build product directory.
101
102If you have any problems building F-Script Anywhere, please let me
103know.
104
105
106FREQUENTLY ASKED QUESTIONS
107--------------------------
108
109Q. What is F-Script?
110
111A. F-Script is a dialect of Smalltalk which includes a bridge to
112   the Objective-C runtime on Mac OS X.  It's open-source, and
113   very nice.  Its author, Philippe Mougin, has written several
114   articles on it, and documentation is available from the
115   F-Script Web site:
116
117   <http://www.fscript.org/>
118
119
120Q. How do you access user interface elements?
121
122A. One way is to access a window and its views programmatically:
123
124   > app := NSApplication sharedApplication
125
126   > windows := app windows
127
128   > windows
129   NSCFArray {<NSWindow: 0x186770>, <NSWindow: 0x1ba4a0>, <NSWindow:
130   0x1f0cea0>}
131
132   > windows collect: [:each | each title]
133
134   error: an instance of NSWindow does not respond to "collect:"
135
136   (...a gentle reminder that this is not Smalltalk...)
137
138   > windows title
139   {'F-Script', '', ''}
140
141   (...but F-Script has some tricks of its own...)
142
143   > fsw := windows at: 0
144
145   > fswView := fsw contentView
146
147   To open an F-Script object browser on fswView, type:
148
149   > sys browse: fswView
150
151   Or, click ÒNew Browser: Object...Ó, then click on fswView.
152   Click 'subviews' in the message list.  You can use 'subviews'
153   repeatedly on container views if needed.
154
155
156Q. ThatÕs too hard, especially all that scrolling.
157
158A. If you need to access a view (such as a button or text field), menu or
159   window, youÕre in luck.  Click in an F-Script workspace window, then
160   choose ÒAssociate With InterfaceÓ from the ÒFSAÓ menu.
161   Follow the instructions in the window to select a user interface
162   element, view it in an object browser or assign it to a variable.
163
164   The F-Script object browser now provides a similar feature: click the
165   "Select view" button.
166
167
168Q. I donÕt like F-ScriptÕs syntax.  I don't like the object browser.
169   I donÕt like you either.
170
171A. I didnÕt write F-Script.  Please address your questions to
172   F-ScriptÕs author or the F-Script mailing list.
173   
174   <http://www.fscript.org/contacts.htm>
175
176   Oh, and get lost.
177
178
179Q. My question isn't answered here.
180
181A. That's not a question.  But if you have a question about F-Script
182   Anywhere, a suggestion or a bug to report, please email it to me at
183   <fsa@sabi.net>.  Please try to keep your messages short and to the
184   point, and I'll get back to you as soon as my schedule will allow.
185   Thanks!
186
187
188VERSION HISTORY
189---------------
1901.3   - 5 May     2006  - Fixed leaking of file handles
191                        - Removed deprecated F-Script functions
192                        - New associate option that automatically
193                          brings up a new browser without an
194                          interpreter window
195                        - Auto-inject feature
1961.2   - 5 January 2004  - fixed window behavior on startup, delaying
197                          display until launch is complete
198                        - replaced libPatch with mach_inject and
199                          SCPatch: provides improved compatibility
200                          with Mac OS X 10.3 (doesn't crash randomly
201                          any more!)
202                        - no longer requires F-Script Anywhere
203                          application to be running while installed
204                          in applications
205                        - F-Script Anywhere can now be installed in
206                          itself
207                        - check for F-Script version on startup
208                        - use new, documented F-Script API for
209                          identifier validation in associate window
210                        - prepared for localization
211                        - enable "Install" button when appropriate at
212                          application startup
213                        - fixed focus ring "flicker" on Mac OS X 10.3
2141.1.5 - 1 October 2002  - better identify Cocoa vs. Carbon applications
215                          on Jaguar; added hierarchical window list to
216                          FSA menu; fixed startup crash on Puma with
217                          certain Carbon CFM applications
2181.1.4 - 25 August 2002  - fixed miscellaneous Jaguar issues; worked
219                          around broken application quit notifications;
220                          added unique interpreter/associate window titles
2211.1.3 - 24 July 2002    - added bullseye-menu targeting cursor; added menu
222                          association; work around bug by stopping capture
223                          on suspend; added delegate, data source, target,
224                          cell selection for views; window controller for
225                          windows
2261.1.2 - 18 July 2002    - fixed more startup issues with list management;
227                          properly scale icons of apps which have no
228                          small icons; added user interface association
2291.1.1 - 3 July 2002     - fixed inefficiencies responsible for long
230                          startup time; reorganized Window menu; support
231                          paths to applications which contain non-ASCII
232                          characters [Martin HŠcker]; added sample code
233                          to grab UI elements [Philippe Mougin]; cleaned
234                          up code and distribution layout
2351.1   - 25 April 2002   - revised terminology; updated for F-Script 1.2;
236                          zoom to fit in application list; added help
237                          tags for workspace; focus workspace initially
2381.0.2 - (unreleased)    - minor cleanups, added error messages, updated
239                          scroll view component for faster UI response,
240                          removed help menu item because it's useless
2411.0.1 - 1 March 2002    - corrected message for error 5; libPatch 1.2;
242                          fixed endless confirmation on window close
2431.0.1d1 1 February 2002 - added error messages
2441.0   - 3 February 2002 - added dock menu, URL launching, check for
245                          F-Script framework, floating window,
246                          application name in interpreter window title,
247                          fixed bugs, cleaned up error handling,
248                          licensed under the GPL (because of ASM code),
249                          packaged, added Read Me file and license
2501.0d1 - 1 February 2002 - proof of feasibility, private test version
251
252
253CREDITS
254-------
255
256Thanks to the following people for their software and generous
257donations of source code:
258
259Philippe Mougin, for F-Script
260Jonathan 'Wolf' Rentsch, for mach_inject
261Jon Gotow, for SCPatch and lots of advice
262Mike Ferris, for TextExtras
263Apple, for Darwin
264Frank Vercruesse, for ASM
Note: See TracBrowser for help on using the repository browser.