childprocess 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 0f88536969a207dced9e122e8adfbf38e7e4bea75bb0fdb6dc83838db75718b2
-  data.tar.gz: 711c4d76098b6f0d7487428cc7af99331f9b95e2b978bd7b1435a5cd65ae7a38
+SHA1:
+  metadata.gz: 44f5b503e0f1a8763a429eac6f2b36a7cea4ac94
+  data.tar.gz: f2158bcb16256e0f2179df5ca8a012ffa4ca4a6d
 SHA512:
-  metadata.gz: 958c7579affa791c7c61e0dbe5f7f17118b57805b24f497876fb5a4bf0a35ff113dd69d52e2aaf3e0b3c1f9ae8a5e61104ac8cf17b88744280e94dbc4e1d5817
-  data.tar.gz: 7b65d73e847fe42c200cb2e42f8b89303358126d5a2490778f7523db38fd9bd63b209966c6e7eb4f2dbd123400a568f5c23e55e5948bcdb0a8edb949813e005b
+  metadata.gz: 04b3c2c4cd1ba2e1915f655ecc516b8c73ca9757373717174fbe7fd963e2bd19ac90ff4cffd9993e07db1b0165428e6bcbf4e23c4d46d147f33bf7d2add80955
+  data.tar.gz: 96bdbc109a5314f299eb1daf2064fb585b24224a91969e70bec1f9bd5d4460a88b95533121c45bddf989fbd13ac4d0109967b4afc55b88156cd72e447bf49f11

data/.document

@@ -1,6 +1,6 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
--
-LICENSE
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+-
+LICENSE

data/.gitignore

@@ -1,28 +1,28 @@
-## MAC OS
-.DS_Store
-
-## TEXTMATE
-*.tmproj
-tmtags
-
-## EMACS
-*~
-\#*
-.\#*
-
-## VIM
-*.swp
-
-## RubyMine
-.idea/*
-
-## PROJECT::GENERAL
-coverage
-rdoc
-pkg
-.rbx
-Gemfile.lock
-.ruby-version
-.bundle
-
-## PROJECT::SPECIFIC
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## RubyMine
+.idea/*
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+.rbx
+Gemfile.lock
+.ruby-version
+.bundle
+
+## PROJECT::SPECIFIC

data/.rspec

@@ -1 +1 @@
---color
+--color

data/.travis.yml

@@ -1,52 +1,51 @@
-os:
-  - linux
-  - osx
-
-rvm:
-  - 1.9.3
-  - jruby-9.1.9.0
-  - rbx-3
-  - 2.0.0
-  - 2.1
-  - 2.2
-  - 2.3
-  - 2.4
-  - 2.5
-  - ruby-head
-
-sudo: false
-
-cache: bundler
-
-before_install:
-  - "echo 'gem: --no-document' > ~/.gemrc"
-  # RubyGems update is supported for Ruby 2.3 and later
-  - ruby -e "system('gem update --system') if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.3')"
-  - gem install bundler --version '~> 1.17'
-
-before_script:
-  - 'export JAVA_OPTS="${JAVA_OPTS_FOR_SPECS}"'
-
-env:
-  global:
-  matrix:
-    - CHILDPROCESS_POSIX_SPAWN=true CHILDPROCESS_UNSET=should-be-unset
-    - CHILDPROCESS_POSIX_SPAWN=false CHILDPROCESS_UNSET=should-be-unset
-
-matrix:
-  allow_failures:
-    - rvm: rbx-3
-    - rvm: jruby-9.1.9.0
-    - rvm: ruby-head
-    - env: "CHILDPROCESS_POSIX_SPAWN=true"
-  include:
-  - rvm: jruby-9.2.5.0
-    jdk: openjdk11
-    env: "JAVA_OPTS_FOR_SPECS='--add-opens java.base/java.io=org.jruby.dist --add-opens java.base/sun.nio.ch=org.jruby.dist'"
-  exclude:
-    # Travis does not provide 1.9.3 on OSX
-  - rvm: 1.9.3
-    os: osx
-    # Travis does not provide 2.0.0 on it latest version of OSX
-  - rvm: 2.0.0
-    os: osx
+os:
+  - linux
+  - osx
+
+rvm:
+  - jruby-9.1.9.0
+  - rbx-3
+  - 2.0.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - 2.5
+  - ruby-head
+
+sudo: false
+
+cache: bundler
+
+before_install:
+  - "echo 'gem: --no-document' > ~/.gemrc"
+  # RubyGems update is supported for Ruby 2.3 and later
+  - ruby -e "system('gem update --system') if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.3')"
+  - gem install bundler --version '~> 1.17'
+
+before_script:
+  - 'export JAVA_OPTS="${JAVA_OPTS_FOR_SPECS}"'
+
+env:
+  global:
+  matrix:
+    - CHILDPROCESS_POSIX_SPAWN=true CHILDPROCESS_UNSET=should-be-unset
+    - CHILDPROCESS_POSIX_SPAWN=false CHILDPROCESS_UNSET=should-be-unset
+
+matrix:
+  allow_failures:
+    - rvm: rbx-3
+    - rvm: jruby-9.1.9.0
+    - rvm: ruby-head
+    - env: "CHILDPROCESS_POSIX_SPAWN=true"
+  include:
+  - rvm: jruby-9.2.5.0
+    jdk: openjdk11
+    env: "JAVA_OPTS_FOR_SPECS='--add-opens java.base/java.io=org.jruby.dist --add-opens java.base/sun.nio.ch=org.jruby.dist'"
+  exclude:
+    # Travis does not provide 1.9.3 on OSX
+  - rvm: 1.9.3
+    os: osx
+    # Travis does not provide 2.0.0 on it latest version of OSX
+  - rvm: 2.0.0
+    os: osx

data/CHANGELOG.md

@@ -1,56 +1,61 @@
-### Version 1.0.0 / 2019-01-28
-
-* [#134](https://github.com/enkessler/childprocess/pull/134): Add support for non-ASCII characters on Windows
-* [#132](https://github.com/enkessler/childprocess/pull/132): Install `ffi` gem requirement on Windows only
-* [#128](https://github.com/enkessler/childprocess/issues/128): Convert environment variable values to strings when `posix_spawn` enabled
-* [#141](https://github.com/enkessler/childprocess/pull/141): Support JRuby on Java >= 9
-
-### Version 0.9.0 / 2018-03-10
-
-* Added support for DragonFly BSD.
-
-
-### Version 0.8.0 / 2017-09-23
-
-* Added a method for determining whether or not a process had been started.
-
-
-### Version 0.7.1 / 2017-06-26
-
-* Fixed a noisy uninitialized variable warning
-
-
-### Version 0.7.0 / 2017-05-07
-
-* Debugging information now uses a Logger, which can be configured.
-
-
-### Version 0.6.3 / 2017-03-24
-
-See beta release notes.
-
-
-### Version 0.6.3.beta.1 / 2017-03-10
-
-* Bug fix: Fixed child process creation problems on Windows 7 when a child was declared as a leader.
-
-
-### Version 0.6.2 / 2017-02-25
-
-* Bug fix: Fixed a potentially broken edge case that could occur on older 32-bit OSX systems.
-
-
-### Version 0.6.1 / 2017-01-22
-
-* Bug fix: Fixed a dependency that was accidentally declared as a runtime
-  dependency instead of a development dependency.
-
-
-### Version 0.6.0 / 2017-01-22
-
-* Support for Ruby 2.4 added
-
-
-### Version 0.5.9 / 2016-01-06
-
-* The Great Before Times...
+### Version 1.0.1 / 2019-02-03
+
+* [#143](https://github.com/enkessler/childprocess/pull/144): Fix installs by adding `rake` gem as runtime dependency
+* [#147](https://github.com/enkessler/childprocess/pull/147): Relax `rake` gem constraint from `< 12` to `< 13`
+
+### Version 1.0.0 / 2019-01-28
+
+* [#134](https://github.com/enkessler/childprocess/pull/134): Add support for non-ASCII characters on Windows
+* [#132](https://github.com/enkessler/childprocess/pull/132): Install `ffi` gem requirement on Windows only
+* [#128](https://github.com/enkessler/childprocess/issues/128): Convert environment variable values to strings when `posix_spawn` enabled
+* [#141](https://github.com/enkessler/childprocess/pull/141): Support JRuby on Java >= 9
+
+### Version 0.9.0 / 2018-03-10
+
+* Added support for DragonFly BSD.
+
+
+### Version 0.8.0 / 2017-09-23
+
+* Added a method for determining whether or not a process had been started.
+
+
+### Version 0.7.1 / 2017-06-26
+
+* Fixed a noisy uninitialized variable warning
+
+
+### Version 0.7.0 / 2017-05-07
+
+* Debugging information now uses a Logger, which can be configured.
+
+
+### Version 0.6.3 / 2017-03-24
+
+See beta release notes.
+
+
+### Version 0.6.3.beta.1 / 2017-03-10
+
+* Bug fix: Fixed child process creation problems on Windows 7 when a child was declared as a leader.
+
+
+### Version 0.6.2 / 2017-02-25
+
+* Bug fix: Fixed a potentially broken edge case that could occur on older 32-bit OSX systems.
+
+
+### Version 0.6.1 / 2017-01-22
+
+* Bug fix: Fixed a dependency that was accidentally declared as a runtime
+  dependency instead of a development dependency.
+
+
+### Version 0.6.0 / 2017-01-22
+
+* Support for Ruby 2.4 added
+
+
+### Version 0.5.9 / 2016-01-06
+
+* The Great Before Times...

data/Gemfile

@@ -1,18 +1,18 @@
-source 'http://rubygems.org'
-
-# Specify your gem's dependencies in child_process.gemspec
-gemspec
-
-if RUBY_VERSION =~ /^1\./
-  gem 'tins', '< 1.7' # The 'tins' gem requires Ruby 2.x on/after this version
-  gem 'json', '< 2.0' # The 'json' gem drops pre-Ruby 2.x support on/after this version
-  gem 'term-ansicolor', '< 1.4' # The 'term-ansicolor' gem requires Ruby 2.x on/after this version
-
-  # ffi gem for Windows requires Ruby 2.x on/after this version
-  gem 'ffi', '< 1.9.15' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
-elsif Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.2')
-  # Ruby 2.0/2.1 support only ffi before 1.10
-  gem 'ffi', '~> 1.9.0' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
-else
-  gem 'ffi' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
-end
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in child_process.gemspec
+gemspec
+
+if RUBY_VERSION =~ /^1\./
+  gem 'tins', '< 1.7' # The 'tins' gem requires Ruby 2.x on/after this version
+  gem 'json', '< 2.0' # The 'json' gem drops pre-Ruby 2.x support on/after this version
+  gem 'term-ansicolor', '< 1.4' # The 'term-ansicolor' gem requires Ruby 2.x on/after this version
+
+  # ffi gem for Windows requires Ruby 2.x on/after this version
+  gem 'ffi', '< 1.9.15' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
+elsif Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.2')
+  # Ruby 2.0/2.1 support only ffi before 1.10
+  gem 'ffi', '~> 1.9.0' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
+else
+  gem 'ffi' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
+end

data/LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2010-2015 Jari Bakken
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2010-2015 Jari Bakken
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,200 +1,212 @@
-# childprocess
-
-This gem aims at being a simple and reliable solution for controlling
-external programs running in the background on any Ruby / OS combination.
-
-The code originated in the [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver) gem, but should prove useful as
-a standalone library.
-
-[![Build Status](https://secure.travis-ci.org/enkessler/childprocess.svg)](http://travis-ci.org/enkessler/childprocess)
-[![Build status](https://ci.appveyor.com/api/projects/status/fn2snbcd7kku5myk/branch/dev?svg=true)](https://ci.appveyor.com/project/enkessler/childprocess/branch/dev)
-[![Gem Version](https://badge.fury.io/rb/childprocess.svg)](http://badge.fury.io/rb/childprocess)
-[![Code Climate](https://codeclimate.com/github/enkessler/childprocess.svg)](https://codeclimate.com/github/enkessler/childprocess)
-[![Coverage Status](https://coveralls.io/repos/enkessler/childprocess/badge.svg?branch=master)](https://coveralls.io/r/enkessler/childprocess?branch=master)
-
-***
-**This project currently needs a new maintainer. If anyone is interested, please contact me, [enkessler](https://github.com/enkessler).**
-***
-
-# Usage
-
-The object returned from `ChildProcess.build` will implement `ChildProcess::AbstractProcess`.
-
-### Basic examples
-
-```ruby
-process = ChildProcess.build("ruby", "-e", "sleep")
-
-# inherit stdout/stderr from parent...
-process.io.inherit!
-
-# ...or pass an IO
-process.io.stdout = Tempfile.new("child-output")
-
-# modify the environment for the child
-process.environment["a"] = "b"
-process.environment["c"] = nil
-
-# set the child's working directory
-process.cwd = '/some/path'
-
-# start the process
-process.start
-
-# check process status
-process.alive?    #=> true
-process.exited?   #=> false
-
-# wait indefinitely for process to exit...
-process.wait
-process.exited?   #=> true
-
-# get the exit code
-process.exit_code #=> 0
-
-# ...or poll for exit + force quit
-begin
-  process.poll_for_exit(10)
-rescue ChildProcess::TimeoutError
-  process.stop # tries increasingly harsher methods to kill the process.
-end
-```
-
-### Advanced examples
-
-#### Output to pipe
-
-```ruby
-r, w = IO.pipe
-
-proc = ChildProcess.build("echo", "foo")
-proc.io.stdout = proc.io.stderr = w
-proc.start
-w.close
-
-begin
-  loop { print r.readpartial(8192) }
-rescue EOFError
-end
-
-proc.wait
-```
-
-Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
-
-#### Write to stdin
-
-```ruby
-process = ChildProcess.build("cat")
-
-out      = Tempfile.new("duplex")
-out.sync = true
-
-process.io.stdout = process.io.stderr = out
-process.duplex    = true # sets up pipe so process.io.stdin will be available after .start
-
-process.start
-process.io.stdin.puts "hello world"
-process.io.stdin.close
-
-process.poll_for_exit(exit_timeout_in_seconds)
-
-out.rewind
-out.read #=> "hello world\n"
-```
-
-#### Pipe output to another ChildProcess
-
-```ruby
-search           = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
-search.duplex    = true # sets up pipe so search.io.stdin will be available after .start
-search.io.stdout = $stdout
-search.start
-
-listing           = ChildProcess.build("ps", "aux")
-listing.io.stdout = search.io.stdin
-listing.start
-listing.wait
-
-search.io.stdin.close
-search.wait
-```
-
-#### Prefer posix_spawn on *nix
-
-If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
-
-```ruby
-ChildProcess.posix_spawn = true
-process = ChildProcess.build(*args)
-```
-
-To be able to use this, please make sure that you have the `ffi` gem installed.
-
-### Ensure entire process tree dies
-
-By default, the child process does not create a new process group. This means there's no guarantee that the entire process tree will die when the child process is killed. To solve this:
-
-```ruby
-process = ChildProcess.build(*args)
-process.leader = true
-process.start
-```
-
-#### Detach from parent
-
-```ruby
-process = ChildProcess.build("sleep", "10")
-process.detach = true
-process.start
-```
-
-#### Invoking a shell
-
-As opposed to `Kernel#system`, `Kernel#exec` et al., ChildProcess will not automatically execute your command in a shell (like `/bin/sh` or `cmd.exe`) depending on the arguments.
-This means that if you try to execute e.g. gem executables (like `bundle` or `gem`) or Windows executables (with `.com` or `.bat` extensions) you may see a `ChildProcess::LaunchError`.
-You can work around this by being explicit about what interpreter to invoke:
-
-```ruby
-ChildProcess.build("cmd.exe", "/c", "bundle")
-ChildProcess.build("ruby", "-S", "bundle")
-```
-
-#### Log to file
-
-Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead. 
-
-```ruby
-logger = Logger.new('logfile.log')
-logger.level = Logger::DEBUG
-ChildProcess.logger = logger
-```
-
-## Caveats
-
-* With JRuby on Unix, modifying `ENV["PATH"]` before using childprocess could lead to 'Command not found' errors, since JRuby is unable to modify the environment used for PATH searches in `java.lang.ProcessBuilder`. This can be avoided by setting `ChildProcess.posix_spawn = true`.
-* With JRuby on Java >= 9, the JVM may need to be configured to allow JRuby to access neccessary implementations; this can be done by adding `--add-opens java.base/java.io=org.jruby.dist` and `--add-opens java.base/sun.nio.ch=org.jruby.dist` to the `JAVA_OPTS` environment variable that is used by JRuby when launching the JVM.
-
-
-# Implementation
-
-How the process is launched and killed depends on the platform:
-
-* Unix     : `fork + exec` (or `posix_spawn` if enabled)
-* Windows  : `CreateProcess()` and friends
-* JRuby    : `java.lang.{Process,ProcessBuilder}`
-
-# Note on Patches/Pull Requests
-
-1. Fork it
-2. Create your feature branch (off of the development branch)
-   `git checkout -b my-new-feature dev`
-3. Commit your changes
-   `git commit -am 'Add some feature'`
-4. Push to the branch
-   `git push origin my-new-feature`
-5. Create new Pull Request
-
-# Copyright
-
-Copyright (c) 2010-2015 Jari Bakken. See LICENSE for details.
+# childprocess
+
+This gem aims at being a simple and reliable solution for controlling
+external programs running in the background on any Ruby / OS combination.
+
+The code originated in the [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver) gem, but should prove useful as
+a standalone library.
+
+[![Build Status](https://secure.travis-ci.org/enkessler/childprocess.svg)](http://travis-ci.org/enkessler/childprocess)
+[![Build status](https://ci.appveyor.com/api/projects/status/fn2snbcd7kku5myk/branch/dev?svg=true)](https://ci.appveyor.com/project/enkessler/childprocess/branch/dev)
+[![Gem Version](https://badge.fury.io/rb/childprocess.svg)](http://badge.fury.io/rb/childprocess)
+[![Code Climate](https://codeclimate.com/github/enkessler/childprocess.svg)](https://codeclimate.com/github/enkessler/childprocess)
+[![Coverage Status](https://coveralls.io/repos/enkessler/childprocess/badge.svg?branch=master)](https://coveralls.io/r/enkessler/childprocess?branch=master)
+
+***
+**This project currently needs a new maintainer. If anyone is interested, please contact me, [enkessler](https://github.com/enkessler).**
+***
+
+# Usage
+
+The object returned from `ChildProcess.build` will implement `ChildProcess::AbstractProcess`.
+
+### Basic examples
+
+```ruby
+process = ChildProcess.build("ruby", "-e", "sleep")
+
+# inherit stdout/stderr from parent...
+process.io.inherit!
+
+# ...or pass an IO
+process.io.stdout = Tempfile.new("child-output")
+
+# modify the environment for the child
+process.environment["a"] = "b"
+process.environment["c"] = nil
+
+# set the child's working directory
+process.cwd = '/some/path'
+
+# start the process
+process.start
+
+# check process status
+process.alive?    #=> true
+process.exited?   #=> false
+
+# wait indefinitely for process to exit...
+process.wait
+process.exited?   #=> true
+
+# get the exit code
+process.exit_code #=> 0
+
+# ...or poll for exit + force quit
+begin
+  process.poll_for_exit(10)
+rescue ChildProcess::TimeoutError
+  process.stop # tries increasingly harsher methods to kill the process.
+end
+```
+
+### Advanced examples
+
+#### Output to pipe
+
+```ruby
+r, w = IO.pipe
+
+proc = ChildProcess.build("echo", "foo")
+proc.io.stdout = proc.io.stderr = w
+proc.start
+w.close
+
+begin
+  loop { print r.readpartial(8192) }
+rescue EOFError
+end
+
+proc.wait
+```
+
+Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
+
+#### Write to stdin
+
+```ruby
+process = ChildProcess.build("cat")
+
+out      = Tempfile.new("duplex")
+out.sync = true
+
+process.io.stdout = process.io.stderr = out
+process.duplex    = true # sets up pipe so process.io.stdin will be available after .start
+
+process.start
+process.io.stdin.puts "hello world"
+process.io.stdin.close
+
+process.poll_for_exit(exit_timeout_in_seconds)
+
+out.rewind
+out.read #=> "hello world\n"
+```
+
+#### Pipe output to another ChildProcess
+
+```ruby
+search           = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
+search.duplex    = true # sets up pipe so search.io.stdin will be available after .start
+search.io.stdout = $stdout
+search.start
+
+listing           = ChildProcess.build("ps", "aux")
+listing.io.stdout = search.io.stdin
+listing.start
+listing.wait
+
+search.io.stdin.close
+search.wait
+```
+
+#### Prefer posix_spawn on *nix
+
+If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
+
+```ruby
+ChildProcess.posix_spawn = true
+process = ChildProcess.build(*args)
+```
+
+To be able to use this, please make sure that you have the `ffi` gem installed.
+
+### Ensure entire process tree dies
+
+By default, the child process does not create a new process group. This means there's no guarantee that the entire process tree will die when the child process is killed. To solve this:
+
+```ruby
+process = ChildProcess.build(*args)
+process.leader = true
+process.start
+```
+
+#### Detach from parent
+
+```ruby
+process = ChildProcess.build("sleep", "10")
+process.detach = true
+process.start
+```
+
+#### Invoking a shell
+
+As opposed to `Kernel#system`, `Kernel#exec` et al., ChildProcess will not automatically execute your command in a shell (like `/bin/sh` or `cmd.exe`) depending on the arguments.
+This means that if you try to execute e.g. gem executables (like `bundle` or `gem`) or Windows executables (with `.com` or `.bat` extensions) you may see a `ChildProcess::LaunchError`.
+You can work around this by being explicit about what interpreter to invoke:
+
+```ruby
+ChildProcess.build("cmd.exe", "/c", "bundle")
+ChildProcess.build("ruby", "-S", "bundle")
+```
+
+#### Log to file
+
+Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead.
+
+```ruby
+logger = Logger.new('logfile.log')
+logger.level = Logger::DEBUG
+ChildProcess.logger = logger
+```
+
+## Caveats
+
+* With JRuby on Unix, modifying `ENV["PATH"]` before using childprocess could lead to 'Command not found' errors, since JRuby is unable to modify the environment used for PATH searches in `java.lang.ProcessBuilder`. This can be avoided by setting `ChildProcess.posix_spawn = true`.
+* With JRuby on Java >= 9, the JVM may need to be configured to allow JRuby to access neccessary implementations; this can be done by adding `--add-opens java.base/java.io=org.jruby.dist` and `--add-opens java.base/sun.nio.ch=org.jruby.dist` to the `JAVA_OPTS` environment variable that is used by JRuby when launching the JVM.
+
+# Implementation
+
+How the process is launched and killed depends on the platform:
+
+* Unix     : `fork + exec` (or `posix_spawn` if enabled)
+* Windows  : `CreateProcess()` and friends
+* JRuby    : `java.lang.{Process,ProcessBuilder}`
+
+# Note on Patches/Pull Requests
+
+1. Fork it
+2. Create your feature branch (off of the development branch)
+   `git checkout -b my-new-feature dev`
+3. Commit your changes
+   `git commit -am 'Add some feature'`
+4. Push to the branch
+   `git push origin my-new-feature`
+5. Create new Pull Request
+
+# Publishing a New Release
+
+When publishing a new gem release:
+
+1. Ensure [latest build is green on the `dev` branch](https://travis-ci.org/enkessler/childprocess/branches)
+2. Ensure [CHANGELOG](CHANGELOG.md) is updated
+3. Ensure [version is bumped](lib/childprocess/version.rb) following [Semantic Versioning](https://semver.org/)
+4. Merge the `dev` branch into `master`: `git checkout master && git merge dev`
+5. Ensure [latest build is green on the `master` branch](https://travis-ci.org/enkessler/childprocess/branches)
+6. Build gem from the green `master` branch: `git checkout master && gem build childprocess.gemspec`
+7. Push gem to RubyGems: `gem push childprocess-<VERSION>.gem`
+8. Tag commit with version, annotated with release notes: `git tag -a <VERSION>`
+
+# Copyright
+
+Copyright (c) 2010-2015 Jari Bakken. See [LICENSE](LICENSE) for details.