[-ChnqVv] [program [args ...]]
     penv -L [-D depth] [-d basedir] [-f config] [-o option] [-nqv]
     penv -p [-D depth] [-d basedir] [-f config] [-o option] [-nqv]
     penv -S [-D depth] [-d basedir] [-f config] [-m mode] [-o option] var=val
          ...
     penv -R [-D depth] [-d basedir] [-f config] [-o option] var ...

DESCRIPTION

     penv runs a specified program with an execution environment determined by
     the current working directory.  The execution environment is determined
     by invoking envdir(1) (or whatever environment processing program is
     specified by the envdir_p configuration file directive) on an environment
     directory.  The name of that directory is formed by taking the last com-
     ponents of the name of the current working directory and appending them
     to a base directory name.

     The various configuration options (see CONFIGURATION FILE and ENVIRONMENT
     below) may be set in several ways.  Values are obtained from (in that
     order):

     o command-line options;

     o environment settings;

     o the per-user configuration file;

     o the global configuration file.

     The following options are available:

     -c cmd  Perform a specified action.  A list of all available actions may
             be obtained by the help command.  By default, the exec action is
             performed.

     -C      Clean the environment before invoking the environmental proces-
             sor, thus running the specified program with only the environment
             supplied by the environment directory.

     -D depth
             Specify the number of components to be taken from the end of the
             name of the current working directory.

     -d basedir
             Specify an alternative base for forming the environment directory
             name.

     -f config
             Specify an alternative configuration file name.

     -h      Display a short help message and exit.

     -L      Do not run any program, only print the environment specified by
     -p      Do not run any program, only print the environment directory that
             would be used.  This does not take a program argument.  This is
             equivalent to the path command.

     -q      Quiet operation.  penv is even more quiet when more than one -q
             flag is specified.

     -R      Reset the specified variables, i.e. remove files by those names
             from the environment directory.  This is equivalent to the reset
             command.

     -S      Set the specified variables to the specified values, i.e. create
             files in the environment directory.  This is equivalent to the
             set command.

     -V      Display version information and exit.  When combined with one or
             more -v switches, penv also attempts to display information about
             its build environment.

     -v      Verbose operation.  penv is even more verbose when more than one
             -v flag is specified.

CONFIGURATION FILE

     The penv configuration file is parsed line by line.  Lines consisting of
     whitespace only are ignored.  Lines starting with the ``#'' character are
     considered comments and are also ignored.  All other lines must be in the
     format ``variable = value''.  If a variable has been assigned a value,
     either in a configuration file or by a command-line flag, any further
     assignments to it have no effect.  Thus, a command-line setting overrides
     any configuration file variables.

     penv currently recognizes the following variables:

     basedir       (string) The base for forming the environment directory
                   name.  Equivalent to (and overridden by) the -d command-
                   line flag.

                   Default: /var/db/penv.

     conffile      (string) The name of the configuration file to read.  This
                   variable has no effect when specified in the global config-
                   uration file, although it may be used in a per-user config-
                   uration file to override the default name of the global
                   one.  Equivalent to (and overridden by) the -f command-line
                   flag.

                   Default: /usr/local/etc/penv.conf.

     depth         (unsigned integer) The number of components to be taken
                   from the name of the current working directory.  Equivalent
                   to (and overridden by) the -D command-line flag.

     specified in the penv configuration file.  Variables set in the penv
     environment override the settings in the penv configuration file, but are
     in their turn overridden by command-line options.

     The environment variables honored by penv and the corresponding configu-
     ration file variables are as follows:

     PENV_BASEDIR   basedir

     PENV_CONFFILE  conffile

     PENV_DEPTH     depth

     PENV_ENVDIR_P  envdir_p

FILES

     ~/.penvrc
             The per-user configuration file.

     /usr/local/etc/penv.conf
             The default name for the penv configuration file.

     /var/db/penv
             The default base for forming the environment directory name.

SEE ALSO

     envdir(1)

BUGS

     o   The configuration file should contain more than variable assignments.
         The configuration parsing should probably be rewritten using a lex(1)
         / yacc(1) parser.

     o   There should be a build configuration mechanism and a library of
         helper functions - does this really build on anything besides
         FreeBSD?  asprintf(3) seems to be of somewhat limited availability,
         and at least some older versions of Slackware Linux seem to lack
         dirname(3) and basename(3).

HISTORY

     penv was written by Peter Pentchev in August 2001.  The name ``penv'' is
     derived from ``port environment'' - penv was originally intended to
     facilitate building FreeBSD ports with the same environment build set-
     tings over and over again.

AUTHORS

     Peter Pentchev <roam@ringlet.net>.

                                March 22, 2002