"Modular DocBook HTML Stylesheet Version 1.73 ">
"#0000FF" vlink="#840084" alink="#0000FF">
There are three sides to using penv - configuration files, defining environment settings for a particular directory and invoking programs with those settings. For a description of the penv command-line options and the commands that may be specified with the -c option, please see the penv manual page. You may also want to look at some examples of using penv.
penv stores the environment settings for each directory into files located in the corresponding ``environment directory''. Each environment variable is stored in its own file, according to the directory layout format used by the envdir program. By default, the environment directories reside under a common ``base directory'' - /var/db/penv/ by default. The name of the environment directory is formed by taking the last components of the name of the current working directory and appending those to the base directory name. By default, the last two components are used. Thus, if the current working directory is /usr/ports/databases/mysql323-server/, then the directory where penv will store its settings will be /var/db/penv/databases/mysql323-server/. Both the base directory name and the number of path components used to construct the environment directory name may be overridden in the penv.conf file - see the global configuration section.
For its operation, penv needs some information that may be defined on the command line, in environment variables or in configuration files. There are two types of files: a global configuration file named penv.conf, residing in /usr/local/etc/ by default, and a per-user one, named .penvrc, in each user's home directory. The order in which configuration options are looked for is command line, environment settings, per-user configuration file, global configuration file. A sample configuration file is included with the penv distribution.
The syntax of the penv configuration files is simple - each line is either a blank line, a comment starting with the # character, or a variable definition. A variable definition line is of the form varname=value and the variables that may be defined are:
So, you want to define some environment variables that will be used every time some command is run in a certain directory. Nothing easier than that! :)
And that is all - your environment is all set up!
To run a program with an environment modified by the settings you have defined for a directory, simply run penv and tell it which program to execute:
% penv program args..
Yes, it really is as simple as that :)
Keep in mind, though, that penv runs only once, in your current directory, and only uses the settings for this directory. If you want to use it ``recursively'', e.g. for building a FreeBSD port's dependencies with specific settings for each dependency, you may want to have a look at the compatibility section for some patches to FreeBSD's make(1) command allowing it to invoke penv for each directory it recurses into.
The main reason penv was developed was the author's annoyance with having to specify the same variables over and over again when building FreeBSD ports. How does penv help with that? Well, judge for yourself. First, run the following sequence of commands just once:
% cd /usr/ports/mail/vpopmail % penv -c mkdir % penv -S WITH_MYSQL=yes WITH_MYSQL_USER=vpopmail WITH_MYSQL_PASS=unguessable WITH_MYSQL_DB=mail % penv -S WITH_HARDQUOTA=n WITH_QMAIL_EXT=yes
Of course, the two penv -S invocations could have been done in a single command, but those are broken down for clarity.
Now, every time you want to rebuild the mail/vpopmail port, instead of typing all those variables on the make(1) command line, never really certain whether you have not forgotten a couple of them, all you need to do is:
# cd /usr/ports/mail/vpopmail # penv make clean all install
..and penv will take care of passing all the necessary variables to the port build!
FreeBSD ports are not the only area when the same environment settings may have to be specified repeatedly. I, personally, like to build my FreeBSD base system with debug information, yet install it with stripped binaries to save space. So, instead of doing the following:
% cd /usr/src % make -DNOCLEAN DEBUG_FLAGS=-g3 buildworld buildkernel % sudo make TMPDIR=/home/roam/tmp STRIP=-s installkernel installworld
..I have set things up as:
% cd /usr/src % penv -c mkdir % penv -S NOCLEAN=yes DEBUG_FLAGS=-g3 TMPDIR=/home/roam/tmp STRIP=-s
..which allows me to later do simply:
% cd /usr/src % penv make buildworld buildkernel && sudo penv make installkernel installworld
..and be done with it.
Another FreeBSD-related example :) The documentation for many Ringlet software projects uses the build infrastructure of The FreeBSD Documentation Project. Some projects require tweaking some environment variables to get things right. Again, specifying those variables on the make(1) command line at every invocation may be tiresome; specifying them in the global make.conf configuration file would not do, because they would conflict with the settings for other projects. And again, penv comes to the rescue! :)
% cd /home/roam/doc/fbsd-bg % penv -c mkdir % penv -S DOCDIR=/home/roam/doc/fbsd-bg DOC_PREFIX_NAME=fbsd-bg
After doing this, building the documentation with the correct settings is a breeze :)
This, and other documents, can be downloaded from http://devel.ringlet.net/.
For questions about this documentation, e-mail <firstname.lastname@example.org>.