aboutsummaryrefslogtreecommitdiff
path: root/node_modules/spawn-wrap/README.md
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2019-03-27 21:01:33 +0100
committerFlorian Dold <florian.dold@gmail.com>2019-03-27 21:01:33 +0100
commitcc97a4dd2a967e1c2273bd5f4c5f49a5bf2e2585 (patch)
tree92c5d88706a6ffc654d1b133618d357890e7096b /node_modules/spawn-wrap/README.md
parent3771b4d6b67b34c130f3a9a1a15f42deefdb2eda (diff)
downloadwallet-core-cc97a4dd2a967e1c2273bd5f4c5f49a5bf2e2585.tar.xz
remove node_modules
Diffstat (limited to 'node_modules/spawn-wrap/README.md')
-rw-r--r--node_modules/spawn-wrap/README.md111
1 files changed, 0 insertions, 111 deletions
diff --git a/node_modules/spawn-wrap/README.md b/node_modules/spawn-wrap/README.md
deleted file mode 100644
index 428df37e5..000000000
--- a/node_modules/spawn-wrap/README.md
+++ /dev/null
@@ -1,111 +0,0 @@
-# spawn-wrap
-
-Wrap all spawned Node.js child processes by adding environs and
-arguments ahead of the main JavaScript file argument.
-
-Any child processes launched by that child process will also be
-wrapped in a similar fashion.
-
-This is a bit of a brutal hack, designed primarily to support code
-coverage reporting in cases where tests or the system under test are
-loaded via child processes rather than via `require()`.
-
-It can also be handy if you want to run your own mock executable
-instead of some other thing when child procs call into it.
-
-[![Build Status](https://travis-ci.org/tapjs/spawn-wrap.svg)](https://travis-ci.org/tapjs/spawn-wrap) [![Build status](https://ci.appveyor.com/api/projects/status/oea7gdvqa0qeijrm?svg=true)](https://ci.appveyor.com/project/isaacs/spawn-wrap)
-
-## USAGE
-
-```javascript
-var wrap = require('spawn-wrap')
-
-// wrap(wrapperArgs, environs)
-var unwrap = wrap(['/path/to/my/main.js', 'foo=bar'], { FOO: 1 })
-
-// later to undo the wrapping, you can call the returned function
-unwrap()
-```
-
-In this example, the `/path/to/my/main.js` file will be used as the
-"main" module, whenever any Node or io.js child process is started,
-whether via a call to `spawn` or `exec`, whether node is invoked
-directly as the command or as the result of a shebang `#!` lookup.
-
-In `/path/to/my/main.js`, you can do whatever instrumentation or
-environment manipulation you like. When you're done, and ready to run
-the "real" main.js file (ie, the one that was spawned in the first
-place), you can do this:
-
-```javascript
-// /path/to/my/main.js
-// process.argv[1] === 'foo=bar'
-// and process.env.FOO === '1'
-
-// my wrapping manipulations
-setupInstrumentationOrCoverageOrWhatever()
-process.on('exit', function (code) {
- storeCoverageInfoSynchronously()
-})
-
-// now run the instrumented and covered or whatever codes
-require('spawn-wrap').runMain()
-```
-
-## ENVIRONMENT VARIABLES
-
-Spawn-wrap responds to two environment variables, both of which are
-preserved through child processes.
-
-`SPAWN_WRAP_DEBUG=1` in the environment will make this module dump a
-lot of information to stderr.
-
-`SPAWN_WRAP_SHIM_ROOT` can be set to a path on the filesystem where
-the shim files are written in a `.node-spawn-wrap-<id>` folder. By
-default this is done in `$HOME`, but in some environments you may wish
-to point it at some other root. (For example, if `$HOME` is mounted
-as read-only in a virtual machine or container.)
-
-## CONTRACTS and CAVEATS
-
-The initial wrap call uses synchronous I/O. Probably you should not
-be using this script in any production environments anyway.
-
-Also, this will slow down child process execution by a lot, since
-we're adding a few layers of indirection.
-
-The contract which this library aims to uphold is:
-
-* Wrapped processes behave identical to their unwrapped counterparts
- for all intents and purposes. That means that the wrapper script
- propagates all signals and exit codes.
-* If you send a signal to the wrapper, the child gets the signal.
-* If the child exits with a numeric status code, then the wrapper
- exits with that code.
-* If the child dies with a signal, then the wrapper dies with the
- same signal.
-* If you execute any Node child process, in any of the various ways
- that such a thing can be done, it will be wrapped.
-* Children of wrapped processes are also wrapped.
-
-(Much of this made possible by
-[foreground-child](http://npm.im/foreground-child).)
-
-There are a few ways situations in which this contract cannot be
-adhered to, despite best efforts:
-
-1. In order to handle cases where `node` is invoked in a shell script,
- the `PATH` environment variable is modified such that the the shim
- will be run before the "real" node. However, since Windows does
- not allow executing shebang scripts like regular programs, a
- `node.cmd` file is required.
-2. Signal propagation through `dash` doesn't always work. So, if you
- use `child_process.exec()` on systems where `/bin/sh` is actually
- `dash`, then the process may exit with a status code > 128 rather
- than indicating that it received a signal.
-3. `cmd.exe` is even stranger with how it propagates and interprets
- unix signals. If you want your programs to be portable, then
- probably you wanna not rely on signals too much.
-4. It *is* possible to escape the wrapping, if you spawn a bash
- script, and that script modifies the `PATH`, and then calls a
- specific `node` binary explicitly.