source: trunk/launch/launch/README @ 54

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

Fixed a mistake in the README file. Added *~ to the ignore list.

File size: 8.8 KB
Line 
1launch 1.0b1 [14 December 2002]
2============
3
4A command-line launcher for Mac OS X in the spirit of open(1).
5
6Written by Nicholas Riley <mailto:launchsw@sabi.net>.
7Obtain updates from <http://web.sabi.net/nriley/software/>.
8
9WHAT IS IT?
10-----------
11
12Apple provides a simple command-line launching program called 'open'
13with Mac OS X.  It offers few options - launching applications by name
14or by path, launching TextEdit, or opening a number of applications,
15documents, folders, or URLs.  With the exception of special support for
16TextEdit, 'launch' does all this and:
17
18- opens URLs, directly or in your preferred helper application (-l)
19- lets you specify applications by their four-character creator
20  (e.g. 'ToyS') or Java-style bundle ID (e.g. com.apple.scripteditor),
21  both of which allow you to move or rename an application without
22  changing references to it
23- asks applications to print documents, something the OS X Finder
24  no longer permits
25- allows you to pipe output to GUI applictions
26- launches applications in the background
27- launches Carbon applications in Classic
28- displays file information including type, creator, bundle ID,
29  data and resource fork sizes, and dates
30- reports errors intelligibly
31- and much more!
32
33'launch' is useful by itself, but is even better when used in scripts.
34Assign a shell command to your favorite Mac OS text, graphics or
35resource editor.  Go to your favorite Web site with a few keystrokes.
36
37Like 'open', 'launch' provides one half of the round-trip between
38Terminal.app and the Finder.  You can drag and drop icons or proxy icons
39into Terminal.app to insert their paths into command lines.  To go in the
40other direction, just type 'launch .' (or 'open .') to open a Finder window
41showing the current directory.
42
43INSTALLATION
44------------
45
46The commands below install the 'launch' tool in /usr/local/bin, which
47is in the default path.  You should subsequently be able to use
48'launch' by typing its name.  If you wish to install it somewhere else,
49modify the install line as appropriate.
50
51% sudo /usr/bin/install -c build/launch /usr/local/bin
52% rehash
53
54Uninstallation:
55
56% sudo rm -f /usr/local/bin/launch
57
58COMPILATION
59-----------
60
61A Project Builder project, 'launch.pbproj', is included.  A
62precompiled binary is also provided.  'launch' was developed and
63tested under Mac OS 10.2.3 with the December 2002 Developer Tools,
64and does not require any additional software to build.
65
66USAGE
67-----
68
69Just type 'launch' by itself to receive usage information.
70
71Some examples:
72
73% launch -c 'R*ch'
74[BBEdit opens]
75                               
76% launch -pbc 'R*ch' test.txt
77[BBEdit starts printing test.txt in the background]
78
79% ls -l | launch -c CWIE -
80[CodeWarrior IDE opens with an untitled document containing the file list]
81
82% launch -i org.mozilla.navigator http://www.apple.com/
83[Chimera Navigator opens Apple's Web site]
84
85% launch -l launchsw@sabi.net
86[Your preferred email client opens a new message to comment on launch]
87
88% launch -f /Applications/Preview.app
89/Applications/Preview.app: Mac OS X application package
90        type: 'APPL'    creator: 'prvw'
91        bundle ID: com.apple.Preview
92        kind: Application
93        contents: 2 items
94[...]
95
96FREQUENTLY ASKED QUESTIONS
97--------------------------
98
99Q. How do I discover bundle IDs for applications?
100
101A. The -f option to launch can help.  Say you have OmniWeb in the
102/Applications/Internet folder, and want to find out its bundle ID.
103Type 'launch -f', and drop the OmniWeb icon on Terminal:
104
105% launch -f /Applications/Internet/OmniWeb.app
106/Applications/Internet/OmniWeb.app: Mac OS X application package
107        type: 'APPL'    creator: 'OWEB'
108        bundle ID: com.omnigroup.OmniWeb
109        kind: Application
110
111Note that bundle IDs are not case-sensitive: com.barebones.BBEdit is
112the same as com.barebones.bbedit.
113
114
115Q. Why does application X open a file with a name beginning with
116'launch-stationery-'? 
117
118A. Your application does not support stationery.  Applications which
119support stationery respond to it by creating a new untitled document
120with the contents of the stationery.  Most (all?) Cocoa applications,
121such as TextEdit, do not support stationery.  If you're looking for
122a text editor which supports stationery, try BBEdit, Tex-Edit Plus,
123the CodeWarrior IDE, or almost any other Carbon editor.
124
125For the curious: launch processes input by simultaneously reading it
126and writing to a temporary stationery file.  Once reading is complete,
127launch opens the stationery file with your selected application, and
128deletes the stationery after one minute (as a safeguard, it is not
129possible to accurately gauge how long it will take for the application
130to open the stationery).
131
132
133Q. Why can't I use -f with -c to get info on an application with a
134given creator (or -f with -i for a bundle ID)?
135
136A. This feature may be added to a later version (or add it yourself!),
137but there is a workaround.  Instead of:
138
139% launch -f -c 'Doug'
140launch: can't get information (-f) on item(s) using an application (-u, -c, -i, -a)
141
142use:
143
144% launch -f "`launch -nc 'Doug'`"
145/Volumes/GrayApps/Utilities/Resorcerer 2.4/Resorcerer: scriptable Mac OS X application [Carbon, prefers native OS X]
146        type: 'APPL'    creator: 'Doug'
147        kind: Application
148
149
150Q. Why won't launch locate non-packaged applications by their bundle
151identifier?
152
153A. This was a LaunchServices/CFBundle bug, fixed in Mac OS X 10.2.
154For example, BBEdit 6.1 for OS X was a packaged application; BBEdit
1556.5 is not, however its 'plst' resource contains a bundle ID.
156LaunchServices prior to OS X 10.2 was unable to locate BBEdit 6.5 by
157its bundle ID.
158
159Non-packaged applications usually originated as Mac OS applications,
160so they will have creators.  If you're using Mac OS X 10.1.x, try
161using the creator instead of the bundle ID as a workaround (-c instead
162of -i).
163
164
165Q. Why does launch display '[can't access CFBundle for application]'
166in place of the bundle identifiers of non-packaged applications?
167
168A. This is a CFBundle bug which remains as of Mac OS X 10.2.3.  If
169this matters to you, please ask Apple to fix it, or implement a
170workaround in launch by parsing the 'plst' id 0 resource directly.
171
172
173Q. Why doesn't launch support opening items as root?
174
175A. Apple eliminated this capability with the Mac OS X 10.1 Security
176Update.  If at some point Apple restores this capability, 'launch'
177will be ready to support it.
178
179
180Q. Why do I get an error -600?
181
182A. A typical occurrence of this would be:
183
184% launch -n .
185launch: can't open items: unable to connect to system service.
186Are you logged in? (-600)
187
188In order to perform certain operations, launch needs to talk to
189various system services owned by the currently logged-on user.  If you
190aren't using 'launch' from a terminal currently logged into the Mac OS
191X GUI, certain operations may not work.  Try opening Terminal.app,
192creating a new terminal, and trying again.
193
194Another possibility is to create your own interprocess messaging.
195For example, place this script in a file:
196
197#!/bin/sh
198PIPE=/tmp/.launchpipe
199[ -e $PIPE ] || mkfifo $PIPE
200while true; do
201    read opts < $PIPE
202    eval "/path/to/launch $opts" & # change this to launch's path
203done
204
205Then, define a function or alias.  For zsh:
206
207rlaunch() { echo $@ > /tmp/.launchpipe }
208
209Or for tcsh:
210
211alias rlaunch 'echo \!* > /tmp/.launchpipe'
212
213Start the shell script above from the console, then you can use
214'rlaunch' in place of 'launch' logged in from anywhere else.
215
216Thanks to robert <robert@allyourbass.org> for this suggestion.
217
218COMMENTS, SUGGESTIONS, BUG REPORTS, ETC.
219----------------------------------------
220
221Please send to the author, Nicholas Riley, at <launchsw@sabi.net>.
222
223VERSION HISTORY
224---------------
225
2261.0b1 - 14 December 2002
227 - accept "slack" (default http) URLs and email addresses with -l
228 - accept input from stdin with '-'
229 - open URLs with arbitrary applications when specified without -l
230 - builds without compiler warnings
2311.0a9 - 2 April 2002
232 - license, comments changes
2331.0a8 - 29 March 2002
234 - errors with -l (from ICeCoffEE), added rlaunch script
2351.0a7 - 3 March 2002
236 - print dates, sizes, folder valence, locked status for -f
237 - don't abort on failure to obtain bundle information
2381.0a6 - 30 November 2001
239 - fixed incorrect messages, broken -u and crash on -nu
2401.0a5 - 28 November 2001
241 - print kind string for -f, still no new installer
2421.0a4 - 20 November 2001
243 - [try to] use Installer VISE instead of InstallAnywhere
2441.0a3 - 15 November 2001
245 - fixed package identification in -f, updated examples
2461.0a2 - 15 November 2001
247 - -f, removed broken -m
2481.0a1 - 14 November 2001
249 - renamed from "FindApp", launch by default, -u
2501.0d5 - 7 November 2001
251 - option -s for launching as root [nonfunctional]
2521.0d4 - 6 November 2001
253 - URL launching and Internet Config support
2541.0d3 - 4 November 2001
255 - more robust, support for docs without app
2561.0d2 - 4 November 2001
257 - options -opsbmhCX, -cin, documents
2581.0d1 - 26 August 2001
259 - returns path of application identified by creator
Note: See TracBrowser for help on using the repository browser.