Removed unused code
[zeroinstall/zeroinstall-afb.git] / 0launch.1
blobbf4af7cd638cbeb60aa065af60a110b9e34fa423
1 .TH 0LAUNCH 1 "2010" "Thomas Leonard" ""
2 .SH NAME
3 0launch \(em download and run programs by URL
5 .SH SYNOPSIS
7 .B 0launch
8 [\fBOPTION\fP]... \fBINTERFACE\fP [\fBARG\fP]...
10 .B 0launch
11 \-\-list [\fBSEARCH\-TERM\fP]
13 .B 0launch
14 \-\-import [\fBFEED\-FILES\fP]
16 .SH DESCRIPTION
17 .PP
18 0launch runs a program, identified by an `INTERFACE'. If the program is not
19 already on your computer, it downloads information about which versions are
20 available, and lets you choose one to download. It will also (automatically)
21 do the same for libraries the program needs.
23 .PP
24 0launch will also check for updates if it has been a long time since the last
25 check (configurable).
27 .PP
28 Normally, INTERFACE is taken as a FEED, which can be either a URL in the form
29 `http://site/program' or a local path name like `/path/to/program.xml'. For
30 HTTP URLs, the remote file is a GPG-signed XML document. Local feed files
31 are not signed. The default one-to-one mapping from interface URIs to feed
32 URLs can be changed using the \-\-feed option.
34 .SH EXAMPLES
36 .PP
37 When a program is available using 0launch, it will have an associated URL. To
38 run the program, simply invoke 0launch with this as an argument:
40 .B 0launch http://rox.sourceforge.net/2005/interfaces/Edit
42 .PP
43 The first time you do this, details about the program are downloaded and
44 cached, and you will be prompted to confirm the versions to use. In future,
45 the program will run directly from the cache without confirmation.
47 .PP
48 To check for new versions:
50 .B 0launch \-\-refresh http://rox.sourceforge.net/2005/interfaces/Edit
52 .PP
53 To search the list of cached URLs:
55 .B 0launch \-\-list Edit
57 .PP
58 To avoid having to keep typing the full URI, use the 0alias(1) command
59 to create shortcuts to run your programs.
61 .SH COMMAND-LINE OPTIONS
63 .TP
64 \fB\-\-before=VERSION\fP
65 Chosen implementation's version number must be earlier than VERSION. i.e., force
66 the use of an old version the program.
68 .TP
69 \fB\-c\fP, \fB\-\-console\fP
70 Never use the GUI. Normally, 0launch switches to graphical mode if it needs to
71 download anything from the network (unless DISPLAY is not set).
73 .TP
74 \fB\-d\fP, \fB\-\-download\-only\fP
75 Download any needed files, but stop before actually running the program.
77 .TP
78 \fB\-D\fP, \fB\-\-dry\-run\fP
79 Just print what actions would be taken.
81 .TP
82 \fB\-f\fP, \fB\-\-feed\fP
83 Register (or unregister) an additional source of implementations. When you check out
84 a developer version of a project, it may contain an XML feed file. To add this
85 version to the list of available versions, use \-\-feed on this XML file. The
86 file is not copied, so you don't need to re-add the file each time it is
87 updated.
89 Note that if you just want to run the program, you can invoke 0launch on the
90 feed file directly (without using \-\-feed). This will force the injector to
91 use that version, but won't affect what happens when you run it using the URI
92 as normal. Use \-\-feed when you want to use the developer version even when
93 using the URI, or if the program is a library (and thus referenced by URI by
94 other programs).
96 .TP
97 \fB\-\-get\-selections\fP
98 Instead of running the program, just print the set of chosen implementations as
99 an XML document to stdout. This can be used later with \fB\-\-set\-selections\fP.
100 Use \fB\-\-select\-only\fP if you don't even want to download the packages.
103 \fB\-g\fP, \fB\-\-gui\fP
104 Show the graphical policy editor. This allows you to select which version of
105 a program or library to use.
108 \fB\-h\fP, \fB\-\-help\fP
109 Show the built-in help text.
112 \fB\-i\fP, \fB\-\-import\fP
113 Import from files, not from the network. This is useful when testing a
114 feed file, to avoid uploading it to a remote server in order to download
115 it again. It might also be useful when installing from a CD or similar.
116 The file must have a trusted GPG digital signature, as when fetching from
117 the network. For unsigned interfaces, see \-\-feed.
120 \fB\-l\fP, \fB\-\-list\fP
121 List all known interface (program) URIs. If a search term is given, only
122 URIs containing that string are shown (case insensitive).
125 \fB\-m\fP, \fB\-\-main=MAIN\fP
126 Run the specified executable instead of the default. If MAIN starts with '/'
127 then the path is relative to the implementation's top-level directory,
128 whereas otherwise it is relative to the directory containing the default
129 MAIN program. For example, if the default MAIN is \fBbin/svn\fP then
130 using \fB\-\-main=svnadmin\fP will run \fB.../bin/svnadmin\fP instead.
133 \fB\-\-not\-before=VERSION\fP
134 Chosen implementation's version number must not be earlier than VERSION.
135 E.g., if you want to run version 2.0 or later, use \fB\-\-not\-before=2.0\fP.
138 \fB\-o\fP, \fB\-\-offline\fP
139 Run in off-line mode, overriding the default setting. In off-line mode, no
140 interfaces are refreshed even if they are out-of-date, and newer versions of
141 programs won't be downloaded even if the injector already knows about them
142 (e.g. from a previous refresh).
145 \fB\-r\fP, \fB\-\-refresh\fP
146 Fetch a fresh copy of all used interfaces. This will normally switch to GUI
147 mode, unless \-\-console is also given.
150 \fB\-\-select\-only\fP
151 Download any required feeds and choose a set of implementations, but don't
152 actually download them. If there are stale feeds, check for updates first
153 (if we're not off-line).
156 \fB\-\-set\-selections=FILE\fP
157 Instead of choosing suitable implementations using the policy, run exactly
158 the versions given in FILE. A suitable file can be created using the
159 \fB\-\-get\-selections\fP option described above.
162 \fB\-s\fP, \fB\-\-source\fP
163 The implementation of the main (root) interface must have an architecture
164 of the form '*\-src' (normally a literal "*", but could be a compatible OS).
165 Dependencies are normal implementations, not source ones. See 0compile for
166 details.
169 \fB\-v\fP, \fB\-\-verbose\fP
170 More verbose output. Use twice for even more verbose output.
173 \fB\-V\fP, \fB\-\-version\fP
174 Display version information.
177 \fB\-w\fP, \fB\-\-wrapper=COMMAND\fP
178 Instead of executing the chosen program directly, run \fBCOMMAND PROGRAM ARGS\fP.
179 This is useful for running debuggers and tracing tools on the program (rather
180 than on 0launch!). Note that the wrapper is executed in the environment selected
181 by the program; hence, this mechanism cannot be used for sandboxing. See the
182 DEBUGGING section below.
185 \fB\-\-with\-store=DIR\fP
186 Append a directory to the list of implementation caches.
188 .SH DEBUGGING TIPS
191 To debug 0launch itself, use the \-\-verbose and \-\-console options. For example:
193 .B $ 0launch \-vvc http://myprog
196 To trace or debug programs run by 0launch, use the \-\-wrapper option.
197 For example, to run \fBmyprog \-\-help\fP, displaying all calls to open(2):
199 .B $ 0launch \-\-wrapper="strace \-e open" http://myprog \-\-help
201 If your program is interpreted (e.g. a Python program), and you wish to debug
202 the interpreter running it, you can do it like this:
204 .B $ 0launch \-\-wrapper="gdb \-\-args python" http://myprog \-\-help
206 .SH FILES
208 Configuration files (see freedesktop.org basedir spec):
210 .IP "~/.config/0install.net/injector/global"
211 Global configuration settings.
213 .IP "~/.config/0install.net/injector/trustdb.xml"
214 List of trusted keys.
216 .IP "~/.config/0install.net/injector/user_overrides"
217 Per-interface settings, and extra feeds.
220 Cached data (can be re-downloaded if lost):
222 .IP "~/.cache/0install.net/interfaces"
223 Downloaded cached feed files.
225 .IP "~/.cache/0install.net/implementations"
226 Downloaded cached implementations, indexed by manifest digest.
229 See the 0store(1) man page for more information.
231 .SH LICENSE
233 Copyright (C) 2010 Thomas Leonard.
236 You may redistribute copies of this program under the terms of the GNU Lesser General Public License.
237 .SH BUGS
239 Please report bugs to the developer mailing list:
241 http://0install.net/support.html
243 .SH AUTHOR
245 The Zero Install Injector was created by Thomas Leonard.
247 .SH SEE ALSO
248 0alias(1), 0store(1)
250 The Zero Install web-site:
252 .B http://0install.net