NAME
Developer::Dashboard::PerlEnv - normalize safe Perl library ordering for dashboard processes
SYNOPSIS
use Developer::Dashboard::PerlEnv;
my $perl5lib = Developer::Dashboard::PerlEnv->perl5lib_env(
dashboard_lib => $dashboard_lib,
extra => \@runtime_local_libs,
);
BEGIN {
Developer::Dashboard::PerlEnv->bootstrap_perl5lib(
dashboard_lib => $dashboard_lib,
);
}DESCRIPTION
This module centralizes the PERL5LIB ordering used by the public dashboard switchboard, staged private helpers, and dashboard-managed child process environments. It keeps dashboard libraries and the active Perl core directories ahead of inherited user-local paths so stale dual-life XS modules such as Encode do not shadow the interpreter's matching core copy.
PURPOSE
Use this module when changing how dashboard bootstraps Perl library search paths or when debugging environment-specific startup failures caused by local Perl module shadowing.
WHY IT EXISTS
Dashboard has to keep its own Perl runtime consistent across the public switchboard, staged private helpers, collectors, saved Ajax handlers, and skill subprocesses. A plain inherited PERL5LIB or PATH can be enough to break that guarantee on hosts with older local-lib trees or multiple Perl installs. This module exists so every dashboard-owned child process uses one shared normalization path instead of each caller rebuilding the environment in slightly different ways.
WHEN TO USE
Use this module when bootstrapping dashboard itself, when staging or running private helper commands, and whenever dashboard-managed subprocesses need a Perl-aware child environment. It is also the right place to debug XS handshake mismatches, interpreter drift, or any bug where a child process finds the wrong Perl binary or the wrong core module tree.
HOW TO USE
For early process bootstrap, call bootstrap_perl5lib() in a BEGIN block before heavier dashboard modules load. For child process spawning, call dashboard_child_env() and layer the returned PATH and PERL5LIB entries into the child environment. For inspection or tests, call perl5lib_list() or path_with_current_perl() directly and assert the ordered results.
METHODS
path_separator
Returns the platform-specific separator used by PERL5LIB.
core_inc_paths
Returns the ordered core, site, and vendor Perl library directories for the active interpreter.
perl5lib_list
Builds the ordered list of PERL5LIB paths using the dashboard lib path, runtime-specific extra paths, the active interpreter's core directories, and the inherited environment.
perl5lib_env
Returns the final joined PERL5LIB string built from perl5lib_list.
path_with_current_perl
Returns the final joined PATH string that keeps the current Perl interpreter directory ahead of inherited entries.
dashboard_child_env
Returns the combined child-process PATH and PERL5LIB overrides used by dashboard-managed subprocesses.
bootstrap_perl5lib
Writes the normalized PERL5LIB value back into the target environment hash, defaulting to %ENV.
EXAMPLES
my @paths = Developer::Dashboard::PerlEnv->perl5lib_list(
dashboard_lib => '/home/mv/perl5/lib',
extra => ['/tmp/project/.developer-dashboard/local/lib/perl5'],
);
my $value = Developer::Dashboard::PerlEnv->bootstrap_perl5lib(
dashboard_lib => "$Bin/../lib",
);
my $env = Developer::Dashboard::PerlEnv->dashboard_child_env(
dashboard_lib => "$Bin/../lib",
extra => ['/tmp/project/.developer-dashboard/local/lib/perl5'],
);WHAT USES IT
The public bin/dashboard entrypoint uses it during early bootstrap, the staged private helper runtime uses it before loading command implementations, and runtime child-process builders use it to prepare safe Perl environments for saved Ajax handlers, skills, and collector-related subprocesses.