Apache...Config(3pm)

💖 Apache::TestConfig — the girlies' guide to test config setup 💖

okay so bestie, you're looking at Apache...Config(3pm) from the User Contributed Perl Documentation set. She's a Perl module, she's 3pm-coded, and she is literally the module that builds your Apache::Test configuration files. no cap. let's go 🫶

---

✨ NAME ✨

Apache::TestConfig — the Test Configuration setup module. that's her. that's the whole name. iconic. 💅

---

🌸 SYNOPSIS 🌸

here's the vibe, fr fr:

use Apache::TestConfig;

my $cfg = Apache::TestConfig->new(%args)
my $fh = $cfg->genfile($file);
$cfg->writefile($file, $content);
$cfg->gendir($dir);
...

that ... at the end? that's the "and so much more, iykyk" energy. 🔥

---

🦋 DESCRIPTION 🦋

Apache::TestConfig is the module you call when you need to create the configuration files for Apache::Test. she does the file-wrangling so you don't have to. main character energy honestly. ✨

---

👑 FUNCTIONS 👑

🎀 genwarning()

my $warn = $cfg->genwarning($filename)

genwarning() hands you back a warning string, formatted as a comment, and that comment is basically saying "bestie, this file was autogenerated, do NOT modify it, i'm begging." 💀

and after that warning? it appends a perl trace of calls to this this function. (yes, the original says "this this" — i'm not touching it, it's part of the lore 🫶) and that trace is genuinely useful, because it tells you exactly what code created the file. detective work. slay.

my $warn = $cfg->genwarning($filename, $from_filename)

if $from_filename is specified, it gets used inside the warning to tell you which file it was generated from. receipts! 🧾

okay and here's the cute part: genwarning() automatically recognizes the comment type based on the file extension. if the extension isn't one she recognizes, the default # style gets used. she's flexible like that.

currently supported styles:

• <!-- -->
• /* ... */
• #

three icons. no notes. 💅

🎀 genfile()

my $fh = $cfg->genfile($file);

genfile() creates a brand-new file $file for writing, and returns a file handle. so you can go write in it. periodt.

if the parent directories of $file don't exist? they will be automagically created. she's not gonna make you do that by hand, that would be so rude. ✨

and listen — the file $file plus any created parent directories (if found empty) will be automatically removed on cleanup. so she cleans up after herself. a queen who tidies. 🌸

a comment with a warning and a calls trace gets added to the top of this file — see genwarning() for more info about that comment.

my $fh = $cfg->genfile($file, $from_file);

if $from_filename is specified, it'll be used in the warning to tell which file it was generated from. (again: the synopsis calls it $from_file, the prose calls it $from_filename. we keep both, exactly as written. consistency is not the vibe here and that's okay. 😭)

my $fh = $cfg->genfile($file, $from_file, $nowarning);

if $nowarning is true, the warning won't be added. no comment, no trace, just pure vibes.

⚠️ but heads up bestie: if you use this optional argument and there's no $from_file, you must pass undef, like this:

my $fh = $cfg->genfile($file, undef, $nowarning);

don't skip the undef. she will know. 👀

🎀 writefile()

$cfg->writefile($file, $content, [$nowarning]);

writefile() creates a new file $file with the content of $content. boom. done. 💅

a comment with a warning and a calls trace gets added to the top of this file — unless $nowarnings is passed and set to a true value. (original says $nowarnings, with the s. keeping it. character for character, bestie. 🫶) see genwarning() for more info about that comment.

if the parent directories of $file don't exist, they'll be automagically created. same energy as always. ✨

and yes: the file $file and any created parent directories (if found empty) will be automatically removed on cleanup. she's consistent. she's reliable. she's that girl. 🌈

🎀 write_perlscript()

$cfg->write_perlscript($filename, @lines);

similar to writefile(), BUT — and this is the glow-up — she creates an executable Perl script, with a correctly set shebang line. executable. chmod-worthy. absolute icon. 👑

🎀 gendir()

$cfg->gendir($dir);

gendir() creates a new directory $dir. that's it, that's the function, and she serves. ✨

if the parent directories of $dir don't exist, they will be automagically created. obviously. 💅

the directory $dir and any created parent directories will be automatically removed on cleanup if found empty. cleanliness is next to goddess-ness. 🧚

---

🌈 Environment Variables 🌈

these env vars affect the configuration and the run-time of the Apache::Test framework. so they're the backstage pass, the ones pulling strings. y'all know i love a good env var. 💜

💖 APACHE_TEST_COLOR

to help you visually control the configuration process and the run-time phase, Apache::Test uses coloured fonts when the environment variable APACHE_TEST_COLOR is set to a true value.

so yes, set it, get colour. it's giving rainbow terminal. 🌈✨

💖 APACHE_TEST_LIVE_DEV

when you're using Apache::Test during the project development phase, it's often convenient to have the project/lib (live) directory appearing first in @INC, so that any changes to the Perl modules living in it immediately affect the server — without needing to rerun make to update blib/lib. (no rebuild? no waiting? obsessed. 😭💖)

when the environment variable APACHE_TEST_LIVE_DEV is set to a true value during the configuration phase (t/TEST -config), Apache::Test will automatically unshift the project/lib directory into @INC, via the autogenerated t/conf/modperl_inc.pl file. automatic. magical. no cap. ✨

---

🦄 Special Placeholders 🦄

when you're generating configuration files from the *.in templates, special placeholder variables get substituted in. to embed a placeholder, you use the @foo@ syntax. 🎀

for example, in extra.conf.in you can write:

Include @ServerRoot@/conf/myconfig.conf

and when extra.conf is generated, @ServerRoot@ will get replaced with the location of the server root. substitution! transformative! slay! 💅

placeholders are case-insensitive. so don't stress about the caps, she's chill. 🌸

available placeholders:

⭐ Configuration Options

all the configuration variables that can be passed to t/TEST — like MaxClients, DocumentRoot, ServerRoot, etc. the whole squad. 💖

to see the complete list, run:

% t/TEST --help

and you'll find them in the "configuration options" sections. go look, bestie, the full menu is right there. 📜✨

⭐ NextAvailablePort

every single 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. (hardcoding? not on her watch. 🙈)

later, when you run:

% t/TEST -port=select

you can run several concurrent test suites on the same machine w/o having port collisions. no fights, no clashes, just peace and ports. 🕊️💜

---

💜 AUTHOR 💜

sooo... this section exists, okay? i'm just saying. it's here. there's a heading. there's nothing under it. the author is anonymous. mysterious. a ghost. the moment is giving unfilled template and honestly? respect. 😭💀

---

🔥 SEE ALSO 🔥

• perl(1)
• Apache::Test(3)

go read those too, bestie, they're the supporting cast. 🫶

---

and that's the whole page, periodt. 💅 sheet generated as perl v5.42.3, dated 2026-08-20, and it's the Apache...Config(3pm) page from the User Contributed Perl Documentation set. mwah. 🎀✨💖