view release on metacpan or  search on metacpan

bin/plx  view on Meta::CPAN

=head1 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 C<perl> suffices, then we
next run:

  plx --init

If we want a different perl - say, we have a C<perl5.30.1> in our path, or
a C<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 L<Carton> and has a C<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 L<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 L</ACTIONS> section
coming next.

Have fun!

=head1 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/NicholasBHubbard/plx/master/bin/plx-packed -O bin/plx
  chmod +x bin/plx

to get the current latest packed version.

The packed version bundles L<local::lib> and L<File::Which>, and also includes
a modified C<--cpanm> action that uses an inline C<App::cpanminus>.

=head1 ENVIRONMENT

C<plx> actions that execute external commands all clear any existing
environment variables that start with C<PERL> to keep an encapsulated setup
for commands being run within the layouts - and also set C<PERL5OPT> to
exclude C<site_perl> (but not C<vendor_perl>) to avoid locally installed
modules causing unexpected effects.

Having done so, C<plx> then loads each env config entry and sets those
variables - then prepends the C<plx> specific entries to both C<PATH> and
C<PERL5LIB>. You can add env config entries with L</--config>:

  plx --config env add NAME VALUE

The changes that will be made to your environment can be output by calling
the L</--env> command.

Additionally, environment variable overrides may be provided to the
L</--cmd>, L</--exec> and L</--perl> commands by providing them in
 C<NAME=VALUE> format:

  # do not do this, it will be deleted
  PERL_RL=Perl5 plx <something>

  # do this instead, it will provide the environment variable to the command
  plx PERL_RL=Perl5 <something>

=head1 ACTIONS

  plx --help                             # Print synopsis
  plx --version                          # Print plx version

  plx --init <perl>                      # Initialize layout config for .
  plx --bareinit <perl>                  # Initialize bare layout config for .
  plx --base                             # Show layout base dir 
  plx --base <base> <action> <args>      # 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 <name> <path> # Add lib specification
  plx --config libspec del <name> <path> # Delete lib specification
  
  plx --config env                       # Show additional env vars
  plx --config env add <name> <path>     # Add env var
  plx --config env del <name> <path>     # Delete env var