10INSTALL(1) 0INSTALL(1)
2
6 0install — a decentralised software installation system
7
10 Downloading and running:
11 0install select URI
12 0install download URI
14 0install run URI [ARG]...
16 0install update URI
18 Applications:
21 0install add NAME URI
22 0install show NAME
24 0install update NAME
26 0install whatchanged NAME
28 0install destroy NAME
30 Other commands:
33 0install config [NAME [VALUE]]
34 0install import FEED
36 0install list PATTERN
38 0install search QUERY
40 0install add-feed [INTERFACE] FEED
42 0install remove-feed [INTERFACE] FEED
44 0install list-feeds URI
46 0install man COMMAND
48 0install digest DIRECTORY | ARCHIVE [EXTRACT]
50 0install store ...
52 0install slave
54
57 Zero Install is a decentralised cross-distribution software installa‐
58 tion system. Programs and libraries are identified by URIs, and there
59 is no need for a central repository. Zero Install ensures that packages
60 cannot conflict with each other and that programs can be shared between
61 mutually untrusting users. See the web-site for more information:
62 http://0install.net/
64 The simplest case is to ask 0install to run a program, given its URI.
66 For example:
67 0install run http://rox.sourceforge.net/2005/interfaces/Edit
69 The first time you do this, details about available versions of the
72 program are downloaded and cached, along with details about any
73 libraries it depends on.
74 Zero Install will run a solver to select the best version of each com‐
76 ponent to use. For example, it will select binaries that are compatible
77 with your CPU and operating system, in your preferred language, and
78 marked "stable" (by default).
79 If $DISPLAY is set, 0install will display a window where you can con‐
81 firm (or change) the selected versions.
82 It will then download the corresponding archives for those versions and
84 store them in the cache too. Each package unpacks to its own directory.
85 Finally, 0install will launch the program, setting environment vari‐
87 ables to let it locate its libraries.
88
91 The first non-option argument to 0install is the particular sub-command
92 you want to perform; these are described in detail in the next section.
93 However, there are some options that apply to all operations. These
95 are:
96 -c, --console
99 Never use the GUI. Normally, 0install switches to graphical mode
100 if it needs to download anything from the network (unless DIS‐
101 PLAY is not set).
102 --dry-run
105 Do not save any changes to disk, and do not actually run the
106 program. Instead, just print out the changes that would have
107 been made. Note that, as 0install is a very safe system, there
108 is generally no need to use this option. However, it can be use‐
109 ful as a learning aid or for testing.
110 -h, --help
113 Show the built-in help text.
114 -o, --offline
117 Run in off-line mode, overriding the default setting. This pre‐
118 vents 0install from checking for updates, and from downloading
119 updates even if it knows about them.
120 -v, --verbose
123 More verbose output. Use twice for even more verbose output.
124 --with-store=DIR
127 Append a directory to the list of implementation caches. Each
128 sub-directory of DIR contains the contents of one version of a
129 program or library.
130
133 0install select [OPTIONS] URI
134 Select a version of the program identified by URI, and compatible ver‐
135 sions of all of its dependencies. The information about available ver‐
136 sions is downloaded if it's not yet in the cache.
137 The URI can be an HTTP URL, such as `http://site/program.xml' or a
140 local path name like `file:///path/to/program.xml'.
141 For HTTP URLs, the remote file is a signed XML document. If the key is
144 not known and trusted, you will be prompted to accept it first. Local
145 feed files are not signed (any signature will be ignored).
146 You can also specify a local selections document, as created previously
149 using the --xml option, rather than a feed. In that case, 0install sim‐
150 ply uses those versions without running the solver.
151 After selecting (but not downloading) a set of versions, the selection
154 is displayed in a human-readable format. Use --xml to get machine-read‐
155 able output.
156 If a set of versions cannot be selected using the cached information,
159 0install will check for updates first.
160 If a set of versions can be selected based on the currently-cached
163 information, but that information is getting stale, 0install will imme‐
164 diately return the current selection and will also start a background
165 process to check for updates. The `freshness' configuration setting
166 controls when cached information is considered to be stale.
167 Options for select:
170 --before=VERSION
173 Select a version earlier than VERSION (i.e. force the use of an
174 old version of the program). You can only restrict the version
175 of the program itself using this option, not the version of any
176 dependencies.
177 --command=COMMAND
180 Some programs provide multiple commands. This selects which one
181 you want. Common values are `run' (the default), `test' (used by
182 0test) and `compile' (used by 0compile). You can also use --com‐
183 mand="" if you don't want to run any command (for example, if
184 the package contains data rather than a program).
185 --may-compile
188 Treat every source implementation as a potential binary. This
189 can be used to find what needs to be compiled to run a program.
190 Currently this is only available for "0install select".
191 --message=MESSAGE
194 If we show a dialog box for the download, display MESSAGE to the
195 user to explain why the download is needed.
196 --not-before=VERSION
199 The selected version must not be earlier than VERSION. e.g. if
200 you want to run version 2.0 or later, use --not-before=2.0.
201 --refresh
204 Download a fresh copy of all used feeds before selecting. Nor‐
205 mally, cached copies will be used if available (checking for
206 updates later, in the background).
207 --source
210 Select source code rather than a binary. This is used internally
211 by `0compile'.
212 --version=RANGE
215 Require a version of the main program within the given range.
216 This can be a simple number (e.g. --version=2.3) or a range
217 (e.g. --version=2.3..!2.7). For ranges, either end may be omit‐
218 ted. The "!" indicates that the range excludes the final value.
219 Alternatives can be separated by "|", e.g. "2.6..!3 | 3.2.."
220 (allows 2.6, 2.7, 3.2, etc, but not 2.5 or 3.0).
221 You can also force a particular implementation by its ID, using
223 the syntax "=FEED/ID". ID must be escaped: Letters, digits,
224 '-', '.', and characters > 127 stay as they are; "/" becomes
225 "__"; and other characters become "_code_", where code is the
226 lowercase hex value of the byte.
227 --version-for=URI RANGE
230 Specifies the range (as for --version) for any library or sub-
231 component. If URI is the URI of the main program then this is
232 equivalent to using --version.
233 --xml Print the set of chosen implementations as an XML document to
236 stdout. This can be used later with the `download' and `run'
237 sub-commands.
238 `select' returns an exit status of zero if it selected a set of ver‐
242 sions, and a status of 1 if it could not find a consistent set.
243 0install download [OPTIONS] URI
247 This behaves similarly to `0install select', except that it also down‐
248 loads the selected versions if they are not already cached. Unlike
249 `select', it does not print the selected versions by default.
250 All options for `select' can also be used for `download'. In addition,
252 these options are available:
253 --show Print the selected versions in a human-readable format to std‐
256 out.
257 `download' returns an exit status of zero if it selected a suitable set
260 of versions and they are now all downloaded and in the cache. It
261 returns a status of 1 otherwise.
262 0install run [OPTIONS] URI [ARGS]
266 This behaves similarly to `0install download', except that it also runs
267 the program after ensuring it is in the cache.
268 To avoid having to keep typing the full URI, use the `0install add'
271 command to create shortcuts to run your programs.
272 All options for `select' can also be used for `run' except for --xml.
275 In addition, these options are available:
276 -m, --main=MAIN
279 Run the specified executable instead of the default. If MAIN
280 starts with '/' then the path is relative to the implementa‐
281 tion's top-level directory, whereas otherwise it is relative to
282 the directory containing the default MAIN program. For example,
283 if the default MAIN is bin/svn then using --main=svnadmin will
284 run .../bin/svnadmin instead. This option has been largely
285 superseded by the newer --command option.
286 -w, --wrapper=WRAPPER
289 Instead of executing the chosen program directly, run WRAPPER
290 PROGRAM ARGS. This is useful for running debuggers and tracing
291 tools on the program (rather than on 0install!). Note that the
292 wrapper is executed in the environment selected by the program;
293 hence, this mechanism cannot be used for sandboxing. See the
294 DEBUGGING section below.
295 Note that any options after `URI' will be passed to the program being
298 run rather than being interpreted by 0install.
299 `run' returns an exit status of 1 if the download step failed. Other‐
302 wise, the exit status will be the exit status of the program being run.
303 0install update [OPTIONS] URI
306 Check for updates to the program and download them if found. This is
307 similar to 0install download --refresh, except that it prints informa‐
308 tion about whether any changes were found.
309 The options are the same as for `select'.
312 0install import FEED
315 Import a feed from a local file, as if it had been downloaded from the
316 network. This is useful when testing a feed file, to avoid uploading
317 it to a remote server in order to download it again. The file must have
318 a trusted digital signature, as when fetching from the network.
319 It is also useful when installing a feed from a CD or similar. Note: to
322 create a full bundle, for archiving or distribution on CD, see
323 0export(1).
324 0install add-feed [INTERFACE] FEED
327 Register an additional source of implementations (versions) of a pro‐
328 gram.
329 For example, when you check out a developer version of a project, it
332 may contain an XML feed file. To add this version to the list of avail‐
333 able versions, use `add-feed' on the XML file. The file is not copied,
334 so you don't need to re-add the feed each time it is updated. You will
335 probably also want to set the `help_with_testing' configuration option
336 to ensure that testing versions are selected by default.
337 Note that if you just want to run the program, you can invoke 0install
340 on the feed file directly (without using `add-feed'). This will force
341 the it to use that version, but won't affect what happens when you run
342 it using the URI as normal. Use `add-feed' when you want to use the
343 developer version even when using the URI, or if the program is a
344 library (and thus referenced by URI by other programs).
345 0install remove-feed [INTERFACE] FEED
348 Un-register a feed, reversing the effect of `add-feed'. If INTERFACE is
349 not given, you will be prompted to choose which INTERFACE to remove it
350 from.
351 0install list-feeds URI
354 List all extra feeds added to URI using `add-feed'.
355 0install list [PATTERN]
358 List all locally-cached interface (program) URIs. If a search term is
359 given, only URIs containing that string are shown (case insensitive).
360 0install search QUERY
363 Send the query string to the mirror server and display any interfaces
364 it returns. Note that the default mirror server indexes all known
365 feeds, regardless of quality; you must decide whether to trust the pro‐
366 grams before running them.
367 0install config [NAME [VALUE]]
370 View or change configuration settings.
371 With no arguments, `0install config' displays all configuration set‐
374 tings. With one argument, it displays the current value of the named
375 setting. With two arguments, it sets the setting to the given value.
376 0install man COMMAND
379 Show the man-page of the given command. If the single argument COMMAND
380 is a launcher script (created by "0install add") then the man-page is
381 searched for by 0install, otherwise the arguments are passed through
382 directly to the system's man command. This allows you to do:
383 alias man="0install man --"
385 0install digest DIRECTORY | ARCHIVE [EXTRACT]
388 Calculate the secure hash of an implementation. This is a unique "fin‐
389 gerprint" of a directory and all the files and subdirectories it con‐
390 tains. When publishing a program using 0install, this value must be
391 placed in the XML file.
392 -m, --algorithm=HASH
395 Select the secure hash function to be used. Supported values are
396 "sha1new" (the default), "sha256" and "sha256new".
397 If an archive is given then the hash is for the directory that would be
400 created if the archive were unpacked (or the EXTRACT subdirectory of
401 it, if one is specified).
402 -m, --manifest
405 -d, --digest
407 These options control whether to display the manifest itself (one line
409 for each file or directory) or the manifest's digest (or both). If nei‐
410 ther option is given, the digest is displayed.
411 0install --version
414 This can be used (without any command) the get version of 0install
415 itself.
416
419 An application provides an easy way to run a program without typing the
420 full URL each time.
421 0install add NAME URI
424 Creates a new application called NAME (which can be whatever you want)
425 to run the program URI. A directory (by default, ~/.con‐
426 fig/0install.net/apps/NAME) is created to record the current selec‐
427 tions, as would be produced by "0install select --xml URI".
428 A launcher command (also called NAME) will be created in $PATH to pro‐
431 vide an easy way to run the application. For example, to add and run
432 ROX-Filer:
433 $ 0install add rox http://rox.sourceforge.net/2005/interfaces/ROX-Filer
435 $ rox
437 If additional requirements are given (as for "0install select", e.g.
440 --before), they are stored with the application and apply to all
441 updates.
442 0install show NAME | SELECTIONS
445 Show the current selections for this application (or the contents of
446 the given selections file). By default, the output is in the same for‐
447 mat as for "0install select", and the --xml option has the same effect.
448 -r, --root-uri
451 Just display the root interface URI (e.g. the URI passed to
452 "0install add" when this application was created).
453 0install update NAME
456 The feeds used to make the selections are updated and a new set of
457 selections is generated and saved into the application's directory.
458 Even if you don't run this command explicitly, 0install will check for
459 updates if you run the program and it hasn't been updated for a while.
460 This happens in the background and does not delay starting the program.
461 If additional requirements are given (as for "0install select", e.g.
464 --before), they update the requirements stored with the application and
465 apply to this and future updates.
466 0install whatchanged NAME
469 Show the differences between the current and previous selections for
470 this application. Various times may also be displayed: "Last checked"
471 is the last time we successfully checked for updates (even if none was
472 found), "Last attempted update" is the last time we tried to check for
473 updates, and "Last update" is the last time changes were found. If
474 "Last attempted update" is shown, then either the last updated failed
475 or an update is currently in progress.
476 By default, only changes that resulted in a different version being
479 selected are shown. To see all changes, use --full. Note that at most
480 one set of selections is saved per day.
481 0install destroy NAME
484 The application NAME is deleted, along with any launchers added for it.
485 0install store ...
488 Provides low-level access to the store of cached implementations. See
489 the 0store(1) man-page for details.
490 0install slave
493 Run 0install in slave mode (currently EXPERIMENTAL and likely to
494 change). You can send JSON requests to the process's standard input and
495 receive responses from its standard output.
496
499 To debug 0install itself, use the --verbose and --console options. For
500 example:
501 $ 0install -vvc run http://myprog
503 To trace or debug programs run by 0install, use the --wrapper option.
506 For example, to run myprog --help, displaying all calls to open(2):
507 $ 0install run --wrapper="strace -e open" http://myprog --help
509 To run the application under the gdb debugger:
511 $ 0install run --wrapper="gdb --args" http://myprog --help
513
516 Configuration files (see freedesktop.org basedir spec):
517 ~/.config/0install.net/injector/global
520 Global configuration settings.
521 ~/.config/0install.net/injector/trustdb.xml
524 List of trusted keys.
525 ~/.config/0install.net/injector/feeds
528 Per-feed information (e.g. time of last check).
529 ~/.config/0install.net/injector/interfaces
532 Per-interface settings (preferred stability and any extra feeds
533 that have been registered).
534 Cached data (can be re-downloaded if lost):
537 ~/.cache/0install.net/interfaces
540 Downloaded cached feed files.
541 ~/.cache/0install.net/implementations
544 Downloaded cached implementations, indexed by manifest digest.
545 See the 0store(1) man page for more information.
548
551 XDG_* The configuration and cache directories can be changed using
552 XDG_CONFIG_HOME, XDG_CONFIG_DIRS, XDG_CACHE_HOME and
553 XDG_CACHE_DIRS, as usual.
554 ZEROINSTALL_PORTABLE_BASE
557 If this is set, then the XDG_ variables are ignored and the con‐
559 figuration and cache are stored in $ZEROINSTALL_PORTA‐
560 BLE_BASE/config and $ZEROINSTALL_PORTABLE_BASE/cache instead.
561 ZEROINSTALL_EXTERNAL_STORE
564 When 0install wants to add an archive to the cache, it calls
566 this program instead of doing it itself. This is used internally
567 on Windows to connect to some .NET code. It may change in
568 future.
569
572 Copyright (C) 2013 Thomas Leonard.
573 You may redistribute copies of this program under the terms of the GNU
576 Lesser General Public License.
577
579 Please report bugs to the developer mailing list:
580 http://0install.net/support.html
582
585 Zero Install was created by Thomas Leonard, with help from many others.
586 See the Git log for details.
587
590 0store(1), 0launch(1)
591 The Zero Install web-site:
593 http://0install.net
595Thomas Leonard 2013 0INSTALL(1)