1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365
|
.TH USE 1 "$Date$" "Usepackage" "User Commands"
.SH NAME
usepackage \-
.I Usepackage
Environment Manager
.SH SYNOPSIS
See
.IR use(1) .
.SH DESCRIPTION
.I Usepackage
is an environment management program. It is based on the principle of
.I packages
\- collections of executables that share a common set of necessary
environment variables, such as PATH, MANPATH or LD_LIBRARY_PATH.
.PP
For each given
.IR package ,
.B use
sources the appropriate environment information into the current shell.
The environment information is specified in packages files, see
.IR PACKAGES .
.PP
The
.B usepackage
executable is the backend program used to generate environment information
suitable for sourcing into a running shell. The
.B use
frontend should be invoked to actually effect changes to the environment,
see
.IR use(1) .
.SS OPTIONS
.TP
.I \-v
Output verbose information to the standard error stream.
.TP
.I \-s
Silence warnings for un-matched packages. This is useful in a shell
.I rc
script when a package is known not to be available on all architectures that
the shell is used on, see
.IR PACKAGES .
.TP
.I \-c
Force
.I csh
style environment output.
.TP
.I \-b
Force bourne shell style environment output.
.TP
.I \-f file
Specify an alternate initial configuration file, see
.IR PACKAGES .
.TP
.I \-l
List available packages and groups, see
.IR ANNOTATIONS
and
.IR GROUPS .
.SH PACKAGES
.I Usepackage
reads package environment information from the configuration file as follows:
.SS LOAD ORDER
When
.I Usepackage
starts up, it loads an initial configuration file, the name of this file may
be given on the command line (see
.IR OPTIONS ),
otherwise it defaults to the builtin name "usepackage.conf" (see
.IR FILES ).
This file is located by searching along a path which defaults to:
.PP
.nf
@sysconfdir@:~:.
.fi
.PP
This path may be overridden with the PACKAGES_PATH environment variable
(see
.IR ENVIRONMENT ).
A packages file may contain inclusion directives which cause the sourcing of
other files at given points. An inclusion directive looks like:
.PP
.nf
(include file-name)
.fi
.PP
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.
.SS SYNTAX
A package file consists of comments, delimited by a leading hash (#),
or package definitions of the form:
.PP
.nf
package [arch [os [version [host [shell]]]]]
[<= requires ...] : setting [, setting ...] ;
.fi
.PP
The
.IR package ,
.IR arch ,
.IR os ,
.IR version ,
.IR host ,
and
.I shell
parts may be simple shell-style patterns of the form:
.TP 15
*
matches anything.
.TP
foo*
matches "foo", "foobar" etc.
.TP
{foo,bar}
matches "foo" or "bar".
.PP
The
.I requires
list specifies the names of other packages which must be sourced into the
environment before the settings for this package are processed.
.PP
A
.I 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
.IR <[
and
.IR ]> ,
for example:
.PP
.nf
<[ /usr/local/bin/test-init ]>
.fi
.PP
When
.I 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
.IR 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:
.PP
.nf
var-name = "string"
var-name = path-list
var-name += path-list
var-name += "string"
var-name =+ path-list
var-name =+ "string"
.fi
.PP
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.
.PP
In addition,
.I 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:
.PP
.nf
var-name ?= path-list
var-name ?+= path-list
var-name ?+= "string"
.fi
.PP
These operate as per the definitions above, but will ignore path components
that don't exist.
.PP
An alias definition has one of the following forms:
.PP
.nf
alias name = name
alias name = path
alias name = "string"
.fi
.PP
These will define a matching shell alias.
.SS GROUPS
In addition to the package definitions in a packages file, there may also be
group definitions. These have the following syntax:
.PP
.nf
group := package [, package ...] ;
.fi
.PP
.I 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.
.SS 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:
.PP
.nf
>> name : "description" <<
.fi
.PP
.I Usepackage
collects these annotations together and displays them when called with the
.I -l
flag, see
.IR 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).
.SS EXAMPLE
The following fragment of a packages file illustrates the main features:
.PP
.nf
# 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 ;
.fi
.PP
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.
.PP
Assuming the appropriate shell setup script has been sourced - see
.IR use(1)
- then the following command will cause the CVS environment (including the
GNU environment) to be sourced:
.PP
.nf
$ use CVS
.fi
.PP
Note that on a DEC Alpha machine, this will generate a warning like:
.PP
.nf
$ use CVS
warning: no match for package `CVS' on this host.
.fi
.PP
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
.IR OPTIONS ).
.SH FILES
.TP 15
.SB @pkgdatadir@/usepackage.conf
The default master packages file.
.TP
.SB @pkgdatadir@/use.csh
Shell setup for csh and derivatives.
.TP
.SB @pkgdatadir@/use.bsh
Shell setup for bourne shell and derivatives.
.TP
.SB @pkgdatadir@/use.ksh
Shell setup for ksh.
.TP
.SB @bindir@/usepackage
The underlying
.I Usepackage
executable.
.SH ENVIRONMENT
Other than the reading and re-definition of environment variables for package
setup,
.B use
also uses the following environment variables for user configuration:
.TP 15
.SB PACKAGES_PATH
Colon-separated path list giving the directories to search for configuration
files. Shell-style tilde (~) user-directory escapes are expanded.
.TP
.SB HOME
If present in the environment, this is used to provide the expansion for
the tilde (~) user-directory.
.TP
.SB SHELL
If present in the environment, the last path component of this is used for
shell matching (see
.IR SYNTAX )
and detecting the style of environment output that should be used (see
.IR OPTIONS ).
.SH COPYRIGHT
.nf
Usepackage Environment Manager
Copyright (C) 1995-2015 Jonathan Hogg <me@jonathanhogg.com>
.fi
.PP
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.
.PP
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.
.PP
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
.SH SEE ALSO
use(1), csh(1), sh(1), ksh(1), env(1), environ(5), getenv(3C), uname(1),
uname(2)
|