view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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/NicholasBHubbard/plx/master/bin/plx-packed -O bin/plx
      chmod +x 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 "--config":

      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 <something>

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

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

      plx --exec <cmd> <args>                # exec()s with env vars set