source: trunk/launch/launch/README @ 314

launch 1.1.1 [unreleased]
============

A command-line launcher for Mac OS X in the spirit of open(1).

Written by Nicholas Riley <mailto:launchsw@sabi.net>.
Obtain updates from <http://web.sabi.net/nriley/software/>.

WHAT IS IT?
-----------

Apple provides a simple command-line launching program called 'open'
with Mac OS X.  It offers few options - launching applications by name
or by path, launching TextEdit, or opening a number of applications,
documents, folders, or URLs.  With the exception of special support for
TextEdit (open -e), 'launch' does all this and:

- opens URLs, directly or in your preferred helper application (-l)
- lets you specify applications by their four-character creator
  (e.g. 'ToyS') or Java-style bundle ID (e.g. com.apple.scripteditor),
  both of which allow you to move or rename an application without
  changing references to it
- asks applications to print documents, something the OS X Finder
  didn't get until Mac OS X 10.4
- allows you to pipe output to GUI applictions
- launches applications in the background
- launches Carbon applications in Classic
- displays file information including type, creator, bundle ID,
  data and resource fork sizes, dates and version
- reports errors intelligibly
- and much more!

'launch' is useful by itself, but is even better when used in scripts.
Assign a shell command to your favorite Mac OS text, graphics or
resource editor.  Go to your favorite Web site with a few keystrokes.

Like 'open', 'launch' provides one half of the round-trip between
Terminal.app and the Finder.  You can drag and drop icons or proxy icons
into Terminal.app to insert their paths into command lines.  To go in the
other direction, just type 'launch .' (or 'open .') to open a Finder window
showing the current directory.

INSTALLATION
------------

The commands below install the 'launch' tool in /usr/local/bin, which
is in the default path.  You should subsequently be able to use
'launch' by typing its name.  If you wish to install it somewhere else,
modify the install line as appropriate.

% sudo /usr/bin/install -d /usr/local/bin /usr/local/man/man1
% sudo /usr/bin/install -c launch /usr/local/bin
% sudo /usr/bin/install -c launch.1 /usr/local/man/man1
% rehash

Uninstallation:

% sudo rm -f /usr/local/bin/launch /usr/local/man/man1/launch.1

COMPILATION
-----------

An Xcode project, 'launch.xcodeproj', is included.  A precompiled
Universal binary is also provided.  'launch' was developed and tested
under Mac OS X 10.4.8 with Xcode 2.4, and does not require any
additional software to build.

USAGE
-----

Just type 'launch' by itself to receive usage information.

Some examples:

% launch -c 'R*ch'
[BBEdit opens]
                                
% launch -pbc 'R*ch' test.txt
[BBEdit starts printing test.txt in the background]

% ls -l | launch -c CWIE -
[CodeWarrior IDE opens with an untitled document containing the file list]

% launch -i org.mozilla.camino http://www.apple.com/
[Camino opens Apple's Web site]

% launch -l launchsw@sabi.net
[Your preferred email client opens a new message to comment on launch]

% launch -f /Applications/Preview.app
/Applications/Preview.app: Mac OS X application package
        type: 'APPL'    creator: 'prvw'
        architecture: Intel 80x86, PowerPC
        bundle ID: com.apple.Preview
        version: 3.0.8
        kind: Application
        content type ID: com.apple.application-bundle
        contents: 1 item
[...]

A scripting example: a zsh function which provides an OS X wrapper
around emacsclient and the Carbon build of GNU Emacs, using launch and
appswitch (another one of my command-line tools).

    e() {
      ( emacsclient -n $@ >&/dev/null && \
        appswitch -a Emacs ) || \
      ( launch -ba Emacs && \
        until { emacsclient -n $@ >&/dev/null } do sleep 1; done;
        appswitch -a Emacs )
      export EDITOR=emacsclient
    }

FREQUENTLY ASKED QUESTIONS
--------------------------

Q. How do I discover bundle IDs for applications?

A. The -f option to launch can help.  Say you have OmniWeb in the
/Applications/Internet folder, and want to find out its bundle ID.
Type 'launch -f', and drop the OmniWeb icon on Terminal:

% launch -f /Applications/Internet/OmniWeb.app
/Applications/Internet/OmniWeb.app: scriptable Mac OS X application package 
        type: 'APPL'    creator: 'OWEB'
        architecture: PowerPC, Intel 80x86
        bundle ID: com.omnigroup.OmniWeb5

Note that bundle IDs are not case-sensitive: com.barebones.BBEdit is
the same as com.barebones.bbedit.


Q. Why does application X open a file with a name beginning with 
'launch-stationery-'?  

A. Your application does not support stationery.  Applications which
support stationery respond to it by creating a new untitled document
with the contents of the stationery.  Most Cocoa applications, such as
TextEdit, do not support stationery.  (Omni Group applications are a
notable exception.)  If you're looking for a text editor which
supports stationery, try BBEdit, Tex-Edit Plus, the CodeWarrior IDE,
or almost any other Carbon editor.

For the curious: launch processes input by simultaneously reading it
and writing to a temporary stationery file.  Once reading is complete,
launch opens the stationery file with your selected application, and
deletes the stationery after one minute (as a safeguard, it is not
possible to accurately gauge how long it will take for the application
to open the stationery).


Q. Why can't I use -f with -c to get info on an application with a
given creator (or -f with -i for a bundle ID)?

A. This feature may be added to a later version (or add it yourself!),
but there is a workaround.  Instead of:

% launch -f -c 'Doug'
launch: can't get information (-f) on item(s) using an application (-u, -c, -i, -a)

use:

% launch -f "`launch -nc 'Doug'`"
/Volumes/GrayApps/Utilities/Resorcerer 2.4/Resorcerer: scriptable Mac OS X application [Carbon, prefers native OS X]
        type: 'APPL'    creator: 'Doug'
        bundle ID: com.mathemaesthetics.resorcerer
        version: 2.4 [0x2418010 = 37847056]
        kind: Application
[...]


Q. Why doesn't launch support opening items as root?

A. Apple eliminated this capability with the Mac OS X 10.1 Security
Update.  If at some point Apple restores this capability, 'launch'
will be ready to support it.


Q. Why do I get an error -600?

A. A typical occurrence of this would be:

% launch -n .
launch: can't open items: unable to connect to system service.
Are you logged in? (-600)

In order to perform certain operations, launch needs to talk to
various system services owned by the currently logged-on user.  If you
aren't using 'launch' from a terminal currently logged into the Mac OS
X GUI, certain operations may not work.  Try opening Terminal, creating
a new terminal window, and trying again.

Another possibility is to create your own interprocess messaging.
For example, place this script in a file:

#!/bin/sh
PIPE=/tmp/.launchpipe
[ -e $PIPE ] || mkfifo $PIPE
while true; do
    read opts < $PIPE
    eval "/path/to/launch $opts" & # change this to launch's path
done

Then, define a function or alias.  For zsh:

rlaunch() { echo $@ > /tmp/.launchpipe }

Or for tcsh:

alias rlaunch 'echo \!* > /tmp/.launchpipe'

Start the shell script above from the console, then you can use
'rlaunch' in place of 'launch' logged in from anywhere else.

Thanks to robert <robert@allyourbass.org> for this suggestion.

COMMENTS, SUGGESTIONS, BUG REPORTS, ETC.
----------------------------------------

Please send to the author, Nicholas Riley, at <launchsw@sabi.net>.

VERSION HISTORY
---------------

1.1.1 - unreleased
 - updated error codes for Mac OS X 10.4
1.1 - 30 October 2006
 - -L: send "launch" (ascr/noop) event to app, bypasses automatic
   opening of untitled document, etc.
 - -o: pass command-line arguments (broken, r. 4474993)
 - display content type ID (UTI)    
 - display architecture of Mach-O files
 - switched to new LSOpen APIs (now requires Mac OS X 10.4 or later)
 - switched to new date formatting APIs (the old ones are deprecated)
 - for compatibility with open(1), take app path as argument to -a
 - Universal Binary, compatible with Intel Macs [Peter Hosey]
1.0.1 - 3 April 2005
 - prefer files to URLs; added -U for old behavior
 - don't display extraneous leading './' on file paths
 - display 'zero items', not '0 items', for consistency
 - display versions of non-applications
 - read Info.plists embedded in unbundled Mach-O applications
 - non-ASCII arguments are now handled with the filesystem, rather
   than the system encoding [Derrick Bass]
 - explicitly use UTF-8 everywhere else to properly interpret and
   display non-ASCII filenames and URLs
 - reading OSTypes and 'vers' resources, and opening URLs with
   Internet Config still uses the system encoding, converting as
   necessary for display
 - should be buildable on 10.2 again
1.0 - 23 October 2003
 - work around CFBundle bug to report bundle identifiers and versions
   from resource forks of unpackaged Carbon applications and Classic
   applications [Lloyd Dupont]
 - added descriptions for more error codes and clarified error
   reporting
 - output all errors to stderr
 - provide better errors for -X option
 - restored -m: OS X bug is fixed in Panther
 - fixed a couple of tiny memory leaks
 - added man page [Hisashi T Fujinaka]
 - work around bug in LSOpenFromURLSpec opening multiple items in
   Mac OS X 10.3
1.0b2 - 9 March 2003
 - fixed install instructions to create /usr/local/bin if needed
 - show bundle version with text, hex and integer representations
1.0b1 - 14 December 2002
 - accept "slack" (default http) URLs and email addresses with -l
 - accept input from stdin with '-'
 - open URLs with arbitrary applications when specified without -l
 - builds without compiler warnings
1.0a9 - 2 April 2002
 - license, comments changes
1.0a8 - 29 March 2002
 - errors with -l (from ICeCoffEE), added rlaunch script
1.0a7 - 3 March 2002
 - print dates, sizes, folder valence, locked status for -f
 - don't abort on failure to obtain bundle information
1.0a6 - 30 November 2001
 - fixed incorrect messages, broken -u and crash on -nu
1.0a5 - 28 November 2001
 - print kind string for -f, still no new installer
1.0a4 - 20 November 2001
 - [try to] use Installer VISE instead of InstallAnywhere
1.0a3 - 15 November 2001
 - fixed package identification in -f, updated examples
1.0a2 - 15 November 2001
 - -f, removed broken -m
1.0a1 - 14 November 2001
 - renamed from "FindApp", launch by default, -u
1.0d5 - 7 November 2001
 - option -s for launching as root [nonfunctional]
1.0d4 - 6 November 2001
 - URL launching and Internet Config support
1.0d3 - 4 November 2001
 - more robust, support for docs without app
1.0d2 - 4 November 2001
 - options -opsbmhCX, -cin, documents
1.0d1 - 26 August 2001
 - returns path of application identified by creator