0install — a decentralised software installation system
0install select URI
0install download URI
0install run URI [ARG]...
0install update URI
0install add NAME URI
0install show NAME
0install update NAME
0install whatchanged NAME
0install destroy NAME
0install config [NAME [VALUE]]
0install import FEED
0install list PATTERN
0install search QUERY
0install add-feed [INTERFACE] FEED
0install remove-feed [INTERFACE] FEED
0install list-feeds URI
0install man COMMAND
0install digest DIRECTORY | ARCHIVE [EXTRACT]
0install store ...
0install slave
Zero Install is a decentralised cross-distribution software installation system.
Programs and libraries are identified by URIs, and there is no need for a
central repository. Zero Install ensures that packages cannot conflict with
each other and that programs can be shared between mutually untrusting users.
See the web-site for more information:
http://0install.net/
The simplest case is to ask 0install to run a program, given its URI. For
example:
0install run http://rox.sourceforge.net/2005/interfaces/Edit
The first time you do this, details about available versions of the program are
downloaded and cached, along with details about any libraries it depends on.
Zero Install will run a solver to select the best version of each component to
use. For example, it will select binaries that are compatible with your CPU
and operating system, in your preferred language, and marked
"stable" (by default).
If $DISPLAY is set, 0install will display a window where you can confirm (or
change) the selected versions.
It will then download the corresponding archives for those versions and store
them in the cache too. Each package unpacks to its own directory.
Finally, 0install will launch the program, setting environment variables to let
it locate its libraries.
The first non-option argument to 0install is the particular sub-command you want
to perform; these are described in detail in the next section.
However, there are some options that apply to all operations. These are:
-
-c, --console
- Never use the GUI. Normally, 0install switches to graphical
mode if it needs to download anything from the network (unless DISPLAY is
not set).
- --dry-run
- Do not save any changes to disk, and do not actually run
the program. Instead, just print out the changes that would have been
made. Note that, as 0install is a very safe system, there is generally no
need to use this option. However, it can be useful as a learning aid or
for testing.
-
-h, --help
- Show the built-in help text.
-
-o, --offline
- Run in off-line mode, overriding the default setting. This
prevents 0install from checking for updates, and from downloading updates
even if it knows about them.
-
-v, --verbose
- More verbose output. Use twice for even more verbose
output.
- --with-store=DIR
- Append a directory to the list of implementation caches.
Each sub-directory of DIR contains the contents of one version of a
program or library.
Select a version of the program identified by URI, and compatible versions of
all of its dependencies. The information about available versions is
downloaded if it's not yet in the cache.
The URI can be an HTTP URL, such as `http://site/program.xml' or a local path
name like `file:///path/to/program.xml'.
For HTTP URLs, the remote file is a signed XML document. If the key is not known
and trusted, you will be prompted to accept it first. Local feed files are not
signed (any signature will be ignored).
You can also specify a local selections document, as created previously using
the
--xml option, rather than a feed. In that case, 0install simply
uses those versions without running the solver.
After selecting (but not downloading) a set of versions, the selection is
displayed in a human-readable format. Use
--xml to get machine-readable
output.
If a set of versions cannot be selected using the cached information, 0install
will check for updates first.
If a set of versions can be selected based on the currently-cached information,
but that information is getting stale, 0install will immediately return the
current selection and will also start a background process to check for
updates. The `freshness' configuration setting controls when cached
information is considered to be stale.
Options for select:
- --before=VERSION
- Select a version earlier than VERSION (i.e. force the use
of an old version of the program). You can only restrict the version of
the program itself using this option, not the version of any dependencies.
- --command=COMMAND
- Some programs provide multiple commands. This selects which
one you want. Common values are `run' (the default), `test' (used by
0test) and `compile' (used by 0compile). You can also use
--command="" if you don't want to run any command (for
example, if the package contains data rather than a program).
- --may-compile
- Treat every source implementation as a potential binary.
This can be used to find what needs to be compiled to run a program.
Currently this is only available for "0install select".
- --message=MESSAGE
- If we show a dialog box for the download, display MESSAGE
to the user to explain why the download is needed.
- --not-before=VERSION
- The selected version must not be earlier than VERSION. e.g.
if you want to run version 2.0 or later, use --not-before=2.0.
- --refresh
- Download a fresh copy of all used feeds before selecting.
Normally, cached copies will be used if available (checking for updates
later, in the background).
- --source
- Select source code rather than a binary. This is used
internally by `0compile'.
- --version=RANGE
- Require a version of the main program within the given
range. This can be a simple number (e.g. --version=2.3) or a range
(e.g. --version=2.3..!2.7). For ranges, either end may be omitted.
The "!" indicates that the range excludes the final value.
Alternatives can be separated by "|", e.g. "2.6..!3 |
3.2.." (allows 2.6, 2.7, 3.2, etc, but not 2.5 or 3.0).
You can also force a particular implementation by its ID, using the syntax
"=FEED/ID". ID must be escaped: Letters, digits, '-', '.', and
characters > 127 stay as they are; "/" becomes
"__"; and other characters become "_code_", where code
is the lowercase hex value of the byte.
- --version-for=URI RANGE
- Specifies the range (as for --version) for any
library or sub-component. If URI is the URI of the main program
then this is equivalent to using --version.
- --xml
- Print the set of chosen implementations as an XML document
to stdout. This can be used later with the `download' and `run'
sub-commands.
`select' returns an exit status of zero if it selected a set of versions, and a
status of 1 if it could not find a consistent set.
This behaves similarly to `0install select', except that it also downloads the
selected versions if they are not already cached. Unlike `select', it does not
print the selected versions by default.
All options for `select' can also be used for `download'. In addition, these
options are available:
- --show
- Print the selected versions in a human-readable format to
stdout.
`download' returns an exit status of zero if it selected a suitable set of
versions and they are now all downloaded and in the cache. It returns a status
of 1 otherwise.
This behaves similarly to `0install download', except that it also runs the
program after ensuring it is in the cache.
To avoid having to keep typing the full URI, use the `0install add' command to
create shortcuts to run your programs.
All options for `select' can also be used for `run' except for
--xml. In
addition, these options are available:
-
-m, --main=MAIN
- 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
bin/svn then using --main=svnadmin will run
.../bin/svnadmin instead. This option has been largely superseded
by the newer --command option.
-
-w, --wrapper=WRAPPER
- Instead of executing the chosen program directly, run
WRAPPER PROGRAM ARGS. This is useful for running debuggers and
tracing tools on the program (rather than on 0install!). 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.
Note that any options after `URI' will be passed to the program being run rather
than being interpreted by 0install.
`run' returns an exit status of 1 if the download step failed. Otherwise, the
exit status will be the exit status of the program being run.
Check for updates to the program and download them if found. This is similar to
0install download --refresh, except that it prints information about
whether any changes were found.
The options are the same as for `select'.
Import a feed from a local file, as if it had been downloaded from the network.
This is useful when testing a feed file, to avoid uploading it to a remote
server in order to download it again. The file must have a trusted digital
signature, as when fetching from the network.
It is also useful when installing a feed from a CD or similar. Note: to create a
full bundle, for archiving or distribution on CD, see
0export(1).
Register an additional source of implementations (versions) of a program.
For example, when you check out a developer version of a project, it may contain
an XML feed file. To add this version to the list of available versions, use
`add-feed' on the XML file. The file is not copied, so you don't need to
re-add the feed each time it is updated. You will probably also want to set
the `help_with_testing' configuration option to ensure that testing versions
are selected by default.
Note that if you just want to run the program, you can invoke 0install on the
feed file directly (without using `add-feed'). This will force the it to use
that version, but won't affect what happens when you run it using the URI as
normal. Use `add-feed' when you want to use the developer version even when
using the URI, or if the program is a library (and thus referenced by URI by
other programs).
Un-register a feed, reversing the effect of `add-feed'. If INTERFACE is not
given, you will be prompted to choose which INTERFACE to remove it from.
List all extra feeds added to URI using `add-feed'.
List all locally-cached interface (program) URIs. If a search term is given,
only URIs containing that string are shown (case insensitive).
Send the query string to the mirror server and display any interfaces it
returns. Note that the default mirror server indexes all known feeds,
regardless of quality; you must decide whether to trust the programs before
running them.
View or change configuration settings.
With no arguments, `0install config' displays all configuration settings. With
one argument, it displays the current value of the named setting. With two
arguments, it sets the setting to the given value.
Show the man-page of the given command. If the single argument
COMMAND is
a launcher script (created by "0install add") then the man-page is
searched for by 0install, otherwise the arguments are passed through directly
to the system's man command. This allows you to do:
alias man="0install man --"
Calculate the secure hash of an implementation. This is a unique
"fingerprint" of a directory and all the files and subdirectories it
contains. When publishing a program using 0install, this value must be placed
in the XML file.
-
-m, --algorithm=HASH
- Select the secure hash function to be used. Supported
values are "sha1new" (the default), "sha256" and
"sha256new".
If an archive is given then the hash is for the directory that would be created
if the archive were unpacked (or the EXTRACT subdirectory of it, if one is
specified).
-
-m, --manifest
-d,
--digest
These options control whether to display the manifest itself (one line for each
file or directory) or the manifest's digest (or both). If neither option is
given, the digest is displayed.
This can be used (without any command) the get version of 0install itself.
An application provides an easy way to run a program without typing the full URL
each time.
Creates a new application called
NAME (which can be whatever you want) to
run the program
URI. A directory (by default,
~/.config/0install.net/apps/NAME) is created to record the current selections,
as would be produced by "0install select --xml URI".
A launcher command (also called
NAME) will be created in $PATH to provide
an easy way to run the application. For example, to add and run ROX-Filer:
$ 0install add rox http://rox.sourceforge.net/2005/interfaces/ROX-Filer
$ rox
If additional requirements are given (as for "0install select", e.g.
--before), they are stored with the application and apply to all updates.
Show the current selections for this application (or the contents of the given
selections file). By default, the output is in the same format as for
"0install select", and the --xml option has the same effect.
-
-r, --root-uri
- Just display the root interface URI (e.g. the URI passed to
"0install add" when this application was created).
The feeds used to make the selections are updated and a new set of selections is
generated and saved into the application's directory. Even if you don't run
this command explicitly, 0install will check for updates if you run the
program and it hasn't been updated for a while. This happens in the background
and does not delay starting the program.
If additional requirements are given (as for "0install select", e.g.
--before), they update the requirements stored with the application and apply
to this and future updates.
Show the differences between the current and previous selections for this
application. Various times may also be displayed: "Last checked" is
the last time we successfully checked for updates (even if none was found),
"Last attempted update" is the last time we tried to check for
updates, and "Last update" is the last time changes were found. If
"Last attempted update" is shown, then either the last updated
failed or an update is currently in progress.
By default, only changes that resulted in a different version being selected are
shown. To see all changes, use --full. Note that at most one set of selections
is saved per day.
The application
NAME is deleted, along with any launchers added for it.
Provides low-level access to the store of cached implementations. See the
0store(1) man-page for details.
Run 0install in slave mode (currently EXPERIMENTAL and likely to change). You
can send JSON requests to the process's standard input and receive responses
from its standard output.
To debug 0install itself, use the --verbose and --console options. For example:
$ 0install -vvc run http://myprog
To trace or debug programs run by 0install, use the --wrapper option. For
example, to run
myprog --help, displaying all calls to
open(2):
$ 0install run --wrapper="strace -e open" http://myprog --help
To run the application under the gdb debugger:
$ 0install run --wrapper="gdb --args" http://myprog --help
Configuration files (see freedesktop.org basedir spec):
- ~/.config/0install.net/injector/global
- Global configuration settings.
- ~/.config/0install.net/injector/trustdb.xml
- List of trusted keys.
- ~/.config/0install.net/injector/feeds
- Per-feed information (e.g. time of last check).
- ~/.config/0install.net/injector/interfaces
- Per-interface settings (preferred stability and any extra
feeds that have been registered).
Cached data (can be re-downloaded if lost):
- ~/.cache/0install.net/interfaces
- Downloaded cached feed files.
- ~/.cache/0install.net/implementations
- Downloaded cached implementations, indexed by manifest
digest.
See the
0store(1) man page for more information.
- XDG_*
- The configuration and cache directories can be changed
using XDG_CONFIG_HOME, XDG_CONFIG_DIRS,
XDG_CACHE_HOME and XDG_CACHE_DIRS, as usual.
- ZEROINSTALL_PORTABLE_BASE
-
If this is set, then the XDG_ variables are ignored and the configuration
and cache are stored in $ZEROINSTALL_PORTABLE_BASE/config and
$ZEROINSTALL_PORTABLE_BASE/cache instead.
- ZEROINSTALL_EXTERNAL_STORE
-
When 0install wants to add an archive to the cache, it calls this program
instead of doing it itself. This is used internally on Windows to connect
to some .NET code. It may change in future.
Copyright (C) 2013 Thomas Leonard.
You may redistribute copies of this program under the terms of the GNU Lesser
General Public License.
Please report bugs to the developer mailing list:
http://0install.net/support.html
Zero Install was created by Thomas Leonard, with help from many others. See the
Git log for details.
0store(1),
0launch(1)
The Zero Install web-site:
http://0install.net