.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Apache::TestConfig 3"
.TH Apache::TestConfig 3 "2007-12-31" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Apache::TestConfigData \- Configuration file for Apache::Test
.SH "NAME"
Apache::TestConfig \-\- Test Configuration setup module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Apache::TestConfig;
\&
\&  my $cfg = Apache::TestConfig\->new(%args)
\&  my $fh = $cfg\->genfile($file);
\&  $cfg\->writefile($file, $content);
\&  $cfg\->gendir($dir);
\&  ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Apache::TestConfig\*(C'\fR is used in creating the \f(CW\*(C`Apache::Test\*(C'\fR
configuration files.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fIgenwarning()\fR" 4
.IX Item "genwarning()"
.Vb 1
\&  my $warn = $cfg\->genwarning($filename)
.Ve
.Sp
\&\fIgenwarning()\fR returns a warning string as a comment, saying that the
file was autogenerated and that it's not a good idea to modify this
file. After the warning a perl trace of calls to this this function is
appended. This trace is useful for finding what code has created the
file.
.Sp
.Vb 1
\&  my $warn = $cfg\->genwarning($filename, $from_filename)
.Ve
.Sp
If \f(CW$from_filename\fR is specified it'll be used in the warning to tell
which file it was generated from.
.Sp
\&\fIgenwarning()\fR automatically recognizes the comment type based on the
file extension. If the extension is not recognized, the default \f(CW\*(C`#\*(C'\fR
style is used.
.Sp
Currently it support \f(CW\*(C`<!\-\- \-\->\*(C'\fR, \f(CW\*(C`/* ... */\*(C'\fR and \f(CW\*(C`#\*(C'\fR
styles.
.IP "\fIgenfile()\fR" 4
.IX Item "genfile()"
.Vb 1
\&  my $fh = $cfg\->genfile($file);
.Ve
.Sp
\&\fIgenfile()\fR creates a new file \f(CW$file\fR for writing and returns a file
handle.
.Sp
If parent directories of \f(CW$file\fR don't exist they will be
automagically created.
.Sp
The file \f(CW$file\fR and any created parent directories (if found empty)
will be automatically removed on cleanup.
.Sp
A comment with a warning and calls trace is added to the top of this
file. See \fIgenwarning()\fR for more info about this comment.
.Sp
.Vb 1
\&  my $fh = $cfg\->genfile($file, $from_file);
.Ve
.Sp
If \f(CW$from_filename\fR is specified it'll be used in the warning to tell
which file it was generated from.
.Sp
.Vb 1
\&  my $fh = $cfg\->genfile($file, $from_file, $nowarning);
.Ve
.Sp
If \f(CW$nowarning\fR is true, the warning won't be added. If using this
optional argument and there is no \f(CW$from_file\fR you must pass undef as
in:
.Sp
.Vb 1
\&  my $fh = $cfg\->genfile($file, undef, $nowarning);
.Ve
.IP "\fIwritefile()\fR" 4
.IX Item "writefile()"
.Vb 1
\&  $cfg\->writefile($file, $content, [$nowarning]);
.Ve
.Sp
\&\fIwritefile()\fR creates a new file \f(CW$file\fR with the content of
\&\f(CW$content\fR.
.Sp
A comment with a warning and calls trace is added to the top of this
file unless \f(CW$nowarnings\fR is passed and set to a true value. See
\&\fIgenwarning()\fR for more info about this comment.
.Sp
If parent directories of \f(CW$file\fR don't exist they will be
automagically created.
.Sp
The file \f(CW$file\fR and any created parent directories (if found empty)
will be automatically removed on cleanup.
.IP "\fIwrite_perlscript()\fR" 4
.IX Item "write_perlscript()"
.Vb 1
\&  $cfg\->write_perlscript($filename, @lines);
.Ve
.Sp
Similar to \fIwritefile()\fR but creates an executable Perl script with
correctly set shebang line.
.IP "\fIgendir()\fR" 4
.IX Item "gendir()"
.Vb 1
\&  $cfg\->gendir($dir);
.Ve
.Sp
\&\fIgendir()\fR creates a new directory \f(CW$dir\fR.
.Sp
If parent directories of \f(CW$dir\fR don't exist they will be
automagically created.
.Sp
The directory \f(CW$dir\fR and any created parent directories will be
automatically removed on cleanup if found empty.
.SH "Environment Variables"
.IX Header "Environment Variables"
The following environment variables affect the configuration and the
run-time of the \f(CW\*(C`Apache::Test\*(C'\fR framework:
.SS "\s-1APACHE_TEST_COLOR\s0"
.IX Subsection "APACHE_TEST_COLOR"
To aid visual control over the configuration process and the run-time
phase, \f(CW\*(C`Apache::Test\*(C'\fR uses coloured fonts when the environment
variable \f(CW\*(C`APACHE_TEST_COLOR\*(C'\fR is set to a true value.
.SS "\s-1APACHE_TEST_LIVE_DEV\s0"
.IX Subsection "APACHE_TEST_LIVE_DEV"
When using \f(CW\*(C`Apache::Test\*(C'\fR during the project development phase, it's
often convenient to have the \fIproject/lib\fR (live) directory appearing
first in \f(CW@INC\fR so any changes to the Perl modules, residing in it,
immediately affect the server, without a need to rerun \f(CW\*(C`make\*(C'\fR to
update \fIblib/lib\fR. When the environment variable
\&\f(CW\*(C`APACHE_TEST_LIVE_DEV\*(C'\fR is set to a true value during the
configuration phase (\f(CW\*(C`t/TEST \-config\*(C'\fR, \f(CW\*(C`Apache::Test\*(C'\fR will
automatically unshift the \fIproject/lib\fR directory into \f(CW@INC\fR, via
the autogenerated \fIt/conf/modperl_inc.pl\fR file.
.SS "\s-1APACHE_TEST_INTERACTIVE_PROMPT_OK\s0"
.IX Subsection "APACHE_TEST_INTERACTIVE_PROMPT_OK"
Normally interactive prompts aren't run when \s-1STDIN\s0 is not attached to
a tty. But sometimes there is a program that can answer the prompts
(e.g. when testing A\-T itself). If this variable is true the
interactive config won't be skipped (if needed).
.SH "Special Placeholders"
.IX Header "Special Placeholders"
When generating configuration files from the \fI*.in\fR templates,
special placeholder variables get substituted. To embed a placeholder
use the \f(CW\*(C`@foo@\*(C'\fR syntax. For example in \fIextra.conf.in\fR you can
write:
.PP
.Vb 1
\&  Include @ServerRoot@/conf/myconfig.conf
.Ve
.PP
When \fIextra.conf\fR is generated, \f(CW\*(C`@ServerRoot@\*(C'\fR will get replaced
with the location of the server root.
.PP
Placeholders are case-insensitive.
.PP
Available placeholders:
.SS "Configuration Options"
.IX Subsection "Configuration Options"
All configuration variables that can be passed to \f(CW\*(C`t/TEST\*(C'\fR, such as
\&\f(CW\*(C`MaxClients\*(C'\fR, \f(CW\*(C`DocumentRoot\*(C'\fR, \f(CW\*(C`ServerRoot\*(C'\fR, etc. To see the
complete list run:
.PP
.Vb 1
\&  % t/TEST \-\-help
.Ve
.PP
and you will find them in the \f(CW\*(C`configuration options\*(C'\fR sections.
.SS "NextAvailablePort"
.IX Subsection "NextAvailablePort"
Every time this placeholder is encountered it'll be replaced with the
next available port. This is very useful if you need to allocate a
special port, but not hardcode it. Later when running:
.PP
.Vb 1
\&  % t/TEST \-port=select
.Ve
.PP
it's possible to run several concurrent test suites on the same
machine, w/o having port collisions.
.SH "AUTHOR"
.IX Header "AUTHOR"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1), \fIApache::Test\fR\|(3)