childprocess 0.9.0 → 4.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (50) hide show
  1. checksums.yaml +5 -5
  2. data/.document +6 -6
  3. data/.gitignore +28 -28
  4. data/.rspec +1 -1
  5. data/.travis.yml +37 -44
  6. data/CHANGELOG.md +77 -49
  7. data/Gemfile +21 -15
  8. data/LICENSE +20 -20
  9. data/README.md +230 -196
  10. data/Rakefile +61 -61
  11. data/appveyor.yml +36 -60
  12. data/childprocess.gemspec +26 -30
  13. data/lib/childprocess.rb +210 -205
  14. data/lib/childprocess/abstract_io.rb +36 -36
  15. data/lib/childprocess/abstract_process.rb +192 -192
  16. data/lib/childprocess/errors.rb +37 -26
  17. data/lib/childprocess/jruby.rb +56 -56
  18. data/lib/childprocess/jruby/io.rb +16 -16
  19. data/lib/childprocess/jruby/process.rb +184 -159
  20. data/lib/childprocess/jruby/pump.rb +53 -53
  21. data/lib/childprocess/tools/generator.rb +145 -145
  22. data/lib/childprocess/unix.rb +9 -9
  23. data/lib/childprocess/unix/fork_exec_process.rb +78 -70
  24. data/lib/childprocess/unix/io.rb +21 -21
  25. data/lib/childprocess/unix/lib.rb +186 -186
  26. data/lib/childprocess/unix/platform/i386-linux.rb +12 -12
  27. data/lib/childprocess/unix/platform/i386-solaris.rb +11 -11
  28. data/lib/childprocess/unix/platform/x86_64-linux.rb +12 -12
  29. data/lib/childprocess/unix/platform/x86_64-macosx.rb +11 -11
  30. data/lib/childprocess/unix/posix_spawn_process.rb +134 -134
  31. data/lib/childprocess/unix/process.rb +90 -89
  32. data/lib/childprocess/version.rb +3 -3
  33. data/lib/childprocess/windows.rb +38 -33
  34. data/lib/childprocess/windows/handle.rb +91 -91
  35. data/lib/childprocess/windows/io.rb +25 -25
  36. data/lib/childprocess/windows/lib.rb +416 -416
  37. data/lib/childprocess/windows/process.rb +131 -130
  38. data/lib/childprocess/windows/process_builder.rb +178 -175
  39. data/lib/childprocess/windows/structs.rb +148 -148
  40. data/spec/abstract_io_spec.rb +12 -12
  41. data/spec/childprocess_spec.rb +447 -422
  42. data/spec/get_env.ps1 +13 -0
  43. data/spec/io_spec.rb +228 -228
  44. data/spec/jruby_spec.rb +24 -24
  45. data/spec/pid_behavior.rb +12 -12
  46. data/spec/platform_detection_spec.rb +86 -86
  47. data/spec/spec_helper.rb +270 -261
  48. data/spec/unix_spec.rb +57 -57
  49. data/spec/windows_spec.rb +23 -23
  50. metadata +8 -39
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- SHA1:
3
- metadata.gz: 2f7bcd4a74bf8315015b61ff4a5dcf5774fec372
4
- data.tar.gz: ebb386c0ffd4b05121cbc8c3f18ded1d8721552b
2
+ SHA256:
3
+ metadata.gz: b4e76f415dff2879680f9ca7c48442132fde2099dbdcd956aaf44b429269067b
4
+ data.tar.gz: b02b05e8ec6ad8a63c31cbaae6067cf5dae11e80b79850ebf9cf630e6fe69ddf
5
5
  SHA512:
6
- metadata.gz: 264821e0ea3147f6d19f63d76f5e290462e0ae8991d6858839b949a470f8ef173b716f5000f24fdfe9b86446eab1da593e7ad81e7cac83880fa7af81e7441563
7
- data.tar.gz: 26f5534f0cb73ad3482e513706ca7a53d87c7f610efeaf09f64f0c4205b293db565548c097290d27a4b49a2b831f9593edbfc4cf7c0da73903d05c1c3fd98b23
6
+ metadata.gz: ea2985d14f2b941e48dfa544c4531440560e6e4fc7c8edb1bdf68200099f9002cba20e033c0267a5f87bed8f886ae655dd3476c023f1133ce0729d7428610d8f
7
+ data.tar.gz: d962183e2e67e3612be72a7120a2a083bae78f738662cd8f0af7e50513b9936406814a25136e8a5cb7ae2c3166eb4d3ead38f85be834478b6fd26106c000dd56
data/.document CHANGED
@@ -1,6 +1,6 @@
1
- README.rdoc
2
- lib/**/*.rb
3
- bin/*
4
- features/**/*.feature
5
- -
6
- LICENSE
1
+ README.rdoc
2
+ lib/**/*.rb
3
+ bin/*
4
+ features/**/*.feature
5
+ -
6
+ LICENSE
data/.gitignore CHANGED
@@ -1,28 +1,28 @@
1
- ## MAC OS
2
- .DS_Store
3
-
4
- ## TEXTMATE
5
- *.tmproj
6
- tmtags
7
-
8
- ## EMACS
9
- *~
10
- \#*
11
- .\#*
12
-
13
- ## VIM
14
- *.swp
15
-
16
- ## RubyMine
17
- .idea/*
18
-
19
- ## PROJECT::GENERAL
20
- coverage
21
- rdoc
22
- pkg
23
- .rbx
24
- Gemfile.lock
25
- .ruby-version
26
- .bundle
27
-
28
- ## PROJECT::SPECIFIC
1
+ ## MAC OS
2
+ .DS_Store
3
+
4
+ ## TEXTMATE
5
+ *.tmproj
6
+ tmtags
7
+
8
+ ## EMACS
9
+ *~
10
+ \#*
11
+ .\#*
12
+
13
+ ## VIM
14
+ *.swp
15
+
16
+ ## RubyMine
17
+ .idea/*
18
+
19
+ ## PROJECT::GENERAL
20
+ coverage
21
+ rdoc
22
+ pkg
23
+ .rbx
24
+ Gemfile.lock
25
+ .ruby-version
26
+ .bundle
27
+
28
+ ## PROJECT::SPECIFIC
data/.rspec CHANGED
@@ -1 +1 @@
1
- --color
1
+ --color
@@ -1,44 +1,37 @@
1
- os:
2
- - linux
3
- - osx
4
-
5
- rvm:
6
- - 1.9.3
7
- - jruby-9.1.9.0
8
- - rbx-3
9
- - 2.0.0
10
- - 2.1
11
- - 2.2
12
- - 2.3
13
- - 2.4
14
- - 2.5
15
- - ruby-head
16
-
17
- sudo: true # Necessary to fix JRuby
18
-
19
- cache: bundler
20
-
21
- before_install:
22
- - "echo 'gem: --no-document' > ~/.gemrc"
23
- - gem update --system
24
- - gem install bundler # Necessary to fix 1.9.3
25
-
26
- env:
27
- global:
28
- matrix:
29
- - CHILDPROCESS_POSIX_SPAWN=true CHILDPROCESS_UNSET=should-be-unset
30
- - CHILDPROCESS_POSIX_SPAWN=false CHILDPROCESS_UNSET=should-be-unset
31
-
32
- matrix:
33
- allow_failures:
34
- - rvm: rbx-3
35
- - rvm: jruby-9.1.9.0
36
- - rvm: ruby-head
37
- - env: "CHILDPROCESS_POSIX_SPAWN=true"
38
- exclude:
39
- # Travis does not provide 1.9.3 on OSX
40
- - rvm: 1.9.3
41
- os: osx
42
- # Travis does not provide 2.0.0 on it latest version of OSX
43
- - rvm: 2.0.0
44
- os: osx
1
+ os:
2
+ - linux
3
+ - osx
4
+
5
+ rvm:
6
+ - rbx-3
7
+ - 2.4
8
+ - 2.5
9
+ - 2.6
10
+ - ruby-head
11
+
12
+ sudo: false
13
+
14
+ cache: bundler
15
+
16
+ before_install:
17
+ - "echo 'gem: --no-document' > ~/.gemrc"
18
+ - gem install bundler
19
+
20
+ before_script:
21
+ - 'export JAVA_OPTS="${JAVA_OPTS_FOR_SPECS}"'
22
+
23
+ env:
24
+ global:
25
+ matrix:
26
+ - CHILDPROCESS_POSIX_SPAWN=true CHILDPROCESS_UNSET=should-be-unset
27
+ - CHILDPROCESS_POSIX_SPAWN=false CHILDPROCESS_UNSET=should-be-unset
28
+
29
+ matrix:
30
+ allow_failures:
31
+ - rvm: rbx-3
32
+ - rvm: ruby-head
33
+ - env: "CHILDPROCESS_POSIX_SPAWN=true"
34
+ include:
35
+ - rvm: jruby-9.2.5.0
36
+ jdk: openjdk11
37
+ env: "JAVA_OPTS_FOR_SPECS='--add-opens java.base/java.io=org.jruby.dist --add-opens java.base/sun.nio.ch=org.jruby.dist'"
@@ -1,49 +1,77 @@
1
- ### Version 0.9.0 / 2018-03-10
2
-
3
- * Added support for DragonFly BSD.
4
-
5
-
6
- ### Version 0.8.0 / 2017-09-23
7
-
8
- * Added a method for determining whether or not a process had been started.
9
-
10
-
11
- ### Version 0.7.1 / 2017-06-26
12
-
13
- * Fixed a noisy uninitialized variable warning
14
-
15
-
16
- ### Version 0.7.0 / 2017-05-07
17
-
18
- * Debugging information now uses a Logger, which can be configured.
19
-
20
-
21
- ### Version 0.6.3 / 2017-03-24
22
-
23
- See beta release notes.
24
-
25
-
26
- ### Version 0.6.3.beta.1 / 2017-03-10
27
-
28
- * Bug fix: Fixed child process creation problems on Windows 7 when a child was declared as a leader.
29
-
30
-
31
- ### Version 0.6.2 / 2017-02-25
32
-
33
- * Bug fix: Fixed a potentially broken edge case that could occur on older 32-bit OSX systems.
34
-
35
-
36
- ### Version 0.6.1 / 2017-01-22
37
-
38
- * Bug fix: Fixed a dependency that was accidentally declared as a runtime
39
- dependency instead of a development dependency.
40
-
41
-
42
- ### Version 0.6.0 / 2017-01-22
43
-
44
- * Support for Ruby 2.4 added
45
-
46
-
47
- ### Version 0.5.9 / 2016-01-06
48
-
49
- * The Great Before Times...
1
+ ### Version 4.0.0 / 2020-06-18
2
+
3
+ * [#167](https://github.com/enkessler/childprocess/pull/167): Fix detach behavior on Windows
4
+
5
+ ### Version 3.0.0 / 2019-09-20
6
+
7
+ * [#156](https://github.com/enkessler/childprocess/pull/156): Remove unused `rubyforge_project` from gemspec
8
+ * [#160](https://github.com/enkessler/childprocess/pull/160): Remove extension to conditionally install `ffi` gem on Windows platforms
9
+ * [#160](https://github.com/enkessler/childprocess/pull/160): Remove runtime dependency on `rake` gem
10
+
11
+ ### Version 2.0.0 / 2019-07-11
12
+
13
+ * [#148](https://github.com/enkessler/childprocess/pull/148): Drop support for Ruby 2.0, 2.1, and 2.2
14
+ * [#149](https://github.com/enkessler/childprocess/pull/149): Fix Unix fork reopen to be compatible with Ruby 2.6
15
+ * [#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
16
+
17
+ ### Version 1.0.1 / 2019-02-03
18
+
19
+ * [#143](https://github.com/enkessler/childprocess/pull/144): Fix installs by adding `rake` gem as runtime dependency
20
+ * [#147](https://github.com/enkessler/childprocess/pull/147): Relax `rake` gem constraint from `< 12` to `< 13`
21
+
22
+ ### Version 1.0.0 / 2019-01-28
23
+
24
+ * [#134](https://github.com/enkessler/childprocess/pull/134): Add support for non-ASCII characters on Windows
25
+ * [#132](https://github.com/enkessler/childprocess/pull/132): Install `ffi` gem requirement on Windows only
26
+ * [#128](https://github.com/enkessler/childprocess/issues/128): Convert environment variable values to strings when `posix_spawn` enabled
27
+ * [#141](https://github.com/enkessler/childprocess/pull/141): Support JRuby on Java >= 9
28
+
29
+ ### Version 0.9.0 / 2018-03-10
30
+
31
+ * Added support for DragonFly BSD.
32
+
33
+
34
+ ### Version 0.8.0 / 2017-09-23
35
+
36
+ * Added a method for determining whether or not a process had been started.
37
+
38
+
39
+ ### Version 0.7.1 / 2017-06-26
40
+
41
+ * Fixed a noisy uninitialized variable warning
42
+
43
+
44
+ ### Version 0.7.0 / 2017-05-07
45
+
46
+ * Debugging information now uses a Logger, which can be configured.
47
+
48
+
49
+ ### Version 0.6.3 / 2017-03-24
50
+
51
+ See beta release notes.
52
+
53
+
54
+ ### Version 0.6.3.beta.1 / 2017-03-10
55
+
56
+ * Bug fix: Fixed child process creation problems on Windows 7 when a child was declared as a leader.
57
+
58
+
59
+ ### Version 0.6.2 / 2017-02-25
60
+
61
+ * Bug fix: Fixed a potentially broken edge case that could occur on older 32-bit OSX systems.
62
+
63
+
64
+ ### Version 0.6.1 / 2017-01-22
65
+
66
+ * Bug fix: Fixed a dependency that was accidentally declared as a runtime
67
+ dependency instead of a development dependency.
68
+
69
+
70
+ ### Version 0.6.0 / 2017-01-22
71
+
72
+ * Support for Ruby 2.4 added
73
+
74
+
75
+ ### Version 0.5.9 / 2016-01-06
76
+
77
+ * The Great Before Times...
data/Gemfile CHANGED
@@ -1,15 +1,21 @@
1
- source "http://rubygems.org"
2
-
3
- # Specify your gem's dependencies in child_process.gemspec
4
- gemspec
5
-
6
-
7
- if RUBY_VERSION =~ /^1\./
8
- gem 'tins', '< 1.7' # The 'tins' gem requires Ruby 2.x on/after this version
9
- gem 'json', '< 2.0' # The 'json' gem drops pre-Ruby 2.x support on/after this version
10
- gem 'term-ansicolor', '< 1.4' # The 'term-ansicolor' gem requires Ruby 2.x on/after this version
11
-
12
- if RbConfig::CONFIG['host_os'].downcase =~ /mswin|msys|mingw32/
13
- gem 'ffi', '< 1.9.15' # The 'ffi' gem, for Windows, requires Ruby 2.x on/after this version
14
- end
15
- end
1
+ source 'http://rubygems.org'
2
+
3
+ # Specify your gem's dependencies in child_process.gemspec
4
+ gemspec
5
+
6
+ # Used for local development/testing only
7
+ gem 'rake'
8
+
9
+ if RUBY_VERSION =~ /^1\./
10
+ gem 'tins', '< 1.7' # The 'tins' gem requires Ruby 2.x on/after this version
11
+ gem 'json', '< 2.0' # The 'json' gem drops pre-Ruby 2.x support on/after this version
12
+ gem 'term-ansicolor', '< 1.4' # The 'term-ansicolor' gem requires Ruby 2.x on/after this version
13
+
14
+ # ffi gem for Windows requires Ruby 2.x on/after this version
15
+ gem 'ffi', '< 1.9.15' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
16
+ elsif Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.2')
17
+ # Ruby 2.0/2.1 support only ffi before 1.10
18
+ gem 'ffi', '~> 1.9.0' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
19
+ else
20
+ gem 'ffi' if ENV['CHILDPROCESS_POSIX_SPAWN'] == 'true' || Gem.win_platform?
21
+ end
data/LICENSE CHANGED
@@ -1,20 +1,20 @@
1
- Copyright (c) 2010-2015 Jari Bakken
2
-
3
- Permission is hereby granted, free of charge, to any person obtaining
4
- a copy of this software and associated documentation files (the
5
- "Software"), to deal in the Software without restriction, including
6
- without limitation the rights to use, copy, modify, merge, publish,
7
- distribute, sublicense, and/or sell copies of the Software, and to
8
- permit persons to whom the Software is furnished to do so, subject to
9
- the following conditions:
10
-
11
- The above copyright notice and this permission notice shall be
12
- included in all copies or substantial portions of the Software.
13
-
14
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1
+ Copyright (c) 2010-2015 Jari Bakken
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.md CHANGED
@@ -1,196 +1,230 @@
1
- # childprocess
2
-
3
- This gem aims at being a simple and reliable solution for controlling
4
- external programs running in the background on any Ruby / OS combination.
5
-
6
- The code originated in the [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver) gem, but should prove useful as
7
- a standalone library.
8
-
9
- [![Build Status](https://secure.travis-ci.org/enkessler/childprocess.svg)](http://travis-ci.org/enkessler/childprocess)
10
- [![Build status](https://ci.appveyor.com/api/projects/status/fn2snbcd7kku5myk/branch/dev?svg=true)](https://ci.appveyor.com/project/enkessler/childprocess/branch/dev)
11
- [![Gem Version](https://badge.fury.io/rb/childprocess.svg)](http://badge.fury.io/rb/childprocess)
12
- [![Code Climate](https://codeclimate.com/github/enkessler/childprocess.svg)](https://codeclimate.com/github/enkessler/childprocess)
13
- [![Coverage Status](https://coveralls.io/repos/enkessler/childprocess/badge.svg?branch=master)](https://coveralls.io/r/enkessler/childprocess?branch=master)
14
-
15
- ***
16
- **This project currently needs a new maintainer. If anyone is interested, please contact me, [enkessler](https://github.com/enkessler).**
17
- ***
18
-
19
- # Usage
20
-
21
- The object returned from `ChildProcess.build` will implement `ChildProcess::AbstractProcess`.
22
-
23
- ### Basic examples
24
-
25
- ```ruby
26
- process = ChildProcess.build("ruby", "-e", "sleep")
27
-
28
- # inherit stdout/stderr from parent...
29
- process.io.inherit!
30
-
31
- # ...or pass an IO
32
- process.io.stdout = Tempfile.new("child-output")
33
-
34
- # modify the environment for the child
35
- process.environment["a"] = "b"
36
- process.environment["c"] = nil
37
-
38
- # set the child's working directory
39
- process.cwd = '/some/path'
40
-
41
- # start the process
42
- process.start
43
-
44
- # check process status
45
- process.alive? #=> true
46
- process.exited? #=> false
47
-
48
- # wait indefinitely for process to exit...
49
- process.wait
50
- process.exited? #=> true
51
-
52
- # get the exit code
53
- process.exit_code #=> 0
54
-
55
- # ...or poll for exit + force quit
56
- begin
57
- process.poll_for_exit(10)
58
- rescue ChildProcess::TimeoutError
59
- process.stop # tries increasingly harsher methods to kill the process.
60
- end
61
- ```
62
-
63
- ### Advanced examples
64
-
65
- #### Output to pipe
66
-
67
- ```ruby
68
- r, w = IO.pipe
69
-
70
- proc = ChildProcess.build("echo", "foo")
71
- proc.io.stdout = proc.io.stderr = w
72
- proc.start
73
- w.close
74
-
75
- begin
76
- loop { print r.readpartial(8192) }
77
- rescue EOFError
78
- end
79
-
80
- proc.wait
81
- ```
82
-
83
- Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
84
-
85
- #### Write to stdin
86
-
87
- ```ruby
88
- process = ChildProcess.build("cat")
89
-
90
- out = Tempfile.new("duplex")
91
- out.sync = true
92
-
93
- process.io.stdout = process.io.stderr = out
94
- process.duplex = true # sets up pipe so process.io.stdin will be available after .start
95
-
96
- process.start
97
- process.io.stdin.puts "hello world"
98
- process.io.stdin.close
99
-
100
- process.poll_for_exit(exit_timeout_in_seconds)
101
-
102
- out.rewind
103
- out.read #=> "hello world\n"
104
- ```
105
-
106
- #### Pipe output to another ChildProcess
107
-
108
- ```ruby
109
- search = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
110
- search.duplex = true # sets up pipe so search.io.stdin will be available after .start
111
- search.io.stdout = $stdout
112
- search.start
113
-
114
- listing = ChildProcess.build("ps", "aux")
115
- listing.io.stdout = search.io.stdin
116
- listing.start
117
- listing.wait
118
-
119
- search.io.stdin.close
120
- search.wait
121
- ```
122
-
123
- #### Prefer posix_spawn on *nix
124
-
125
- If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
126
-
127
- ```ruby
128
- ChildProcess.posix_spawn = true
129
- process = ChildProcess.build(*args)
130
- ```
131
-
132
- ### Ensure entire process tree dies
133
-
134
- 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:
135
-
136
- ```ruby
137
- process = ChildProcess.build(*args)
138
- process.leader = true
139
- process.start
140
- ```
141
-
142
- #### Detach from parent
143
-
144
- ```ruby
145
- process = ChildProcess.build("sleep", "10")
146
- process.detach = true
147
- process.start
148
- ```
149
-
150
- #### Invoking a shell
151
-
152
- 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.
153
- 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`.
154
- You can work around this by being explicit about what interpreter to invoke:
155
-
156
- ```ruby
157
- ChildProcess.build("cmd.exe", "/c", "bundle")
158
- ChildProcess.build("ruby", "-S", "bundle")
159
- ```
160
-
161
- #### Log to file
162
-
163
- Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead.
164
-
165
- ```ruby
166
- logger = Logger.new('logfile.log')
167
- logger.level = Logger::DEBUG
168
- ChildProcess.logger = logger
169
- ```
170
-
171
- ## Caveats
172
-
173
- * 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`.
174
-
175
- # Implementation
176
-
177
- How the process is launched and killed depends on the platform:
178
-
179
- * Unix : `fork + exec` (or `posix_spawn` if enabled)
180
- * Windows : `CreateProcess()` and friends
181
- * JRuby : `java.lang.{Process,ProcessBuilder}`
182
-
183
- # Note on Patches/Pull Requests
184
-
185
- 1. Fork it
186
- 2. Create your feature branch (off of the development branch)
187
- `git checkout -b my-new-feature dev`
188
- 3. Commit your changes
189
- `git commit -am 'Add some feature'`
190
- 4. Push to the branch
191
- `git push origin my-new-feature`
192
- 5. Create new Pull Request
193
-
194
- # Copyright
195
-
196
- Copyright (c) 2010-2015 Jari Bakken. See LICENSE for details.
1
+ # childprocess
2
+
3
+ This gem aims at being a simple and reliable solution for controlling
4
+ external programs running in the background on any Ruby / OS combination.
5
+
6
+ The code originated in the [selenium-webdriver](https://rubygems.org/gems/selenium-webdriver) gem, but should prove useful as
7
+ a standalone library.
8
+
9
+ [![Build Status](https://secure.travis-ci.org/enkessler/childprocess.svg)](http://travis-ci.org/enkessler/childprocess)
10
+ [![Build status](https://ci.appveyor.com/api/projects/status/fn2snbcd7kku5myk/branch/dev?svg=true)](https://ci.appveyor.com/project/enkessler/childprocess/branch/dev)
11
+ [![Gem Version](https://badge.fury.io/rb/childprocess.svg)](http://badge.fury.io/rb/childprocess)
12
+ [![Code Climate](https://codeclimate.com/github/enkessler/childprocess.svg)](https://codeclimate.com/github/enkessler/childprocess)
13
+ [![Coverage Status](https://coveralls.io/repos/enkessler/childprocess/badge.svg?branch=master)](https://coveralls.io/r/enkessler/childprocess?branch=master)
14
+
15
+ # Requirements
16
+
17
+ * Ruby 2.4+, JRuby 9+
18
+
19
+ Windows users **must** ensure the `ffi` gem (`>= 1.0.11`) is installed in order to use ChildProcess.
20
+
21
+ # Usage
22
+
23
+ The object returned from `ChildProcess.build` will implement `ChildProcess::AbstractProcess`.
24
+
25
+ ### Basic examples
26
+
27
+ ```ruby
28
+ process = ChildProcess.build("ruby", "-e", "sleep")
29
+
30
+ # inherit stdout/stderr from parent...
31
+ process.io.inherit!
32
+
33
+ # ...or pass an IO
34
+ process.io.stdout = Tempfile.new("child-output")
35
+
36
+ # modify the environment for the child
37
+ process.environment["a"] = "b"
38
+ process.environment["c"] = nil
39
+
40
+ # set the child's working directory
41
+ process.cwd = '/some/path'
42
+
43
+ # start the process
44
+ process.start
45
+
46
+ # check process status
47
+ process.alive? #=> true
48
+ process.exited? #=> false
49
+
50
+ # wait indefinitely for process to exit...
51
+ process.wait
52
+ process.exited? #=> true
53
+
54
+ # get the exit code
55
+ process.exit_code #=> 0
56
+
57
+ # ...or poll for exit + force quit
58
+ begin
59
+ process.poll_for_exit(10)
60
+ rescue ChildProcess::TimeoutError
61
+ process.stop # tries increasingly harsher methods to kill the process.
62
+ end
63
+ ```
64
+
65
+ ### Advanced examples
66
+
67
+ #### Output to pipe
68
+
69
+ ```ruby
70
+ r, w = IO.pipe
71
+
72
+ begin
73
+ process = ChildProcess.build("sh" , "-c",
74
+ "for i in {1..3}; do echo $i; sleep 1; done")
75
+ process.io.stdout = w
76
+ process.start # This results in a fork, inheriting the write end of the pipe.
77
+
78
+ # Close parent's copy of the write end of the pipe so when the (forked) child
79
+ # process closes its write end of the pipe the parent receives EOF when
80
+ # attempting to read from it. If the parent leaves its write end open, it
81
+ # will not detect EOF.
82
+ w.close
83
+
84
+ thread = Thread.new do
85
+ begin
86
+ loop do
87
+ print r.readpartial(16384)
88
+ end
89
+ rescue EOFError
90
+ # Child has closed the write end of the pipe
91
+ end
92
+ end
93
+
94
+ process.wait
95
+ thread.join
96
+ ensure
97
+ r.close
98
+ end
99
+ ```
100
+
101
+ Note that if you just want to get the output of a command, the backtick method on Kernel may be a better fit.
102
+
103
+ #### Write to stdin
104
+
105
+ ```ruby
106
+ process = ChildProcess.build("cat")
107
+
108
+ out = Tempfile.new("duplex")
109
+ out.sync = true
110
+
111
+ process.io.stdout = process.io.stderr = out
112
+ process.duplex = true # sets up pipe so process.io.stdin will be available after .start
113
+
114
+ process.start
115
+ process.io.stdin.puts "hello world"
116
+ process.io.stdin.close
117
+
118
+ process.poll_for_exit(exit_timeout_in_seconds)
119
+
120
+ out.rewind
121
+ out.read #=> "hello world\n"
122
+ ```
123
+
124
+ #### Pipe output to another ChildProcess
125
+
126
+ ```ruby
127
+ search = ChildProcess.build("grep", '-E', %w(redis memcached).join('|'))
128
+ search.duplex = true # sets up pipe so search.io.stdin will be available after .start
129
+ search.io.stdout = $stdout
130
+ search.start
131
+
132
+ listing = ChildProcess.build("ps", "aux")
133
+ listing.io.stdout = search.io.stdin
134
+ listing.start
135
+ listing.wait
136
+
137
+ search.io.stdin.close
138
+ search.wait
139
+ ```
140
+
141
+ #### Prefer posix_spawn on *nix
142
+
143
+ If the parent process is using a lot of memory, `fork+exec` can be very expensive. The `posix_spawn()` API removes this overhead.
144
+
145
+ ```ruby
146
+ ChildProcess.posix_spawn = true
147
+ process = ChildProcess.build(*args)
148
+ ```
149
+
150
+ To be able to use this, please make sure that you have the `ffi` gem installed.
151
+
152
+ ### Ensure entire process tree dies
153
+
154
+ 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:
155
+
156
+ ```ruby
157
+ process = ChildProcess.build(*args)
158
+ process.leader = true
159
+ process.start
160
+ ```
161
+
162
+ #### Detach from parent
163
+
164
+ ```ruby
165
+ process = ChildProcess.build("sleep", "10")
166
+ process.detach = true
167
+ process.start
168
+ ```
169
+
170
+ #### Invoking a shell
171
+
172
+ 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.
173
+ 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`.
174
+ You can work around this by being explicit about what interpreter to invoke:
175
+
176
+ ```ruby
177
+ ChildProcess.build("cmd.exe", "/c", "bundle")
178
+ ChildProcess.build("ruby", "-S", "bundle")
179
+ ```
180
+
181
+ #### Log to file
182
+
183
+ Errors and debugging information are logged to `$stderr` by default but a custom logger can be used instead.
184
+
185
+ ```ruby
186
+ logger = Logger.new('logfile.log')
187
+ logger.level = Logger::DEBUG
188
+ ChildProcess.logger = logger
189
+ ```
190
+
191
+ ## Caveats
192
+
193
+ * 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`.
194
+ * 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.
195
+
196
+ # Implementation
197
+
198
+ How the process is launched and killed depends on the platform:
199
+
200
+ * Unix : `fork + exec` (or `posix_spawn` if enabled)
201
+ * Windows : `CreateProcess()` and friends
202
+ * JRuby : `java.lang.{Process,ProcessBuilder}`
203
+
204
+ # Note on Patches/Pull Requests
205
+
206
+ 1. Fork it
207
+ 2. Create your feature branch (off of the development branch)
208
+ `git checkout -b my-new-feature dev`
209
+ 3. Commit your changes
210
+ `git commit -am 'Add some feature'`
211
+ 4. Push to the branch
212
+ `git push origin my-new-feature`
213
+ 5. Create new Pull Request
214
+
215
+ # Publishing a New Release
216
+
217
+ When publishing a new gem release:
218
+
219
+ 1. Ensure [latest build is green on the `dev` branch](https://travis-ci.org/enkessler/childprocess/branches)
220
+ 2. Ensure [CHANGELOG](CHANGELOG.md) is updated
221
+ 3. Ensure [version is bumped](lib/childprocess/version.rb) following [Semantic Versioning](https://semver.org/)
222
+ 4. Merge the `dev` branch into `master`: `git checkout master && git merge dev`
223
+ 5. Ensure [latest build is green on the `master` branch](https://travis-ci.org/enkessler/childprocess/branches)
224
+ 6. Build gem from the green `master` branch: `git checkout master && gem build childprocess.gemspec`
225
+ 7. Push gem to RubyGems: `gem push childprocess-<VERSION>.gem`
226
+ 8. Tag commit with version, annotated with release notes: `git tag -a <VERSION>`
227
+
228
+ # Copyright
229
+
230
+ Copyright (c) 2010-2015 Jari Bakken. See [LICENSE](LICENSE) for details.