Avoid a TypeError when language is None and feed description is empty
[zeroinstall/solver.git] / 0launch.1
blob63443f965f8327c987d508f7650554d4c051975a
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\-\-show\fP
163 Print the selected versions in a human-readable format to stdout. The display
164 is similar to the GUI; it shows the program being run and its dependencies.
165 For each selected component, the version number is displayed and its location
166 on the file-system. Implies \-\-download-only.
169 \fB\-s\fP, \fB\-\-source\fP
170 The implementation of the main (root) interface must have an architecture
171 of the form '*\-src' (normally a literal "*", but could be a compatible OS).
172 Dependencies are normal implementations, not source ones. See 0compile for
173 details.
176 \fB\-v\fP, \fB\-\-verbose\fP
177 More verbose output. Use twice for even more verbose output.
180 \fB\-V\fP, \fB\-\-version\fP
181 Display version information.
184 \fB\-w\fP, \fB\-\-wrapper=COMMAND\fP
185 Instead of executing the chosen program directly, run \fBCOMMAND PROGRAM ARGS\fP.
186 This is useful for running debuggers and tracing tools on the program (rather
187 than on 0launch!). Note that the wrapper is executed in the environment selected
188 by the program; hence, this mechanism cannot be used for sandboxing. See the
189 DEBUGGING section below.
192 \fB\-\-with\-store=DIR\fP
193 Append a directory to the list of implementation caches.
195 .SH DEBUGGING TIPS
198 To debug 0launch itself, use the \-\-verbose and \-\-console options. For example:
200 .B $ 0launch \-vvc http://myprog
203 To trace or debug programs run by 0launch, use the \-\-wrapper option.
204 For example, to run \fBmyprog \-\-help\fP, displaying all calls to open(2):
206 .B $ 0launch \-\-wrapper="strace \-e open" http://myprog \-\-help
208 If your program is interpreted (e.g. a Python program), and you wish to debug
209 the interpreter running it, you can do it like this:
211 .B $ 0launch \-\-wrapper="gdb \-\-args python" http://myprog \-\-help
213 .SH FILES
215 Configuration files (see freedesktop.org basedir spec):
217 .IP "~/.config/0install.net/injector/global"
218 Global configuration settings.
220 .IP "~/.config/0install.net/injector/trustdb.xml"
221 List of trusted keys.
223 .IP "~/.config/0install.net/injector/user_overrides"
224 Per-interface settings, and extra feeds.
227 Cached data (can be re-downloaded if lost):
229 .IP "~/.cache/0install.net/interfaces"
230 Downloaded cached feed files.
232 .IP "~/.cache/0install.net/implementations"
233 Downloaded cached implementations, indexed by manifest digest.
236 See the 0store(1) man page for more information.
238 .SH LICENSE
240 Copyright (C) 2010 Thomas Leonard.
243 You may redistribute copies of this program under the terms of the GNU Lesser General Public License.
244 .SH BUGS
246 Please report bugs to the developer mailing list:
248 http://0install.net/support.html
250 .SH AUTHOR
252 The Zero Install Injector was created by Thomas Leonard.
254 .SH SEE ALSO
255 0install(1), 0alias(1), 0store(1)
257 The Zero Install web-site:
259 .B http://0install.net