=begin pod
=head1 NAME
Devel::ExecRunnerGenerator
=head1 SYNOPSIS
=begin code :lang
use Devel::ExecRunnerGenerator;
Devel::ExecRunnerGenerator::generate(
program => "bin/raku",
cwd => ".",
args => [
"./path/to/some/script.raku",
""
],
arg0 => "some-fake-name",
env-add => {
DEBUG => 1,
},
env-remove => [
"LD_PRELOAD",
],
archs => [
"posix",
"windows-x86_64.exe",
],
out-path => ".",
:overwrite
);
=end code
=head1 DESCRIPTION
A tool to generate native wrapper executables (similar to the infamous .bat/.sh wrappers)
=head2 Paths
Paths are always to be written with forward slashes as separators.
=head2 Argument operators
The I and I parameters must have one of the below operators applied to them.
Operators are applied by simply prefixing them to the string.
=defn
Use the arg unchanged
=defn
Insert the passed arguments. Must not be followed by anything.
=defn
Change path (with slashes) to have the platform separators.
=defn
Turn into an absolute path. The base to prefix is the directory the wrapper
executable is located in. Separators are normalized to the platform path separators.
=defn
Turn into an absolute path. The base to prefix is the directory the wrapper
executable is located in. Separators are normalized to be a slash.
=head2 Arguments
=head3 program
Program to call. Either a program name to be searched in PATH, or a path.
The following Is are supported:
=item
=item
=item
=item
Do note that the PATH of the environment I modification by the
I and I have been done. So clearing out the
PATH variable and then trying to call a program via PATH won't work.
=head3 arg0
Use a custom arg0 instead of the program name. This is only supported on
Windows, as it's not possible to set arg0 in an exec call using a POSIX shell.
All platforms except for Windows generate POSIX shell code.
=head3 cwd
The working directory to switch to before calling the program.
If empty or missing, the working directory will be left unchanged.
Either pass an absolute path and use the I operator or pass a path
relative to the wrappers parent directory and use the I operator.
To set the working directory to the wrappers parent directory itself pass ".".
The following Is are supported:
=item
=item
=head3 args
The arguments to pass to the program.
The following Is are supported:
=item
=item
=item
=item
=item
=head3 env-add
Hash of environment variables to add / overwrite in the programs
environment.
=head3 env-remove
List of environment variables to remove from the programs env.
=head1 Standalone usage
A script called `exec-runner-generator` is also provided, which provides access
to the above described functionality without having to write any code. The
program requires a single argument, a path to a configuration file containing
JSON text of the above arguments. An example configuration file is provided at
`doc/example.json`.
=head1 AUTHOR
Patrick Böker
=head1 COPYRIGHT AND LICENSE
Copyright 2020-2022 Patrick Böker
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
=end pod