source: trunk/launch/launch/README @ 166

Last change on this file since 166 was 166, checked in by Nicholas Riley, 17 years ago

VERSION: Updated for 1.0.1.

main.c: Updated copyright statement. Updated for 1.0.1. Added -U,
triggers OPTS.forceURLs. Added kLSMultipleSessionsNotSupportedErr,
nsvErr. Cleaned up string encoding handling; works much better now.
Split code into stringFromURLIsRemote, utf8StringFromCFStringRef, and
utf8StringFromOSType. Display "contents: zero items" instead of "0
items" in printMoreInfoForURL. Remove extraneous "./" at beginning of
displayed paths. Get versions of non-{applications, packages} and
info from nonbundled apps with CFBundleCopyInfoDictionaryForURL.
Replaced some error codes with numbers so we support building on 10.2
again.

launch.1: Updated for 1.0.1 and -U option.

README: Updated for 1.0.1. Fixed a paste-o in the uninstallation
instructions.

package-launch.sh: Use zsh explicitly. Build as deployment. Fix
permissions. Make tarball contents owned by root/wheel.

File size: 10.5 KB
Line 
1launch 1.0.1 [3 April 2005]
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/launch.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.8 with Xcode 1.5, and does not require any
66additional 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, creating
205a new terminal window, 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.1 - 3 April 2005
240 - prefer files to URLs; added -U for old behavior
241 - don't display extraneous leading './' on file paths
242 - display 'zero items', not '0 items', for consistency
243 - display versions of non-applications
244 - read Info.plists embedded in unbundled Mach-O applications
245 - non-ASCII arguments are now handled with the filesystem, rather
246   than the system encoding [Derrick Bass]
247 - explicitly use UTF-8 everywhere else to properly interpret and
248   display non-ASCII filenames and URLs
249 - reading OSTypes and 'vers' resources, and opening URLs with
250   Internet Config still uses the system encoding, converting as
251   necessary for display
252 - should be buildable on 10.2 again
2531.0 - 23 October 2003
254 - work around CFBundle bug to report bundle identifiers and versions
255   from resource forks of unpackaged Carbon applications and Classic
256   applications [Lloyd Dupont]
257 - added descriptions for more error codes and clarified error
258   reporting
259 - output all errors to stderr
260 - provide better errors for -X option
261 - restored -m: OS X bug is fixed in Panther
262 - fixed a couple of tiny memory leaks
263 - added man page [Hisashi T Fujinaka]
264 - work around bug in LSOpenFromURLSpec opening multiple items in
265   Mac OS X 10.3
2661.0b2 - 9 March 2003
267 - fixed install instructions to create /usr/local/bin if needed
268 - show bundle version with text, hex and integer representations
2691.0b1 - 14 December 2002
270 - accept "slack" (default http) URLs and email addresses with -l
271 - accept input from stdin with '-'
272 - open URLs with arbitrary applications when specified without -l
273 - builds without compiler warnings
2741.0a9 - 2 April 2002
275 - license, comments changes
2761.0a8 - 29 March 2002
277 - errors with -l (from ICeCoffEE), added rlaunch script
2781.0a7 - 3 March 2002
279 - print dates, sizes, folder valence, locked status for -f
280 - don't abort on failure to obtain bundle information
2811.0a6 - 30 November 2001
282 - fixed incorrect messages, broken -u and crash on -nu
2831.0a5 - 28 November 2001
284 - print kind string for -f, still no new installer
2851.0a4 - 20 November 2001
286 - [try to] use Installer VISE instead of InstallAnywhere
2871.0a3 - 15 November 2001
288 - fixed package identification in -f, updated examples
2891.0a2 - 15 November 2001
290 - -f, removed broken -m
2911.0a1 - 14 November 2001
292 - renamed from "FindApp", launch by default, -u
2931.0d5 - 7 November 2001
294 - option -s for launching as root [nonfunctional]
2951.0d4 - 6 November 2001
296 - URL launching and Internet Config support
2971.0d3 - 4 November 2001
298 - more robust, support for docs without app
2991.0d2 - 4 November 2001
300 - options -opsbmhCX, -cin, documents
3011.0d1 - 26 August 2001
302 - returns path of application identified by creator
Note: See TracBrowser for help on using the repository browser.