.\" Copyright (c) 2001  Peter Pentchev
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Ringlet: c/misc/penv/penv.in.1,v 1.23 2004/01/06 16:38:10 roam Exp $
.\"
.Dd March 22, 2002
.Dt PENV 1
.Sh NAME
.Nm penv
.Nd run programs with per-directory setting of environment variables
.Sh SYNOPSIS
.Nm
.Op Fl c Cm cmd
.Op Fl D Ar depth
.Op Fl d Ar basedir
.Op Fl f Ar config
.Op Fl m Ar mode
.Op Fl o Ar option
.Op Fl ChnqVv
.Op Ar program Op Ar args ...
.Nm
.Fl L
.Op Fl D Ar depth
.Op Fl d Ar basedir
.Op Fl f Ar config
.Op Fl o Ar option
.Op Fl nqv
.Nm
.Fl p
.Op Fl D Ar depth
.Op Fl d Ar basedir
.Op Fl f Ar config
.Op Fl o Ar option
.Op Fl nqv
.Nm
.Fl S
.Op Fl D Ar depth
.Op Fl d Ar basedir
.Op Fl f Ar config
.Op Fl m Ar mode
.Op Fl o Ar option
.Ar var=val ...
.Nm
.Fl R
.Op Fl D Ar depth
.Op Fl d Ar basedir
.Op Fl f Ar config
.Op Fl o Ar option
.Ar var ...
.Sh DESCRIPTION
.Nm
runs a specified program with an execution environment determined by
the current working directory.
The execution environment is determined by invoking
.Xr envdir 1
(or whatever environment processing program is specified by the
.Va 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.
.Pp
The various configuration options (see CONFIGURATION FILE and ENVIRONMENT
below) may be set in several ways.
Values are obtained from (in that order):
.Bl -bullet -width Ns
.It
command-line options;
.It
environment settings;
.It
the per-user configuration file;
.It
the global configuration file.
.El
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl c Cm cmd
Perform a specified action.
A list of all available actions may be obtained by the
.Cm help
command.
By default, the
.Cm exec
action is performed.
.It Fl C
Clean the environment before invoking the environmental processor,
thus running the specified
.Ar program
with only the environment supplied by the environment directory.
.It Fl D Ar depth
Specify the number of components to be taken from the end of
the name of the current working directory.
.It Fl d Ar basedir
Specify an alternative base for forming the environment directory name.
.It Fl f Ar config
Specify an alternative configuration file name.
.It Fl h
Display a short help message and exit.
.It Fl L
Do not run any
.Ar program ,
only print the environment specified by the environment directory.
This is equivalent to the
.Cm list
command.
.It Fl m Ar mode
Specify the octal mode for access permissions of the files created in
the environment directory.
.It Fl n
Do not execute any programs, only display what would have been run.
.It Fl o Ar option
Process a configuration directive as if read from the top of
the configuration file.
.It Fl p
Do not run any
.Ar program ,
only print the environment directory that would be used.
This does not take a
.Ar program
argument.
This is equivalent to the
.Cm path
command.
.It Fl q
Quiet operation.
.Nm
is even more quiet when more than one
.Fl q
flag is specified.
.It Fl R
Reset the specified variables, i.e. remove files by those names from
the environment directory.
This is equivalent to the
.Cm reset
command.
.It Fl S
Set the specified variables to the specified values, i.e. create files
in the environment directory.
This is equivalent to the
.Cm set
command.
.It Fl V
Display version information and exit.
When combined with one or more
.Fl v
switches,
.Nm
also attempts to display information about its build environment.
.It Fl v
Verbose operation.
.Nm
is even more verbose when more than one
.Fl v
flag is specified.
.El
.Sh CONFIGURATION FILE
The
.Nm
configuration file is parsed line by line.
Lines consisting of whitespace only are ignored.
Lines starting with the
.Dq #
character are considered comments and are also ignored.
All other lines must be in the format
.Dq Ar variable = Ar 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.
.Pp
.Nm
currently recognizes the following variables:
.Bl -tag -width Ar
.It Va basedir
.Pq Vt string
The base for forming the environment directory name.
Equivalent to (and overridden by) the
.Fl d
command-line flag.
.Pp
Default:
.Pa /var/db/penv .
.It Va conffile
.Pq Vt 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
.Fl f
command-line flag.
.Pp
Default:
.Pa /usr/local/etc/penv.conf .
.It Va depth
.Pq Vt unsigned integer
The number of components to be taken from the name of
the current working directory.
Equivalent to (and overridden by) the
.Fl D
command-line flag.
.Pp
Default: 2.
.It Va envdir_p
.Pq Vt string
The path to the environment processor to use.
.Pp
Default:
.Pa /usr/local/bin/envdir
.It Va filemode
.Pq Vt string
The octal mode of the access permissions for the files created in
the environment directory.
Equivalent to (and overridden by) the
.Fl m
command-line flag.
.Pp
Default: 644.
.El
.Sh ENVIRONMENT
Environment variables may be used to override the values of variables
specified in the
.Nm
configuration file.
Variables set in the
.Nm
environment override the settings in the
.Nm
configuration file, but are in their turn overridden by command-line options.
.Pp
The environment variables honored by
.Nm
and the corresponding configuration file variables are as follows:
.Bl -tag -width PENV_ENVDIR_P
.It Va PENV_BASEDIR
.Va basedir
.It Va PENV_CONFFILE
.Va conffile
.It Va PENV_DEPTH
.Va depth
.It Va PENV_ENVDIR_P
.Va envdir_p
.El
.Sh FILES
.Bl -tag -width indent
.It Pa ~/.penvrc
The per-user configuration file.
.It Pa /usr/local/etc/penv.conf
The default name for the
.Nm
configuration file.
.It Pa /var/db/penv
The default base for forming the environment directory name.
.El
.Sh SEE ALSO
.Xr envdir 1
.Sh BUGS
.Bl -bullet
.It
The configuration file should contain more than variable assignments.
The configuration parsing should probably be rewritten using a
.Xr lex 1 /
.Xr yacc 1
parser.
.It
There should be a build configuration mechanism and a library of helper
functions - does this really build on anything besides FreeBSD?
.Xr asprintf 3
seems to be of somewhat limited availability, and at least some older
versions of Slackware Linux seem to lack
.Xr dirname 3
and
.Xr basename 3 .
.El
.Sh HISTORY
.Nm
was written by
.An Peter Pentchev
in August 2001.
The name
.Dq Nm
is derived from
.Dq port environment
-
.Nm
was originally intended to facilitate building
.Fx
ports with the same environment build settings over and over again.
.Sh AUTHORS
.An Peter Pentchev Aq roam@ringlet.net .