view release on metacpan or  search on metacpan

lib/Perl/Dist/APPerl.pm  view on Meta::CPAN

labeled PROJECT. The exact configuration of a STABLE config may change
from release to release of Perl::Dist::APPerl, but only non-breaking
changes should occur. ROLLING configurations are always the latest
STABLE configurations, but breaking changes may occur from release to
release of Perl::Dist::APPerl.

=item *

C<apperlm checkout> sets the current APPerl config, including cleaning
or reestablishing the build dirs. The current config name is written to
C<.apperl/user-project.json> .

=item *

C<apperlm new-config> creates a new config and adds to to the project
config. -n specifies the name of the new config and must be provided.
-b specifies the base of the new config. Alternatively, you can modify
C<apperl-project.json> directly.

=item *

C<apperlm configure> builds cosmopolitan for the current APPerl config
and runs Perl's C<Configure>

=item *

C<apperlm build> C<make>s perl and builds apperl. The output binary by
default is copied to C<perl.com> in the current directory, set dest in
C<apperl-project.json> to customize output binary path and name. A
C<zip> binary is required to build, see README.md for details. The
C<zip> binary path may be explictly set by passing in
--zippath <zip_binary_path> .

=item *

C<apperlm install-build-deps> installs APPerl build git dependencies.
This is now unnecessary unless you are doing vista builds or developing
APPerl itself. Note, vista builds are deprecated, see Changes.
Initialization of the repos can be skipped by passing the path to them
locally. The cosmopolitan repo initialization can be skipped with
-c <path_to_repo> . The perl5 repo initialization can be skipped with
-p <path_to_repo>. This install is done user specific, installs to
$XDG_CONFIG_HOME/apperl .

=back

=head1 USAGE

APPerl doesn't need to be installed, the output C<perl.com> binary can
be copied between computers and ran without installation. However, in
certain cases such as magic (modifying $0, etc.) The binary must be
assimilated for it to work properly. Note, you likely want to copy
before this operation as it modifies the binary in-place to be bound to
the current environment.
  cp perl.com perl
  ./perl --assimilate

For the most part, APPerl works like normal perl, however it has a
couple additional features.

=head2 EMBEDDED SCRIPTS

The APPerl binary is also a ZIP file. Paths starting with C</zip/>
refer to files compressed in the binary itself. At runtime the zip
filesystem is readonly, but additional modules and scripts can be added
just by adding them to the zip file. For example, perldoc and the other
standard scripts are shipped inside of C</zip/bin>

  ./perl.com /zip/bin/perldoc perlcosmo

For convenience, APPerl has some other ways of invoking embedded
scripts:

=over 4

=item *

C<APPERL_SCRIPTNAME> - When the environment variable C<APPERL_SCRIPTNAME>
is set, APPerl attempts to load the basename of C<APPERL_SCRIPTNAME>
without file extension from C</zip/bin> or opens the perl interpreter
like normal if it is C<perl>.

  APPERL_SCRIPTNAME=perldoc ./perl.com perlcosmo

=item *

C<argv[0]> - If C<APPERL_SCRIPTNAME> is not set, APPerl attempts to
load the basename of C<argv[0]> without file extension from C</zip/bin>
or opens the perl interpreter like normal if it is C<perl>. This
enables making single binary perl applications, with a symlink, move,
or copy!

  ln -s perl.com perldoc.com
  ./perldoc.com perlcosmo

=item *

C<APPERL_DEFAULT_SCRIPT> - If C<argv[0]> doesn't yield a valid target
either, if the C<APPERL_DEFAULT_SCRIPT> field inside of the binary
is set, APPerl will attempt to load that. This way is meant for APPerl
application authors to protect against accidental rename messing up
C<argv[0]> script execution. L</BUILDING AN APPLICATION FROM EXISTING APPERL>
shows how to set it with C<"default_script">, but you could also
set/change it, by searching for C<APPERL_DEFAULT_SCRIPT> in a hex
editor and modifying it.

=back

If a valid target is not found via the script execution methods, the
perl interpreter is invoked like normal.

=head1 CREATING APPLICATIONS WITH APPERL

=head2 RATONALE

APPerl wasn't developed to be the 'hack of the day', but provide real
world utility by easing using Perl in user environments.

Unfortunately, scripting languages are often a second class citizen on
user environments due to them not being installed by default or only
broken/old/incomplete versions installed, and sometimes not being the