xenial (1) 0install.1.gz

Provided by: 0install-core_2.10-2_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).

       --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