Proc-Spawner version 0.13 (EXPERIMENTAL)

Compiles and runs shell one-liners (or portable shell scripts) from Perl without /bin/sh and "without" fork, matching dash/bash: the snippets are parsed by one of the Proc::ShellSubset parsers and run by Proc::ShellSpawn, which starts programs with posix_spawn(3) and runs loops, subshells, $( ) and pipelines of compound commands inside the Perl process. (All the started programs are children of the initial Perl process, as opposed to descendants.)

| Module | What it is | |---|---| | Proc::Spawner | start children (every posix_spawn setting) | | Proc::Spawner::Loop | the event loop, one interface on POSIX and on Windows | | Proc::Spawner::Graph | the executable graph of children, pipes and files | | Proc::ShellSpawn | the shell layer | | Proc::ShellSubset, Proc::ShellSubset::Small, Proc::ShellSubset::Large | parsers of three sizes of the shell language |

The documents: Proc::Spawner::Docs, and their map, doc/README.md.

What is open

The file TODO lists every postponed thing in one place, first the decisions waiting for the author (with where to read and how to act), then the work, then what to watch.

How close to dash and bash (0.13; doc/large-subset/large-subset-state.md)

Snippet by snippet, across environments, with every difference of ours and the ruling that allows it: section 11 of large-subset-environment.md (post-0.12). To redo any of these measurements: make corpus-help (after perl Makefile.PL; Linux, root for the runs; section 0 of doc/test-pools.md).

Of 41,952 shell snippets from six public collections (tldr, NL2Bash, ShellCheck's tests, the bash Cookbook, the pure sh and bash bibles), the large parser accepts 40,410. The rest are mostly bash-only syntax, which the subset rejects on purpose; 44 are forms both shells run alike, the work list (section 4 of large-subset-state.md).

One run of every accepted snippet

Each accepted snippet was run by dash, by bash --posix and by Proc::ShellSpawn (section 7 of large-subset-state.md, the run of post-0.12), each run isolated:

| Snippets | Run | Same | Only the messages differ | dash and bash agree, ours differs | the same, known chance¹ | dash and bash differ | |---|---|---|---|---|---|---| | coreutils involved² | 1,333 | 882 | 310 | 3 | 0 | 135 | | no coreutils | 39,077 | 14,894 | 23,083 | 1 | 3 | 1,085 | | all | 40,410 | 15,776 | 23,393 | 4 | 3 | 1,220 |

¹ Known chance: dash and bash agreed in the run counted here and ours did not, but in repeated runs dash and bash too give other results (races, inode numbers), so ours' difference says nothing. ² Coreutils involved: the snippet calls echo, printf, test, [, kill or pwd, which ours runs as the coreutils programs behave, where dash and bash run builtins of their own: these rows compare coreutils' behaviour with the builtins'.

How far one run's agreement carries

An agreement in one run is a real one only if the snippet could not behave otherwise in another environment (other files, variables, programs' output, /tmp, …). Section 1 of large-subset-environment.md sorts the 40,410 snippets by that, into levels. In N+M, the N snippets were sorted programmatically, from their parse trees, the M by Claude (an AI) reading them.

Beyond the one run

Three checks of what the one run above cannot show:

Our tests

The tests of this distribution (the snippets of the collections above are measurements, not tests). They are designed to pass in every environment we could check. Where an environment cannot do what a test needs, the test is skipped, with the reason printed. Where a known bug of someone else's makes a test fail there, the test is marked TODO: it runs and is reported, but its failure is expected. Each test's outcome per environment and level of the spawn primitive, failures, TODO and skips apart: doc/test-results/ (*-flavors-by-test.txt).

Tests, among them: t/spawner.t (Proc::Spawner and the graph), t/graph.t (hand-written graphs), t/parsers.t (1,117 snippets through the parsers), and t/dash.t (every snippet of the batteries run by dash and by the shell layer; skipped without dash; t/dash-known.txt lists the known differences). Their fixtures are in t/: t/batteries/ (the batteries: files of hand-written shell snippets, one a line, 701 in 15 files, grouped by topic: fds, signals and the environment, echo, the large subset's features, …), t/parser/, t/sgraph/, t/try.pl (runs one snippet: perl t/try.pl 'SNIPPET').

Installation

To install this module type the following:

perl Makefile.PL
make
make test
make install

Dependencies

Only modules that come with Perl. Building needs a C compiler. Makefile.PL finds whether the libc has posix_spawn, and which of its extensions (chdir, fchdir, closefrom, tcsetpgrp, pidfd_spawn, cgroup), by compiling a call to each. What the libc lacks is done in Perl's process around the call where that can be undone (chdir, the fds, the signal mask, ...); the rest fails with ENOTSUP, or is dropped, as %Proc::Spawner::UNSUPPORTED says. Without posix_spawn the primitive is fork and exec; without fork either, Perl's own spawn through Run 0.07 (system1); on Windows, win_spawn.h. Resource limits, ignored signals and the nice value, which posix_spawn has no option for, are set around the call too.

Copyright (C) 2026 by Ilya Zakharevich

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.22.2 or, at your option, any later version of Perl 5 you may have available.