source: trunk/launch/launch/README @ 651

Last change on this file since 651 was 651, checked in by Nicholas Riley, 6 years ago

Make buildable on OS X 10.8 (remove obsolete CoreGraphics? error), 32-bit only.

Fix a tiny buffer overflow.

Don't use printf to print things that aren't format strings.

Bump version number.

File size: 10.7 KB
Line 
1launch 1.1.1 [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
64Universal binary is also provided.  'launch' was developed and tested
65under Mac OS X 10.5.2 with Xcode 3.1, 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.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        architecture: Intel 80x86, PowerPC
94        bundle ID: com.apple.Preview
95        version: 3.0.8
96        kind: Application
97        content type ID: com.apple.application-bundle
98        contents: 1 item
99[...]
100
101A scripting example: a zsh function which provides an OS X wrapper
102around emacsclient and the Carbon build of GNU Emacs, using launch and
103appswitch (another one of my command-line tools).
104
105    e() {
106      ( emacsclient -n $@ >&/dev/null && \
107        appswitch -a Emacs ) || \
108      ( launch -ba Emacs && \
109        until { emacsclient -n $@ >&/dev/null } do sleep 1; done;
110        appswitch -a Emacs )
111      export EDITOR=emacsclient
112    }
113
114FREQUENTLY ASKED QUESTIONS
115--------------------------
116
117Q. How do I discover bundle IDs for applications?
118
119A. The -f option to launch can help.  Say you have OmniWeb in the
120/Applications/Internet folder, and want to find out its bundle ID.
121Type 'launch -f', and drop the OmniWeb icon on Terminal:
122
123% launch -f /Applications/Internet/OmniWeb.app
124/Applications/Internet/OmniWeb.app: scriptable Mac OS X application package
125        type: 'APPL'    creator: 'OWEB'
126        architecture: PowerPC, Intel 80x86
127        bundle ID: com.omnigroup.OmniWeb5
128
129Note that bundle IDs are not case-sensitive: com.barebones.BBEdit is
130the same as com.barebones.bbedit.
131
132
133Q. Why does application X open a file with a name beginning with
134'launch-stationery-'? 
135
136A. Your application does not support stationery.  Applications which
137support stationery respond to it by creating a new untitled document
138with the contents of the stationery.  Most Cocoa applications, such as
139TextEdit, do not support stationery.  (Omni Group applications are a
140notable exception.)  If you're looking for a text editor which
141supports stationery, try BBEdit, Tex-Edit Plus, the CodeWarrior IDE,
142or almost any other Carbon editor.
143
144For the curious: launch processes input by simultaneously reading it
145and writing to a temporary stationery file.  Once reading is complete,
146launch opens the stationery file with your selected application, and
147deletes the stationery after one minute (as a safeguard, it is not
148possible to accurately gauge how long it will take for the application
149to open the stationery).
150
151
152Q. Why can't I use -f with -c to get info on an application with a
153given creator (or -f with -i for a bundle ID)?
154
155A. This feature may be added to a later version (or add it yourself!),
156but there is a workaround.  Instead of:
157
158% launch -f -c 'Doug'
159launch: can't get information (-f) on item(s) using an application (-u, -c, -i, -a)
160
161use:
162
163% launch -f "`launch -nc 'Doug'`"
164/Volumes/GrayApps/Utilities/Resorcerer 2.4/Resorcerer: scriptable Mac OS X application [Carbon, prefers native OS X]
165        type: 'APPL'    creator: 'Doug'
166        bundle ID: com.mathemaesthetics.resorcerer
167        version: 2.4 [0x2418010 = 37847056]
168        kind: Application
169[...]
170
171
172Q. Why doesn't launch support opening items as root?
173
174A. Apple eliminated this capability with the Mac OS X 10.1 Security
175Update.  If at some point Apple restores this capability, 'launch'
176will be ready to support it.
177
178
179Q. Why do I get an error -600?
180
181A. A typical occurrence of this would be:
182
183% launch -n .
184launch: can't open items: unable to connect to system service.
185Are you logged in? (-600)
186
187In order to perform certain operations, launch needs to talk to
188various system services owned by the currently logged-on user.  If you
189aren't using 'launch' from a terminal currently logged into the Mac OS
190X GUI, certain operations may not work.  Try opening Terminal, creating
191a new terminal window, and trying again.
192
193Another possibility is to create your own interprocess messaging.
194For example, place this script in a file:
195
196#!/bin/sh
197PIPE=/tmp/.launchpipe
198[ -e $PIPE ] || mkfifo $PIPE
199while true; do
200    read opts < $PIPE
201    eval "/path/to/launch $opts" & # change this to launch's path
202done
203
204Then, define a function or alias.  For zsh:
205
206rlaunch() { echo $@ > /tmp/.launchpipe }
207
208Or for tcsh:
209
210alias rlaunch 'echo \!* > /tmp/.launchpipe'
211
212Start the shell script above from the console, then you can use
213'rlaunch' in place of 'launch' logged in from anywhere else.
214
215Thanks to robert <robert@allyourbass.org> for this suggestion.
216
217COMMENTS, SUGGESTIONS, BUG REPORTS, ETC.
218----------------------------------------
219
220Please send to the author, Nicholas Riley, at <launchsw@sabi.net>.
221
222VERSION HISTORY
223---------------
224
2251.1.1 - unreleased
226 - update error codes for OS X 10.8
227 - read Info.plists embedded in all Mach-O binaries (e.g. hdiutil)
228 - display alias targets
2291.1 - 30 October 2006
230 - -L: send "launch" (ascr/noop) event to app, bypasses automatic
231   opening of untitled document, etc.
232 - -o: pass command-line arguments (broken, r. 4474993)
233 - display content type ID (UTI)   
234 - display architecture of Mach-O files
235 - switched to new LSOpen APIs (now requires Mac OS X 10.4 or later)
236 - switched to new date formatting APIs (the old ones are deprecated)
237 - for compatibility with open(1), take app path as argument to -a
238 - Universal Binary, compatible with Intel Macs [Peter Hosey]
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.