childprocess 0.9.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 2f7bcd4a74bf8315015b61ff4a5dcf5774fec372
-  data.tar.gz: ebb386c0ffd4b05121cbc8c3f18ded1d8721552b
+SHA256:
+  metadata.gz: b4e76f415dff2879680f9ca7c48442132fde2099dbdcd956aaf44b429269067b
+  data.tar.gz: b02b05e8ec6ad8a63c31cbaae6067cf5dae11e80b79850ebf9cf630e6fe69ddf
 SHA512:
-  metadata.gz: 264821e0ea3147f6d19f63d76f5e290462e0ae8991d6858839b949a470f8ef173b716f5000f24fdfe9b86446eab1da593e7ad81e7cac83880fa7af81e7441563
-  data.tar.gz: 26f5534f0cb73ad3482e513706ca7a53d87c7f610efeaf09f64f0c4205b293db565548c097290d27a4b49a2b831f9593edbfc4cf7c0da73903d05c1c3fd98b23
+  metadata.gz: ea2985d14f2b941e48dfa544c4531440560e6e4fc7c8edb1bdf68200099f9002cba20e033c0267a5f87bed8f886ae655dd3476c023f1133ce0729d7428610d8f
+  data.tar.gz: d962183e2e67e3612be72a7120a2a083bae78f738662cd8f0af7e50513b9936406814a25136e8a5cb7ae2c3166eb4d3ead38f85be834478b6fd26106c000dd56

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,44 +1,37 @@
-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: true # Necessary to fix JRuby
-
-cache: bundler
-
-before_install:
-  - "echo 'gem: --no-document' > ~/.gemrc"
-  - gem update --system
-  - gem install bundler  # Necessary to fix 1.9.3
-
-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"
-  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:
+  - rbx-3
+  - 2.4
+  - 2.5
+  - 2.6
+  - ruby-head
+
+sudo: false
+
+cache: bundler
+
+before_install:
+  - "echo 'gem: --no-document' > ~/.gemrc"
+  - gem install bundler
+
+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: 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'"

data/CHANGELOG.md

@@ -1,49 +1,77 @@
-### 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 4.0.0 / 2020-06-18
+
+* [#167](https://github.com/enkessler/childprocess/pull/167): Fix detach behavior on Windows
+
+### Version 3.0.0 / 2019-09-20
+
+* [#156](https://github.com/enkessler/childprocess/pull/156): Remove unused `rubyforge_project` from gemspec
+* [#160](https://github.com/enkessler/childprocess/pull/160): Remove extension to conditionally install `ffi` gem on Windows platforms
+* [#160](https://github.com/enkessler/childprocess/pull/160): Remove runtime dependency on `rake` gem
+
+### Version 2.0.0 / 2019-07-11
+
+* [#148](https://github.com/enkessler/childprocess/pull/148): Drop support for Ruby 2.0, 2.1, and 2.2
+* [#149](https://github.com/enkessler/childprocess/pull/149): Fix Unix fork reopen to be compatible with Ruby 2.6
+* [#152](https://github.com/enkessler/childprocess/pull/152)/[#154](https://github.com/enkessler/childprocess/pull/154): Fix hangs and permission errors introduced in Ruby 2.6 for leader processes of process groups
+
+### 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,15 +1,21 @@
-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
-
-  if RbConfig::CONFIG['host_os'].downcase =~ /mswin|msys|mingw32/
-    gem 'ffi', '< 1.9.15' # The 'ffi' gem, for Windows, requires Ruby 2.x on/after this version
-  end
-end
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in child_process.gemspec
+gemspec
+
+# Used for local development/testing only
+gem 'rake'
+
+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,196 +1,230 @@
-# 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)
-```
-
-### 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`.
-
-# 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)
+
+# Requirements
+
+* Ruby 2.4+, JRuby 9+
+
+Windows users **must** ensure the `ffi` gem (`>= 1.0.11`) is installed in order to use ChildProcess.
+
+# 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
+
+begin
+  process = ChildProcess.build("sh" , "-c",
+                               "for i in {1..3}; do echo $i; sleep 1; done")
+  process.io.stdout = w
+  process.start # This results in a fork, inheriting the write end of the pipe.
+
+  # Close parent's copy of the write end of the pipe so when the (forked) child
+  # process closes its write end of the pipe the parent receives EOF when
+  # attempting to read from it. If the parent leaves its write end open, it
+  # will not detect EOF.
+  w.close
+
+  thread = Thread.new do
+    begin
+      loop do
+        print r.readpartial(16384)
+      end
+    rescue EOFError
+      # Child has closed the write end of the pipe
+    end
+  end
+
+  process.wait
+  thread.join
+ensure
+  r.close
+end
+```
+
+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.