NAME App::plx - Perl Layout Executor SYNOPSIS plx --help # This output plx --init # Initialize layout config plx --perl # Show layout perl binary plx --libs # Show layout $PERL5LIB entries plx --paths # Show layout additional $PATH entries plx --env # Show layout env var changes plx --cpanm -llocal --installdeps . # Run cpanm from outside $PATH plx perl # Run perl within layout plx -E '...' # (ditto) plx script-in-dev # Run dev/ script within layout plx script-in-bin # Run bin/ script within layout plx ./script # Run script within layout plx script/in/cwd # (ditto) plx program # Run program from layout $PATH WHY PLX While perl has many tools for configuring per-project development environments, using them can still be a little on the lumpy side. With Carton, you find yourself running one of perl -Ilocal/lib/perl -Ilib bin/myapp carton exec perl -Ilib bin/myapp With App::perlbrew, perlbrew switch perl-5.28.0@libname perl -Ilib bin/myapp With , plenv exec perl -Ilib bin/myapp and if you have more than one distinct layer of dependencies, while local::lib will happily handle that, integrating it with everything else becomes a pain in the buttocks. As a result of this, your not-so-humble author found himself regularly having a miniature perl executor script at the root of git clones that looked something like: #!/bin/sh eval $(perl -Mlocal::lib=--deactivate-all) export PERL5LIB=$PWD/local/lib/perl5 bin=$1 shift ~/perl5/perlbrew/perls/perl-5.28.0/bin/$bin "$@" and then running: ./pl perl -Ilib bin/myapp However, much like back in 2007 frustration with explaining to other developers how to set up CPAN to install into "~/perl5" and how to set up one's environment variables to then find the modules so installed led to the exercise in rage driven development that first created local::lib, walking newbies through the creation and subsequent use of such a script was not the most enjoyable experience for anybody involved. Thus, the creation of this module to reduce the setup process to: cpanm App::plx cd MyProject plx --init 5.28.0 plx --cpanm -llocal --notest --installdeps . Follwed by being able to immediately (and even more concisely) run: plx myapp which will execute "perl -Ilib bin/myapp" with the correct "perl" and the relevant local::lib already in scope. If this seems of use to you, the "QUICKSTART" is next and the "ACTIONS" section of this document lists the full capabilities of plx. Onwards! QUICKSTART Let's assume we're going to be working on Foo-Bar, so we start with: git clone git@github.com:arthur-nonymous/Foo-Bar.git cd Foo-Bar Assuming the perl we'd get from running just "perl" suffices, then we next run: plx --init If we want a different perl - say, we have a "perl5.30.1" in our path, or a "perl-5.30.1" built in perlbrew, we'd instead run: plx --init 5.30.1 To quickly get our dependencies available, we then run: plx --cpanm -llocal --notest --installdeps . If the project is designed to use Carton and has a "cpanfile.snapshot", instead we would run: plx --cpanm -ldevel --notest Carton plx carton install If the goal is to test this against our current development version of another library, then we'd also want to run: plx --config libspec add 40otherlib.dir ../Other-Lib/lib If we want our ~/perl local::lib available within the plx environment, we can add that as the least significant libspec with: plx --config libspec add 00tilde.ll $HOME/perl5 At which point, we're ready to go, and can run: plx myapp # to run bin/myapp plx t/foo.t # to run one test file plx prove # to run all t/*.t test files plx -E 'say for @INC' # to run a one liner within the layout To learn everything else plx is capable of, read on to the "ACTIONS" section coming next. Have fun! BOOTSTRAP Under normal circumstances, one would run something like: cpanm App::plx However, if you want a self-contained plx script without having a cpan installer available, you can run: mkdir bin wget https://raw.githubusercontent.com/shadowcat-mst/plx/master/bin/plx-packed -O bin/plx to get the current latest packed version. The packed version bundles local::lib and File::Which, and also includes a modified "--cpanm" action that uses an inline "App::cpanminus". ENVIRONMENT "plx" actions that execute external commands all clear any existing environment variables that start with "PERL" to keep an encapsulated setup for commands being run within the layouts - and also set "PERL5OPT" to exclude "site_perl" (but not "vendor_perl") to avoid locally installed modules causing unexpected effects. Having done so, "plx" then loads each env config entry and sets those variables - then prepends the "plx" specific entries to both "PATH" and "PERL5LIB". You can add env config entries with : plx --config env add NAME VALUE The changes that will be made to your environment can be output by calling the "--env" command. Additionally, environment variable overrides may be provided to the "--cmd", "--exec" and "--perl" commands by providing them in "NAME=VALUE" format: # do not do this, it will be deleted PERL_RL=Perl5 plx # do this instead, it will provide the environment variable to the command plx PERL_RL=Perl5 ACTIONS plx --help # Print synopsis plx --version # Print plx version plx --init # Initialize layout config for . plx --bareinit # Initialize bare layout config for . plx --base # Show layout base dir plx --base # Run action with specified base dir plx --perl # Show layout perl binary plx --libs # Show layout $PERL5LIB entries plx --paths # Show layout additional $PATH entries plx --env # Show layout env var changes plx --cpanm -llocal --installdeps . # Run cpanm from outside $PATH plx --config perl # Show perl binary plx --config perl set /path/to/perl # Select exact perl binary plx --config perl set perl-5.xx.y # Select perl via $PATH or perlbrew plx --config libspec # Show lib specifications plx --config libspec add # Add lib specification plx --config libspec del # Delete lib specification plx --config env # Show additional env vars plx --config env add # Add env var plx --config env del # Delete env var plx --exec # exec()s with env vars set plx --perl # Run perl with args plx --cmd # DWIM command: cmd = perl -> --perl cmd = - -> --perl - cmd = some/file -> --perl some/file cmd = ./file -> --perl ./file cmd = name -> exists .plx/cmd/ -> --perl .plx/cmd/ exists dev/ -> --perl dev/ exists bin/ -> --perl bin/ else -> --exec plx --which # Expands --cmd without running plx # Shorthand for plx --cmd plx --commands ? # List available commands plx --multi [ ] [ ... ] # Run multiple actions plx --showmulti [ ... ] [ ... ] # Show multiple action running plx [ ... ] [ ... ] # Shorthand for plx --multi plx --userinit # Init ~/.plx with ~/perl5 ll plx --installself # Installs plx and cpanm into layout plx --installenv # Appends plx --env call to .bashrc plx --userstrap # userinit+installself+installenv --help Prints out the usage information (i.e. the "SYNOPSIS") for plx. --init plx --init # resolve 'perl' in $PATH plx --init perl # (ditto) plx --init 5.28.0 # looks for perl5.28.0 in $PATH # or perl-5.28.0 in perlbrew plx --init /path/to/some/perl # uses the absolute path directly Initializes the layout. If a perl name is passed, attempts to resolve it via $PATH and "perlbrew" and sets the result as the layout perl; if not looks for just "perl". Creates the following libspec config: 25-local.ll local 50-devel.ll devel 75-lib.dir lib --bareinit Identical to "--init" but creates no default configs except for "perl". --base plx --base plx --base Without arguments, shows the selected base dir - "plx" finds this by checking for a ".plx" directory in the current directory, and if not tries the parent directory, recursively. The search stops either when "plx" finds a ".git" directory, to avoid accidentally escaping a project repository, or at the last directory before the root - i.e. "plx" will test "/home" but not "/". With arguments, specifies a base dir to use, and then invokes the rest of the arguments with that base dir selected - so for example one can make a default configuration in $HOME available as "plh" by running: plx --init $HOME alias plh='plx --base $HOME' --libs Prints the directories that will be added to "PERL5LIB", one per line. These will include the "lib/perl5" subdirectory for each "ll" entry in the libspecs, and the directory for each "dir" entry. --paths Prints the directories that will be added to "PATH", one per line. These will include the containing directory of the environment's perl binary if not already in "PATH", followed by the "bin" directories of any "ll" entries in the libspecs. --env Prints the changes that will be made to your environment variables, in a syntax that is (hopefully) correct for your current shell. --cpanm plx --cpanm -Llocal --installdeps . plx --cpanm -ldevel App::Ack Finds the "cpanm" binary in the "PATH" that "plx" was executed *from*, and executes it using the layout's perl binary and environment variables. Requires the user to specify a local::lib to install into via "-l" or "-L" in order to avoid installing modules into unexpected places. Note that this action exists primarily for bootstrapping, and if you want to use a different installer such as App::cpm, you'd install it with: plx --cpanm -ldevel App::cpm and then subsequently run e.g. plx cpm install App::Ack to install modules. --exec plx --exec Sets up the layout's environment variables and "exec"s the command. --perl plx --perl plx --perl