Don't rely on filesystem's report of symlink length

[zeroinstall/solver.git] / 0launch.1

.TH 0LAUNCH 1 "2009" "Thomas Leonard" ""
.SH NAME
0launch \- download and run programs by URL

.SH SYNOPSIS

.B 0launch
[\fBOPTION\fP]... \fBINTERFACE\fP [\fBARG\fP]...

.B 0launch
--list [\fBSEARCH-TERM\fP]

.B 0launch
--import [\fBINTERFACE-FILES\fP]

.SH DESCRIPTION
.PP
0launch runs a program, identified by an `INTERFACE'. If the program is not
already on your computer, it downloads information about which versions are
available, and lets you choose one to download. It will also (automatically)
do the same for libraries the program needs.

.PP
0launch will also check for updates if it has been a long time since the last
check (configurable).
0launch therefore allows users to download and upgrade software without
needing root access.

.PP
An INTERFACE can be either a URL in the form `http://site/program' or
a local path name like `/path/to/program.xml'. For HTTP URLs, the remote
file is a GPG-signed XML document. Local interface files are not signed.

.SH EXAMPLES

.PP
When a program is available using 0launch, it will have an associated URL. To
run the program, simply invoke 0launch with this as an argument:

.B 0launch http://rox.sourceforge.net/2005/interfaces/Edit

.PP
The first time you do this, details about the program are downloaded and
cached, and you will be prompted to confirm the versions to use. In future,
the program will run directly from the cache without confirmation.

.PP
To check for new versions:

.B 0launch --refresh http://rox.sourceforge.net/2005/interfaces/Edit

.PP
To search the list of cached URLs:

.B 0launch --list Edit

.PP
To avoid having to keep typing the full URI, use the 0alias(1) command
to create shortcuts to run your programs.

.SH COMMAND-LINE OPTIONS

.TP
\fB--before=VERSION\fP
Choosen implementation's version number must be earlier than VERSION. i.e., force
the use of an old version the program.

.TP
\fB-c\fP, \fB--console\fP
Never use the GUI. Normally, 0launch switches to graphical mode if it needs to
download anything from the network (unless DISPLAY is not set).

.TP
\fB-d\fP, \fB--download-only\fP
Download any needed files, but stop before actually running the program.

.TP
\fB-D\fP, \fB--dry-run\fP
Just print what actions would be taken.

.TP
\fB-f\fP, \fB--feed\fP
Register (or unregister) an additional source of implementations. When you get
a CVS version of a project, it may contain an interface XML file. To add this
version to the list of available versions, use --feed on this XML file. The
file is not copied, so you don't need to re-add the file each time it is
updated.

Note that if you just want to run the program, you can invoke 0launch on the
interface file directly (without using --feed). This will force the injector to
use that version, but won't affect what happens when you run it using the URI
as normal. Use --feed when you want to use the CVS version even when using the
URI, or if the program is a library (and thus referenced by URI by other
programs).

Note also that the stability of CVS versions may be set to 'developer', in
which case you must set this as the preferred stability for the interface
(using the GUI).

.TP
\fB--get-selections\fP
Instead of running the program, just print the set of chosen implementations as
an XML document to stdout. This can be used later with \fB--set-selections\fP.

.TP
\fB-g\fP, \fB--gui\fP
Show the graphical policy editor. This allows you to select which version of
a program or library to use.

.TP
\fB-h\fP, \fB--help\fP
Show the built-in help text.

.TP
\fB-i\fP, \fB--import\fP
Import from files, not from the network. This is useful when testing an
interface file, to avoid uploading it to a remote server in order to download
it again. It might also be useful when installing from a CD or similar.
The file must have a trusted GPG digital signature, as when fetching from
the network. For unsigned interfaces, see --feed.

.TP
\fB-l\fP, \fB--list\fP
List all known interface (program) URIs. If a search term is given, only
URIs containing that string are shown (case insensitive).

.TP
\fB-m\fP, \fB--main=MAIN\fP
Run the specified executable instead of the default. If MAIN starts with '/'
then the path is relative to the implementation's top-level directory,
whereas otherwise it is relative to the directory containing the default
MAIN program. For example, if the default MAIN is \fBbin/svn\fP then
using \fB--main=svnadmin\fP will run \fB.../bin/svnadmin\fP instead.

.TP
\fB--not-before=VERSION\fP
Choosen implementation's version number must not be earlier than VERSION.
E.g., if you want to run version 2.0 or later, use \fB--not-before=2.0\fP.

.TP
\fB-o\fP, \fB--offline\fP
Run in off-line mode, overriding the default setting. In off-line mode, no
interfaces are refreshed even if they are out-of-date, and newer versions of
programs won't be downloaded even if the injector already knows about them
(e.g. from a previous refresh).

.TP
\fB-r\fP, \fB--refresh\fP
Fetch a fresh copy of all used interfaces. This will normally switch to GUI
mode, unless --console is also given. Note that using --refresh and --gui
together will check for updates to the GUI itself.

.TP
\fB--set-selections=FILE\fP
Instead of choosing suitable implementations using the policy, run exactly
the versions given in FILE. A suitable file can be created using the
\fB--get-selections\fP option described above.

.TP
\fB-s\fP, \fB--source\fP
The implementation of the main (root) interface must have an architecture
of the form '*-src' (normally a literal "*", but could be a compatible OS).
Dependencies are normal implementations, not source ones.

.TP
\fB-v\fP, \fB--verbose\fP
More verbose output. Use twice for even more verbose output.

.TP
\fB-V\fP, \fB--version\fP
Display version information.

.TP
\fB-w\fP, \fB--wrapper=COMMAND\fP
Instead of executing the chosen program directly, run \fBCOMMAND PROGRAM ARGS\fP.
This is useful for running debuggers and tracing tools on the program (rather
than on 0launch!). Note that the wrapper is executed in the environment selected
by the program; hence, this mechanism cannot be used for sandboxing. See the
DEBUGGING section below.

.TP
\fB--with-store=DIR\fP
Append a directory to the list of implementation caches.

.SH DEBUGGING TIPS

.PP
To debug 0launch itself, use the --verbose and --console options. For example:

.B $ 0launch -vvc http://myprog

.PP
To trace or debug programs run by 0launch, use the --wrapper option.
For example, to run \fBmyprog --help\fP, displaying all calls to open(2):

.B $ 0launch --wrapper="strace -e open" http://myprog --help

If your program is interpreted (e.g. a Python program), and you wish to debug
the interpreter running it, you can do it like this:

.B $ 0launch --wrapper="gdb --args python" http://myprog --help

.SH FILES

Configuration files (see freedesktop.org basedir spec):

.IP "~/.config/0install.net/injector/global"
Global configuration settings.

.IP "~/.config/0install.net/injector/trust"
List of trusted keys.

.IP "~/.config/0install.net/injector/user_overrides"
Per-interface settings, and extra feeds.

.PP
Cached data (can be re-downloaded if lost):

.IP "~/.cache/0install.net/interfaces"
Downloaded cached interface files.

.IP "~/.cache/0install.net/implementations"
Downloaded cached implementations, indexed by manifest digest.

.PP
See the 0store(1) man page for more information.

.SH LICENSE
.PP
Copyright (C) 2009 Thomas Leonard.

.PP
You may redistribute copies of this program under the terms of the GNU Lesser General Public License.
.SH BUGS
.PP
Please report bugs to the developer mailing list:

http://0install.net/support.html

.SH AUTHOR
.PP
The Zero Install Injector was created by Thomas Leonard.

.SH SEE ALSO
0alias(1), 0store(1)
.PP
The Zero Install web-site:

.B http://0install.net