Provided by: 0install-core_2.15.1-1_amd64 bug

NAME

       0install — a decentralised software installation system

SYNOPSIS

   Downloading and running:
       0install select URI

       0install download URI

       0install run URI [ARG]...

       0install update URI

   Applications:
       0install add NAME URI

       0install show NAME

       0install update NAME

       0install whatchanged NAME

       0install destroy NAME

   Other commands:
       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

DESCRIPTION

       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.

GLOBAL OPTIONS

       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.

SUB-COMMANDS

   0install select [OPTIONS] URI
       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.

   0install download [OPTIONS] URI
       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.

   0install run [OPTIONS] URI [ARGS]
       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.

   0install update [OPTIONS] URI
       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'.

   0install import FEED
       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).

   0install add-feed [INTERFACE] FEED
       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).

   0install remove-feed [INTERFACE] FEED
       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.

   0install list-feeds URI
       List all extra feeds added to URI using `add-feed'.

   0install list [PATTERN]
       List  all  locally-cached  interface  (program) URIs. If a search term is given, only URIs
       containing that string are shown (case insensitive).

   0install search QUERY
       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.

   0install config [NAME [VALUE]]
       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.

   0install man COMMAND
       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 --"

   0install digest DIRECTORY | ARCHIVE [EXTRACT]
       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.

   0install --version
       This can be used (without any command) the get version of 0install itself.

APPLICATIONS

       An  application  provides  an  easy  way to run a program without typing the full URL each
       time.

   0install add NAME URI
       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.

   0install show NAME | SELECTIONS
       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).

   0install update NAME
       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.

   0install whatchanged NAME
       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.

   0install destroy NAME
       The application NAME is deleted, along with any launchers added for it.

   0install store ...
       Provides  low-level  access to the store of cached implementations. See the 0store(1) man-
       page for details.

   0install slave
       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.

DEBUGGING TIPS

       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

FILES

       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.

ENVIRONMENT VARIABLES

       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.

LICENSE

       Copyright (C) 2013 Thomas Leonard.

       You  may  redistribute  copies  of  this program under the terms of the GNU Lesser General
       Public License.

BUGS

       Please report bugs to the developer mailing list:

       http://0install.net/support.html

AUTHOR

       Zero Install was created by Thomas Leonard, with help from many others. See  the  Git  log
       for details.

SEE ALSO

       0store(1), 0launch(1)

       The Zero Install web-site:

       http://0install.net