EXAMPLE

     /usr/etc:~:.

     (include file-name)

     package platform os version host [<= requires ...] :
          variable-def [, variable-def ...] ;

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

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

     >> name : "description" <<

     # GNU software is available everywhere:

     $ use CVS

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

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

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

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

# 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 sources (see SYNOPSIS), 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

The default master packages file.

Shell setup for csh and derivatives.

Shell setup for bourne shell and derivatives.

Shell setup for ksh.

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:

Colon-separated path list giving the directories to search for the master packages file and included files. Shell-style tilde (~) user-directory escapes are expanded.

COPYRIGHT

Copyright (C) 1995-2001 Jonathan Hogg.

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., 675 Mass Ave, Cambridge, MA 02139, USA.

SEE ALSO

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

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

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

The first packages file to be read-in is the master packages file, the name of this file may be given on the command line (see OPTIONS) or otherwise defaults to the builtin name "packages.master" (see FILES). This file is located by searching along a path which defaults to:

     DEFAULT_PACKAGE_PATH

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 a given points. An inclusion directive looks like:

     (`include' file-name)

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

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

     package platform os version host [<= requires ...] :
          variable-def [, variable-def ...] ;

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

*

matches anything.

foo*

matches "foo", "foobar" etc.

{foo,bar}

matches "foo" or "bar".

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 are processed to modify the environment. A variable definition may be one of three forms:

          var-name = "string"
          var-name = path-list
          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. 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.

The requires list specifies the names of other packages which must be sourced into the environment before the following variables when this line is matched.

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.

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

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

     /usr/etc:~:.

     (include file-name)

     package platform os version host [<= requires ...] :
          variable-def [, variable-def ...] ;

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

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

     >> name : "description" <<

     # GNU software is available everywhere:

     $ use CVS

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

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

When Usepackage starts up, it loads an initial configutation 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:

     /usr/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 a 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.

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

     package platform os version host [<= requires ...] :
          variable-def [, variable-def ...] ;

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

*

matches anything.

foo*

matches "foo", "foobar" etc.

{foo,bar}

matches "foo" or "bar".

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 are processed to modify the environment. A variable definition may be one of three forms:

          var-name = "string"
          var-name = path-list
          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. 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.

The requires list specifies the names of other packages which must be sourced into the environment before the following variables when this line is matched.

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.

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

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

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

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

# 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 sources (see SYNOPSIS), 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).

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

When Usepackage starts up, it loads an initial configutation 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:

     /usr/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 a 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.

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

     package platform os version host [<= requires ...] :
          variable-def [, variable-def ...] ;

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

*

matches anything.

foo*

matches "foo", "foobar" etc.

{foo,bar}

matches "foo" or "bar".

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 are processed to modify the environment. A variable definition may be one of three forms:

          var-name = "string"
          var-name = path-list
          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. 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.

The requires list specifies the names of other packages which must be sourced into the environment before the following variables when this line is matched.

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.

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

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

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

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

# 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 sources (see SYNOPSIS), 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).