0launch.1

   1 .TH 0LAUNCH 1 "2010" "Thomas Leonard" ""
   2 .SH NAME
   3 0launch \(em download and run programs by URL
   4
   5 .SH SYNOPSIS
   6
   7 .B 0launch
   8 [\fBOPTION\fP]... \fBINTERFACE\fP [\fBARG\fP]...
   9
  10 .B 0launch
  11 \-\-list [\fBSEARCH\-TERM\fP]
  12
  13 .B 0launch
  14 \-\-import [\fBFEED\-FILES\fP]
  15
  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.
  22
  23 .PP
  24 0launch will also check for updates if it has been a long time since the last
  25 check (configurable).
  26
  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.
  33
  34 .SH EXAMPLES
  35
  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:
  39
  40 .B 0launch http://rox.sourceforge.net/2005/interfaces/Edit
  41
  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.
  46
  47 .PP
  48 To check for new versions:
  49
  50 .B 0launch \-\-refresh http://rox.sourceforge.net/2005/interfaces/Edit
  51
  52 .PP
  53 To search the list of cached URLs:
  54
  55 .B 0launch \-\-list Edit
  56
  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.
  60
  61 .SH COMMAND-LINE OPTIONS
  62
  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.
  67
  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).
  72
  73 .TP
  74 \fB\-d\fP, \fB\-\-download\-only\fP
  75 Download any needed files, but stop before actually running the program.
  76
  77 .TP
  78 \fB\-D\fP, \fB\-\-dry\-run\fP
  79 Just print what actions would be taken.
  80
  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.
  88
  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).
  95
  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.
 101
 102 .TP
 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.
 106
 107 .TP
 108 \fB\-h\fP, \fB\-\-help\fP
 109 Show the built-in help text.
 110
 111 .TP
 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.
 118
 119 .TP
 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).
 123
 124 .TP
 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.
 131
 132 .TP
 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.
 136
 137 .TP
 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).
 143
 144 .TP
 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.
 148
 149 .TP
 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).
 154
 155 .TP
 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.
 160
 161 .TP
 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.
 167
 168 .TP
 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.
 174
 175 .TP
 176 \fB\-v\fP, \fB\-\-verbose\fP
 177 More verbose output. Use twice for even more verbose output.
 178
 179 .TP
 180 \fB\-V\fP, \fB\-\-version\fP
 181 Display version information.
 182
 183 .TP
 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.
 190
 191 .TP
 192 \fB\-\-with\-store=DIR\fP
 193 Append a directory to the list of implementation caches.
 194
 195 .SH DEBUGGING TIPS
 196
 197 .PP
 198 To debug 0launch itself, use the \-\-verbose and \-\-console options. For example:
 199
 200 .B $ 0launch \-vvc http://myprog
 201
 202 .PP
 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):
 205
 206 .B $ 0launch \-\-wrapper="strace \-e open" http://myprog \-\-help
 207
 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:
 210
 211 .B $ 0launch \-\-wrapper="gdb \-\-args python" http://myprog \-\-help
 212
 213 .SH FILES
 214
 215 Configuration files (see freedesktop.org basedir spec):
 216
 217 .IP "~/.config/0install.net/injector/global"
 218 Global configuration settings.
 219
 220 .IP "~/.config/0install.net/injector/trustdb.xml"
 221 List of trusted keys.
 222
 223 .IP "~/.config/0install.net/injector/user_overrides"
 224 Per-interface settings, and extra feeds.
 225
 226 .PP
 227 Cached data (can be re-downloaded if lost):
 228
 229 .IP "~/.cache/0install.net/interfaces"
 230 Downloaded cached feed files.
 231
 232 .IP "~/.cache/0install.net/implementations"
 233 Downloaded cached implementations, indexed by manifest digest.
 234
 235 .PP
 236 See the 0store(1) man page for more information.
 237
 238 .SH LICENSE
 239 .PP
 240 Copyright (C) 2010 Thomas Leonard.
 241
 242 .PP
 243 You may redistribute copies of this program under the terms of the GNU Lesser General Public License.
 244 .SH BUGS
 245 .PP
 246 Please report bugs to the developer mailing list:
 247
 248 http://0install.net/support.html
 249
 250 .SH AUTHOR
 251 .PP
 252 The Zero Install Injector was created by Thomas Leonard.
 253
 254 .SH SEE ALSO
 255 0install(1), 0alias(1), 0store(1)
 256 .PP
 257 The Zero Install web-site:
 258
 259 .B http://0install.net