~patrickb/Devel-ExecRunnerGenerator

A tool to generate native wrapper executables (similar to the infamous .bat/.sh wrappers)
On Windows fix PATH search of programs
Structure a bit better, add function to generate to blob

clone

read-only
https://git.sr.ht/~patrickb/Devel-ExecRunnerGenerator
read/write
git@git.sr.ht:~patrickb/Devel-ExecRunnerGenerator

You can also use your local clone with git send-email.

=begin pod

=head1 NAME

Devel::ExecRunnerGenerator

=head1 SYNOPSIS

=begin code :lang<raku>

use Devel::ExecRunnerGenerator;
Devel::ExecRunnerGenerator::generate(
    program => "<abs>bin/raku",
    cwd => "<abs>.",
    args => [
        "<abs>./path/to/some/script.raku",
        "<cmd-args>"
    ],
    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<program> and I<args> parameters must have one of the below operators applied to them.
Operators are applied by simply prefixing them to the string.

=defn <plain>
Use the arg unchanged

=defn <cmd-args>
Insert the passed arguments. Must not be followed by anything.

=defn <plat-sep>
Change path (with slashes) to have the platform separators.

=defn <abs>
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 <abs-slash>
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 I<argument operator>s are supported:

=item <plain>
=item <plat-sep>
=item <abs>
=item <abs-slash>

Do note that the PATH of the environment I<after> modification by the
I<env-add> and I<env-remove> have been done. So clearing out the
PATH variable and then trying to call a program via PATH won't work.

On Windows, when searching for a program in PATH, in addition to looking in the
PATH folders, we also search in the current directory afterwards. That's a sad
behavior of Windows itself that's not trivial to work around.

=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<plain> operator or pass a path
relative to the wrappers parent directory and use the I<abs> operator.
To set the working directory to the wrappers parent directory itself pass "<abs>.".

The following I<argument operator>s are supported:

=item <plain>
=item <abs>

=head3 args

The arguments to pass to the program.
The following I<argument operator>s are supported:

=item <cmd-args>
=item <plain>
=item <plat-sep>
=item <abs>
=item <abs-slash>

=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 <patrick.boeker@posteo.de>

=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