source: trunk/launch/launch/README @ 127

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

svn:ignore: added .DS_Store, not used for command-line apps.

README: Fixed install instructions, updated for 1.0b2.

VERSION: Updated for 1.0b2.

main.c: Updated copyright statement. Updated for 1.0b2. Provided
better explanation of error 1001. Added version information to -l,
partially descended from ICeCoffEE 1.3.

File size: 9.0 KB
Line 
1launch 1.0b2 [9 March 2003]
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 -d /usr/local/bin
52% sudo /usr/bin/install -c build/launch /usr/local/bin
53% rehash
54
55Uninstallation:
56
57% sudo rm -f /usr/local/bin/launch
58
59COMPILATION
60-----------
61
62A Project Builder project, 'launch.pbproj', is included.  A
63precompiled binary is also provided.  'launch' was developed and
64tested under Mac OS 10.2.3 with the December 2002 Developer Tools,
65and does not require any additional software to build.
66
67USAGE
68-----
69
70Just type 'launch' by itself to receive usage information.
71
72Some examples:
73
74% launch -c 'R*ch'
75[BBEdit opens]
76                               
77% launch -pbc 'R*ch' test.txt
78[BBEdit starts printing test.txt in the background]
79
80% ls -l | launch -c CWIE -
81[CodeWarrior IDE opens with an untitled document containing the file list]
82
83% launch -i org.mozilla.navigator http://www.apple.com/
84[Chimera Navigator opens Apple's Web site]
85
86% launch -l launchsw@sabi.net
87[Your preferred email client opens a new message to comment on launch]
88
89% launch -f /Applications/Preview.app
90/Applications/Preview.app: Mac OS X application package
91        type: 'APPL'    creator: 'prvw'
92        bundle ID: com.apple.Preview
93        kind: Application
94        contents: 2 items
95[...]
96
97FREQUENTLY ASKED QUESTIONS
98--------------------------
99
100Q. How do I discover bundle IDs for applications?
101
102A. The -f option to launch can help.  Say you have OmniWeb in the
103/Applications/Internet folder, and want to find out its bundle ID.
104Type 'launch -f', and drop the OmniWeb icon on Terminal:
105
106% launch -f /Applications/Internet/OmniWeb.app
107/Applications/Internet/OmniWeb.app: Mac OS X application package
108        type: 'APPL'    creator: 'OWEB'
109        bundle ID: com.omnigroup.OmniWeb
110        kind: Application
111
112Note that bundle IDs are not case-sensitive: com.barebones.BBEdit is
113the same as com.barebones.bbedit.
114
115
116Q. Why does application X open a file with a name beginning with
117'launch-stationery-'? 
118
119A. Your application does not support stationery.  Applications which
120support stationery respond to it by creating a new untitled document
121with the contents of the stationery.  Most (all?) Cocoa applications,
122such as TextEdit, do not support stationery.  If you're looking for
123a text editor which supports stationery, try BBEdit, Tex-Edit Plus,
124the CodeWarrior IDE, or almost any other Carbon editor.
125
126For the curious: launch processes input by simultaneously reading it
127and writing to a temporary stationery file.  Once reading is complete,
128launch opens the stationery file with your selected application, and
129deletes the stationery after one minute (as a safeguard, it is not
130possible to accurately gauge how long it will take for the application
131to open the stationery).
132
133
134Q. Why can't I use -f with -c to get info on an application with a
135given creator (or -f with -i for a bundle ID)?
136
137A. This feature may be added to a later version (or add it yourself!),
138but there is a workaround.  Instead of:
139
140% launch -f -c 'Doug'
141launch: can't get information (-f) on item(s) using an application (-u, -c, -i, -a)
142
143use:
144
145% launch -f "`launch -nc 'Doug'`"
146/Volumes/GrayApps/Utilities/Resorcerer 2.4/Resorcerer: scriptable Mac OS X application [Carbon, prefers native OS X]
147        type: 'APPL'    creator: 'Doug'
148        kind: Application
149
150
151Q. Why won't launch locate non-packaged applications by their bundle
152identifier?
153
154A. This was a LaunchServices/CFBundle bug, fixed in Mac OS X 10.2.
155For example, BBEdit 6.1 for OS X was a packaged application; BBEdit
1566.5 is not, however its 'plst' resource contains a bundle ID.
157LaunchServices prior to OS X 10.2 was unable to locate BBEdit 6.5 by
158its bundle ID.
159
160Non-packaged applications usually originated as Mac OS applications,
161so they will have creators.  If you're using Mac OS X 10.1.x, try
162using the creator instead of the bundle ID as a workaround (-c instead
163of -i).
164
165
166Q. Why does launch display '[can't access CFBundle for application]'
167in place of the bundle identifiers of non-packaged applications?
168
169A. This is a CFBundle bug which remains as of Mac OS X 10.2.3.  If
170this matters to you, please ask Apple to fix it, or implement a
171workaround in launch by parsing the 'plst' id 0 resource directly.
172
173
174Q. Why doesn't launch support opening items as root?
175
176A. Apple eliminated this capability with the Mac OS X 10.1 Security
177Update.  If at some point Apple restores this capability, 'launch'
178will be ready to support it.
179
180
181Q. Why do I get an error -600?
182
183A. A typical occurrence of this would be:
184
185% launch -n .
186launch: can't open items: unable to connect to system service.
187Are you logged in? (-600)
188
189In order to perform certain operations, launch needs to talk to
190various system services owned by the currently logged-on user.  If you
191aren't using 'launch' from a terminal currently logged into the Mac OS
192X GUI, certain operations may not work.  Try opening Terminal.app,
193creating a new terminal, and trying again.
194
195Another possibility is to create your own interprocess messaging.
196For example, place this script in a file:
197
198#!/bin/sh
199PIPE=/tmp/.launchpipe
200[ -e $PIPE ] || mkfifo $PIPE
201while true; do
202    read opts < $PIPE
203    eval "/path/to/launch $opts" & # change this to launch's path
204done
205
206Then, define a function or alias.  For zsh:
207
208rlaunch() { echo $@ > /tmp/.launchpipe }
209
210Or for tcsh:
211
212alias rlaunch 'echo \!* > /tmp/.launchpipe'
213
214Start the shell script above from the console, then you can use
215'rlaunch' in place of 'launch' logged in from anywhere else.
216
217Thanks to robert <robert@allyourbass.org> for this suggestion.
218
219COMMENTS, SUGGESTIONS, BUG REPORTS, ETC.
220----------------------------------------
221
222Please send to the author, Nicholas Riley, at <launchsw@sabi.net>.
223
224VERSION HISTORY
225---------------
226
2271.0b2 - 9 March 2003
228 - fixed install instructions to create /usr/local/bin if needed
229 - show bundle version with text, hex and integer representations
2301.0b1 - 14 December 2002
231 - accept "slack" (default http) URLs and email addresses with -l
232 - accept input from stdin with '-'
233 - open URLs with arbitrary applications when specified without -l
234 - builds without compiler warnings
2351.0a9 - 2 April 2002
236 - license, comments changes
2371.0a8 - 29 March 2002
238 - errors with -l (from ICeCoffEE), added rlaunch script
2391.0a7 - 3 March 2002
240 - print dates, sizes, folder valence, locked status for -f
241 - don't abort on failure to obtain bundle information
2421.0a6 - 30 November 2001
243 - fixed incorrect messages, broken -u and crash on -nu
2441.0a5 - 28 November 2001
245 - print kind string for -f, still no new installer
2461.0a4 - 20 November 2001
247 - [try to] use Installer VISE instead of InstallAnywhere
2481.0a3 - 15 November 2001
249 - fixed package identification in -f, updated examples
2501.0a2 - 15 November 2001
251 - -f, removed broken -m
2521.0a1 - 14 November 2001
253 - renamed from "FindApp", launch by default, -u
2541.0d5 - 7 November 2001
255 - option -s for launching as root [nonfunctional]
2561.0d4 - 6 November 2001
257 - URL launching and Internet Config support
2581.0d3 - 4 November 2001
259 - more robust, support for docs without app
2601.0d2 - 4 November 2001
261 - options -opsbmhCX, -cin, documents
2621.0d1 - 26 August 2001
263 - returns path of application identified by creator
Note: See TracBrowser for help on using the repository browser.