Provided by: usepackage_1.14-1_amd64 bug

NAME

       usepackage - Usepackage Environment Manager

SYNOPSIS

       See use(1).

DESCRIPTION

       Usepackage  is an environment management program. It is based on the principle of packages
       - collections of executables that share a common set of necessary  environment  variables,
       such as PATH, MANPATH or LD_LIBRARY_PATH.

       For  each  given  package,  use  sources  the appropriate environment information into the
       current shell.  The environment information is specified in packages files, see PACKAGES.

       The usepackage executable is the backend program used to generate environment  information
       suitable for sourcing into a running shell. The use frontend should be invoked to actually
       effect changes to the environment, see use(1).

   OPTIONS
       -v     Output verbose information to the standard error stream.

       -s     Silence warnings for un-matched packages. This is useful in a shell rc script  when
              a  package is known not to be available on all architectures that the shell is used
              on, see PACKAGES.

       -c     Force csh style environment output.

       -b     Force bourne shell style environment output.

       -f file
              Specify an alternate initial configuration file, see PACKAGES.

       -l     List available packages and groups, see ANNOTATIONS and GROUPS.

PACKAGES

       Usepackage reads package environment information from the configuration file as follows:

   LOAD ORDER
       When Usepackage starts up, it loads an initial configuration file, the name of  this  file
       may  be given on the command line (see OPTIONS), otherwise it defaults to the builtin name
       "usepackage.conf" (see FILES).  This file is located  by  searching  along  a  path  which
       defaults to:

            /etc:~:.

       This path may be overridden with the PACKAGES_PATH environment variable (see ENVIRONMENT).
       A packages file may contain inclusion directives which cause the sourcing of  other  files
       at given points. An inclusion directive looks like:

            (include file-name)

       The  same  location mechanism is used to find "file-name" as for the initial configuration
       file. A package file name may also be given as an absolute file name or may be shell-style
       user directory, tilde (~), relative.

   SYNTAX
       A  package  file  consists  of  comments,  delimited  by  a  leading  hash (#), or package
       definitions of the form:

            package [arch [os [version [host [shell]]]]]
                 [<= requires ...] : setting [, setting ...] ;

       The package, arch, os, version, host, and shell parts may be simple  shell-style  patterns
       of the form:

       *              matches anything.

       foo*           matches "foo", "foobar" etc.

       {foo,bar}      matches "foo" or "bar".

       The  requires  list  specifies  the names of other packages which must be sourced into the
       environment before the settings for this package are processed.

       A setting is either a variable definition, an alias definition (both described below) or a
       section  of  text  to  be  directly  evaluated in the shell, delimited with <[ and ]>, for
       example:

            <[ /usr/local/bin/test-init ]>

       When Usepackage searches for the definition for a particular  package,  it  compares  each
       line  in  the  packages  file  against the name of the package given (package) and system-
       dependant information for the execution host, as obtained by uname(2).   This  information
       is  the  hardware implementation (platform), the operating system name (os), the operating
       system version (version) and the hostname (host). Comparisons are case-insensitive.  If  a
       match is obtained then the given variable definitions and script sections are processed to
       modify the environment. A  variable definition may have one of the following forms:

            var-name = "string"
            var-name = path-list
            var-name += path-list
            var-name += "string"
            var-name =+ path-list
            var-name =+ "string"

       The first sets the given variable to a literal string value, the  second  sets  the  given
       variable to a path list, the third prepends the current value of a variable with the given
       path list, and the fourth interprets the literal string as a path list and prepends it  to
       the  current  value of the variable. The fourth and fifth forms do the same, but append to
       the current value of the variable. Path lists are colon (:) separated lists of directories
       and  may  contain shell-style tilde (~), user-relative, directories which will be expanded
       automatically (except when the path list is given as a literal string).  When  pre-pending
       paths to a variable, duplicate paths are removed from the original value first.

       In  addition,  Usepackage can optionally test for the existence of paths before setting or
       adding them to variables. This is done with the test form of the above operators:

            var-name ?= path-list
            var-name ?+= path-list
            var-name ?+= "string"

       These operate as per the definitions above, but will ignore  path  components  that  don't
       exist.

       An alias definition has one of the following forms:

            alias name = name
            alias name = path
            alias name = "string"

       These will define a matching shell alias.

   GROUPS
       In  addition  to  the  package  definitions  in  a  packages file, there may also be group
       definitions. These have the following syntax:

            group := package [, package ...] ;

       Usepackage searches for a given package name in the defined groups  first,  if  the  given
       name  matchs a group name then the packages defined as part of that group are sourced into
       the environment together. A group definition may not reference other groups  and  may  not
       contain patterns.

   ANNOTATIONS
       In  order to give useful package information to the user, annotations may be placed in the
       packages file that give summaries of packages. These annotations have the form:

            >> name : "description" <<

       Usepackage collects these annotations together and displays them when called with  the  -l
       flag, see OPTIONS.  These annotations have no impact on the package mechanism and need not
       necessarily be beside or correspond to the  package  definitions  (although  this  is  the
       sensible way to arrange things).

   EXAMPLE
       The following fragment of a packages file illustrates the main features:

            # GNU software is available everywhere:

            >> GNU : "The GNU project software" <<

            GNU :                     PATH += /usr/local/gnu/bin,
                                      MANPATH += /usr/local/gnu/man ;

            # CVS requires RCS which is found in the GNU package, but
            # is only available on SPARC Solaris machines:

            >> CVS : "Concurrent Versions System revision control" <<

            CVS sun4* SunOS 5.* <= GNU :
                                      CVSROOT = /usr/src/cvsroot,
                                      CVSEDITOR = "vi",
                                      PATH += /usr/local/cvs/bin,
                                      MANPATH += /usr/local/cvs/man ;

            # User bin directories (Solaris will run SunOS 4 binaries):
            # (Only added to the path if the directories actually exist)

            >> user : "User's own programs" <<

            user sun4* SunOS :        PATH ?+= ~/bin/sun4 ;
            user sun4* SunOS 5.* :    PATH ?+= ~/bin/solaris ;
            user alpha OSF :          PATH ?+= ~/bin/alpha ;

            # Useful aliases:

            aliases : alias more = less,
                      alias ls = "ls --color",
                      alias cc = /usr/bin/gcc ;

            # Special function for zsh:

            >> zsh-function : "Special zsh function" <<

            zsh-function * * * * zsh :
                  <[ hello() { echo "Hello World!"; } ]> ;

            # include standard packages:

            (include packages.standard)

            # security hole:

            dot :                     PATH += . ;

            # groups:

            user-setup := standard, user ;
            programmer-setup := standard, CVS, user, dot ;

       Note  the  use  of  Operating  System  version  numbers to distinguish between SunOS 4 and
       Solaris (SunOS 5), the use of "sun4*" to match the multiple different platform versions of
       SPARC  machines  (sun4m,  sun4c, etc.) and the fact that package "user" on a SPARC Solaris
       machine will match both of the first two lines of the "user" package section, resulting in
       the "solaris" directory and the "sun4" directory being added into the PATH.

       Assuming  the  appropriate  shell  setup  script  has been sourced - see use(1) - then the
       following command will cause the CVS environment (including the  GNU  environment)  to  be
       sourced:

            $ use CVS

       Note that on a DEC Alpha machine, this will generate a warning like:

            $ use CVS
            warning: no match for package `CVS' on this host.

       In  a shell script which is executed on a number of different platforms (such as the shell
       startup script). These warnings may be silenced (see OPTIONS).

FILES

       /usr/share/usepackage/usepackage.conf
                      The default master packages file.

       /usr/share/usepackage/use.csh
                      Shell setup for csh and derivatives.

       /usr/share/usepackage/use.bsh
                      Shell setup for bourne shell and derivatives.

       /usr/share/usepackage/use.ksh
                      Shell setup for ksh.

       /usr/bin/usepackage
                      The underlying Usepackage executable.

ENVIRONMENT

       Other than the reading and re-definition of environment variables for package  setup,  use
       also uses the following environment variables for user configuration:

       PACKAGES_PATH  Colon-separated   path   list   giving   the   directories  to  search  for
                      configuration files.  Shell-style  tilde  (~)  user-directory  escapes  are
                      expanded.

       HOME           If  present  in  the environment, this is used to provide the expansion for
                      the tilde (~) user-directory.

       SHELL          If present in the environment, the last path component of this is used  for
                      shell  matching  (see SYNTAX) and detecting the style of environment output
                      that should be used (see OPTIONS).

COPYRIGHT

       Usepackage Environment Manager
       Copyright (C) 1995-2020  Jonathan Hogg  <me@jonathanhogg.com>

       This program is free software; you can redistribute it and/or modify it under the terms of
       the  GNU  General  Public  License  as  published  by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;
       without  even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program;
       if  not,  write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
       MA  02111-1307  USA

SEE ALSO

       use(1), csh(1), sh(1), ksh(1), env(1), environ(5), getenv(3C), uname(1), uname(2)