source: trunk/launch/launch/README @ 146

Last change on this file since 146 was 146, checked in by Nicholas Riley, 16 years ago

VERSION: Updated for 1.0 (at long last!)

main.c: Dealt with -b/-h issue through documentation in man page,
removed from to do list. Dealt with -X issue through testing and
adding kLSNoClassicEnvironmentErr. Added kLSNoExecutableErr and
kCGErrorApplicationRequiresNewerSystem. Removed
BROKEN_LAUNCHNEWINSTANCE because it's fixed in Panther. Updated for
1.0. Fixed a couple of minor memory leaks. Output errors to stderr
instead of stdout. Work around bug in LSOpenFromURLSpec in Panther
(filed bug already). Don't make '????' look like a trigraph to GCC.

launch.pbproj: Updated for Xcode.

launch.1: Manual page, finally. Documents several known Mac OS X bugs
which interfere with launch's functioning.

README: Updated for 1.0. Added man page installation/removal
instructions, just like appswitch. s/Chimera/Camino/. Added my zsh
e() function as an example. Updated examples to reflect current
software versions and usage. Updated stationery discussion to mention
that Omni apps handle stationery too.

package-launch.sh: Set type/creator of files (not that it matters
since we're not doing a dmg distribution any more). Changes for man
page packaging.

File size: 9.9 KB
Line 
1launch 1.0 [23 October 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 (open -a), '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, 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 build/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/appswitch.1
59
60COMPILATION
61-----------
62
63An Xcode/Project Builder project, 'launch.pbproj', is included.  A
64precompiled binary is also provided.  'launch' was developed and
65tested under Mac OS 10.3 with the October 2003 Developer Tools, and
66does not require any additional software to build.
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.navigator 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 won't launch locate non-packaged applications by their bundle
172identifier?
173
174A. This was a LaunchServices/CFBundle bug, fixed in Mac OS X 10.2.
175For example, BBEdit 6.1 for OS X was a packaged application; BBEdit
1766.5 is not, however its 'plst' resource contains a bundle ID.
177LaunchServices prior to OS X 10.2 was unable to locate BBEdit 6.5 by
178its bundle ID.
179
180Non-packaged applications usually originated as Mac OS applications,
181so they will have creators.  If you're using Mac OS X 10.1.x, try
182using the creator instead of the bundle ID as a workaround (-c instead
183of -i).
184
185
186Q. Why doesn't launch support opening items as root?
187
188A. Apple eliminated this capability with the Mac OS X 10.1 Security
189Update.  If at some point Apple restores this capability, 'launch'
190will be ready to support it.
191
192
193Q. Why do I get an error -600?
194
195A. A typical occurrence of this would be:
196
197% launch -n .
198launch: can't open items: unable to connect to system service.
199Are you logged in? (-600)
200
201In order to perform certain operations, launch needs to talk to
202various system services owned by the currently logged-on user.  If you
203aren't using 'launch' from a terminal currently logged into the Mac OS
204X GUI, certain operations may not work.  Try opening Terminal.app,
205creating a new terminal, and trying again.
206
207Another possibility is to create your own interprocess messaging.
208For example, place this script in a file:
209
210#!/bin/sh
211PIPE=/tmp/.launchpipe
212[ -e $PIPE ] || mkfifo $PIPE
213while true; do
214    read opts < $PIPE
215    eval "/path/to/launch $opts" & # change this to launch's path
216done
217
218Then, define a function or alias.  For zsh:
219
220rlaunch() { echo $@ > /tmp/.launchpipe }
221
222Or for tcsh:
223
224alias rlaunch 'echo \!* > /tmp/.launchpipe'
225
226Start the shell script above from the console, then you can use
227'rlaunch' in place of 'launch' logged in from anywhere else.
228
229Thanks to robert <robert@allyourbass.org> for this suggestion.
230
231COMMENTS, SUGGESTIONS, BUG REPORTS, ETC.
232----------------------------------------
233
234Please send to the author, Nicholas Riley, at <launchsw@sabi.net>.
235
236VERSION HISTORY
237---------------
238
2391.0 - 23 October 2003
240 - work around CFBundle bug to report bundle identifiers and versions
241   from resource forks of unpackaged Carbon applications and Classic
242   applications [Lloyd Dupont]
243 - added descriptions for more error codes and clarified error
244   reporting
245 - output all errors to stderr
246 - provide better errors for -X option
247 - restored -m: OS X bug is fixed in Panther
248 - fixed a couple of tiny memory leaks
249 - added man page [Hisashi T Fujinaka]
250 - work around bug in LSOpenFromURLSpec opening multiple items in
251   Mac OS X 10.3
2521.0b2 - 9 March 2003
253 - fixed install instructions to create /usr/local/bin if needed
254 - show bundle version with text, hex and integer representations
2551.0b1 - 14 December 2002
256 - accept "slack" (default http) URLs and email addresses with -l
257 - accept input from stdin with '-'
258 - open URLs with arbitrary applications when specified without -l
259 - builds without compiler warnings
2601.0a9 - 2 April 2002
261 - license, comments changes
2621.0a8 - 29 March 2002
263 - errors with -l (from ICeCoffEE), added rlaunch script
2641.0a7 - 3 March 2002
265 - print dates, sizes, folder valence, locked status for -f
266 - don't abort on failure to obtain bundle information
2671.0a6 - 30 November 2001
268 - fixed incorrect messages, broken -u and crash on -nu
2691.0a5 - 28 November 2001
270 - print kind string for -f, still no new installer
2711.0a4 - 20 November 2001
272 - [try to] use Installer VISE instead of InstallAnywhere
2731.0a3 - 15 November 2001
274 - fixed package identification in -f, updated examples
2751.0a2 - 15 November 2001
276 - -f, removed broken -m
2771.0a1 - 14 November 2001
278 - renamed from "FindApp", launch by default, -u
2791.0d5 - 7 November 2001
280 - option -s for launching as root [nonfunctional]
2811.0d4 - 6 November 2001
282 - URL launching and Internet Config support
2831.0d3 - 4 November 2001
284 - more robust, support for docs without app
2851.0d2 - 4 November 2001
286 - options -opsbmhCX, -cin, documents
2871.0d1 - 26 August 2001
288 - returns path of application identified by creator
Note: See TracBrowser for help on using the repository browser.