PENV(1)

NAME
penv - run programs with per-directory setting of environment variables

SYNOPSIS
penv [-c cmd] [-D depth] [-d basedir] [-f config] [-o option] [-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] [-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 components 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):

•   command-line options;

•   environment settings;

•   the per-user configuration file;

•   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 processor, 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 the environment directory. This is equivalent to the list command.

-n  Do not execute any programs, only display what would have been run.

-o option
    Process a configuration directive as if read from the top of the configuration file.

-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 configuration file, although it may be used in a per-user configuration 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.

    Default: 2.

envdir_p
    (string) The path to the environment processor to use.

    Default: /usr/local/bin/envdir

ENVIRONMENT
Environment variables may be used to override the values of variables 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 configuration 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

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

•   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 settings over and over again.

AUTHORS
Peter Pentchev <roam@ringlet.net>.