source: trunk/launch/launch/README @ 267

Last change on this file since 267 was 267, checked in by Nicholas Riley, 14 years ago

package-launch.sh, launch/README: New, simpler packaging process.

File size: 10.4 KB
Line 
1launch 1.1d2 [unreleased]
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 (open -e), '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  didn't get until Mac OS X 10.4
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, dates and version
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 /usr/local/man/man1
52% sudo /usr/bin/install -c launch /usr/local/bin
53% sudo /usr/bin/install -c launch.1 /usr/local/man/man1
54% rehash
55
56Uninstallation:
57
58% sudo rm -f /usr/local/bin/launch /usr/local/man/man1/launch.1
59
60COMPILATION
61-----------
62
63An Xcode project, 'launch.xcodeproj', is included.  A precompiled Universal
64binary is also provided.  'launch' was developed and tested under Mac OS X
6510.4.7 with Xcode 2.3, and does not require any additional software to
66build.
67
68USAGE
69-----
70
71Just type 'launch' by itself to receive usage information.
72
73Some examples:
74
75% launch -c 'R*ch'
76[BBEdit opens]
77                               
78% launch -pbc 'R*ch' test.txt
79[BBEdit starts printing test.txt in the background]
80
81% ls -l | launch -c CWIE -
82[CodeWarrior IDE opens with an untitled document containing the file list]
83
84% launch -i org.mozilla.camino http://www.apple.com/
85[Camino opens Apple's Web site]
86
87% launch -l launchsw@sabi.net
88[Your preferred email client opens a new message to comment on launch]
89
90% launch -f /Applications/Preview.app
91/Applications/Preview.app: Mac OS X application package
92        type: 'APPL'    creator: 'prvw'
93        bundle ID: com.apple.Preview
94        version: 2.1.0
95        kind: Application
96        contents: 1 item
97[...]
98
99A scripting example: a zsh function which provides an OS X wrapper
100around emacsclient and the Carbon build of GNU Emacs, using launch and
101appswitch (another one of my command-line tools).
102
103    e() {
104      ( emacsclient -n $@ >&/dev/null && \
105        appswitch -a Emacs ) || \
106      ( launch -ba Emacs && \
107        until { emacsclient -n $@ >&/dev/null } do sleep 1; done;
108        appswitch -a Emacs )
109      export EDITOR=emacsclient
110    }
111
112FREQUENTLY ASKED QUESTIONS
113--------------------------
114
115Q. How do I discover bundle IDs for applications?
116
117A. The -f option to launch can help.  Say you have OmniWeb in the
118/Applications/Internet folder, and want to find out its bundle ID.
119Type 'launch -f', and drop the OmniWeb icon on Terminal:
120
121% launch -f /Applications/Internet/OmniWeb.app
122/Applications/Internet/OmniWeb.app: Mac OS X application package
123        type: 'APPL'    creator: 'OWEB'
124        bundle ID: com.omnigroup.OmniWeb
125        version: 4.5
126        kind: Application
127
128Note that bundle IDs are not case-sensitive: com.barebones.BBEdit is
129the same as com.barebones.bbedit.
130
131
132Q. Why does application X open a file with a name beginning with
133'launch-stationery-'? 
134
135A. Your application does not support stationery.  Applications which
136support stationery respond to it by creating a new untitled document
137with the contents of the stationery.  Most Cocoa applications, such as
138TextEdit, do not support stationery.  (Omni Group applications are a
139notable exception.)  If you're looking for a text editor which
140supports stationery, try BBEdit, Tex-Edit Plus, the CodeWarrior IDE,
141or almost any other Carbon editor.
142
143For the curious: launch processes input by simultaneously reading it
144and writing to a temporary stationery file.  Once reading is complete,
145launch opens the stationery file with your selected application, and
146deletes the stationery after one minute (as a safeguard, it is not
147possible to accurately gauge how long it will take for the application
148to open the stationery).
149
150
151Q. Why can't I use -f with -c to get info on an application with a
152given creator (or -f with -i for a bundle ID)?
153
154A. This feature may be added to a later version (or add it yourself!),
155but there is a workaround.  Instead of:
156
157% launch -f -c 'Doug'
158launch: can't get information (-f) on item(s) using an application (-u, -c, -i, -a)
159
160use:
161
162% launch -f "`launch -nc 'Doug'`"
163/Volumes/GrayApps/Utilities/Resorcerer 2.4/Resorcerer: scriptable Mac OS X application [Carbon, prefers native OS X]
164        type: 'APPL'    creator: 'Doug'
165        bundle ID: com.mathemaesthetics.resorcerer
166        version: 2.4 [0x2418010 = 37847056]
167        kind: Application
168[...]
169
170
171Q. Why doesn't launch support opening items as root?
172
173A. Apple eliminated this capability with the Mac OS X 10.1 Security
174Update.  If at some point Apple restores this capability, 'launch'
175will be ready to support it.
176
177
178Q. Why do I get an error -600?
179
180A. A typical occurrence of this would be:
181
182% launch -n .
183launch: can't open items: unable to connect to system service.
184Are you logged in? (-600)
185
186In order to perform certain operations, launch needs to talk to
187various system services owned by the currently logged-on user.  If you
188aren't using 'launch' from a terminal currently logged into the Mac OS
189X GUI, certain operations may not work.  Try opening Terminal, creating
190a new terminal window, and trying again.
191
192Another possibility is to create your own interprocess messaging.
193For example, place this script in a file:
194
195#!/bin/sh
196PIPE=/tmp/.launchpipe
197[ -e $PIPE ] || mkfifo $PIPE
198while true; do
199    read opts < $PIPE
200    eval "/path/to/launch $opts" & # change this to launch's path
201done
202
203Then, define a function or alias.  For zsh:
204
205rlaunch() { echo $@ > /tmp/.launchpipe }
206
207Or for tcsh:
208
209alias rlaunch 'echo \!* > /tmp/.launchpipe'
210
211Start the shell script above from the console, then you can use
212'rlaunch' in place of 'launch' logged in from anywhere else.
213
214Thanks to robert <robert@allyourbass.org> for this suggestion.
215
216COMMENTS, SUGGESTIONS, BUG REPORTS, ETC.
217----------------------------------------
218
219Please send to the author, Nicholas Riley, at <launchsw@sabi.net>.
220
221VERSION HISTORY
222---------------
223
2241.1 - unreleased
225 - -L: send "launch" (ascr/noop) event to app, bypasses automatic
226 - -o: pass command-line arguments (broken, r. 4474993)
227   opening of untitled document, etc.
228 - display content type ID (UTI)   
229 - switched to new LSOpen APIs (now requires Mac OS X 10.4 or later)
230 - switched to new date formatting APIs (the old ones are deprecated)
231 - for compatibility with open(1), take app path as argument to -a
2321.0.1 - 3 April 2005
233 - prefer files to URLs; added -U for old behavior
234 - don't display extraneous leading './' on file paths
235 - display 'zero items', not '0 items', for consistency
236 - display versions of non-applications
237 - read Info.plists embedded in unbundled Mach-O applications
238 - non-ASCII arguments are now handled with the filesystem, rather
239   than the system encoding [Derrick Bass]
240 - explicitly use UTF-8 everywhere else to properly interpret and
241   display non-ASCII filenames and URLs
242 - reading OSTypes and 'vers' resources, and opening URLs with
243   Internet Config still uses the system encoding, converting as
244   necessary for display
245 - should be buildable on 10.2 again
2461.0 - 23 October 2003
247 - work around CFBundle bug to report bundle identifiers and versions
248   from resource forks of unpackaged Carbon applications and Classic
249   applications [Lloyd Dupont]
250 - added descriptions for more error codes and clarified error
251   reporting
252 - output all errors to stderr
253 - provide better errors for -X option
254 - restored -m: OS X bug is fixed in Panther
255 - fixed a couple of tiny memory leaks
256 - added man page [Hisashi T Fujinaka]
257 - work around bug in LSOpenFromURLSpec opening multiple items in
258   Mac OS X 10.3
2591.0b2 - 9 March 2003
260 - fixed install instructions to create /usr/local/bin if needed
261 - show bundle version with text, hex and integer representations
2621.0b1 - 14 December 2002
263 - accept "slack" (default http) URLs and email addresses with -l
264 - accept input from stdin with '-'
265 - open URLs with arbitrary applications when specified without -l
266 - builds without compiler warnings
2671.0a9 - 2 April 2002
268 - license, comments changes
2691.0a8 - 29 March 2002
270 - errors with -l (from ICeCoffEE), added rlaunch script
2711.0a7 - 3 March 2002
272 - print dates, sizes, folder valence, locked status for -f
273 - don't abort on failure to obtain bundle information
2741.0a6 - 30 November 2001
275 - fixed incorrect messages, broken -u and crash on -nu
2761.0a5 - 28 November 2001
277 - print kind string for -f, still no new installer
2781.0a4 - 20 November 2001
279 - [try to] use Installer VISE instead of InstallAnywhere
2801.0a3 - 15 November 2001
281 - fixed package identification in -f, updated examples
2821.0a2 - 15 November 2001
283 - -f, removed broken -m
2841.0a1 - 14 November 2001
285 - renamed from "FindApp", launch by default, -u
2861.0d5 - 7 November 2001
287 - option -s for launching as root [nonfunctional]
2881.0d4 - 6 November 2001
289 - URL launching and Internet Config support
2901.0d3 - 4 November 2001
291 - more robust, support for docs without app
2921.0d2 - 4 November 2001
293 - options -opsbmhCX, -cin, documents
2941.0d1 - 26 August 2001
295 - returns path of application identified by creator
Note: See TracBrowser for help on using the repository browser.